Skip to main content

database

db.create​

Create workspace database

Effects: write

Provision this workspace's own database (one per workspace). Returns the connection string and password ONCE — relay them to the user immediately; they cannot be retrieved later. Errors if the workspace already has a database. Use db.schema / db.query / db.execute to work with it afterwards.

Arguments​

No arguments.

db.execute​

Write to workspace database

Effects: write

Run SQL (CREATE TABLE / INSERT / UPDATE / DELETE / ALTER) against this workspace's own database. Use db.schema first to see what exists, and db.query to read.

Arguments​

ArgumentTypeRequiredDescription
sqlstringyesSQL DDL/DML, e.g. CREATE TABLE records (id serial primary key, name text)

db.mirror​

Workspace database mirror

Effects: write

Change this workspace's read-only platform-data mirror (views in schema dialogbrain_v1 of its own database, read with db.query). action=enable migrates the mirror schemas and takes a full snapshot (needs a database from db.create; admin/owner only). It is NOT idempotent: every call re-migrates and re-snapshots, so it is also how a failed mirror is recovered. The work runs in the background and the call returns at once with status 'snapshotting'; poll db.mirror_status until it is healthy. action=resync reconciles with the platform now (admin/owner, only when enabled and not snapshotting; also runs in the background). Example once healthy: db.query sql="SELECT id, title, last_message_preview FROM dialogbrain_v1.threads WHERE channel_account_id = <your channel account id> AND last_message_is_outgoing = false".

Arguments​

ArgumentTypeRequiredDescription
actionstringyesenable | resync

db.mirror_status​

Workspace database mirror status

Effects: read

Show whether this workspace's read-only platform-data mirror is on: enabled, status, synced_at, last_error, and the views in schema dialogbrain_v1 that db.query can read (threads, messages, contacts, entities, channel_accounts, files, agents, calls, campaigns, campaign_items). Example once healthy: db.query sql="SELECT id, title, last_message_preview FROM dialogbrain_v1.threads WHERE channel_account_id = <your channel account id> AND last_message_is_outgoing = false". Turn it on with db.mirror.

Arguments​

No arguments.

db.query​

Query workspace database

Effects: read

Read from this workspace's own database. Pass either a natural-language question (e.g. 'how many records were added this week') or a raw SQL SELECT. Read-only; returns rows plus a chart hint.

Arguments​

ArgumentTypeRequiredDescription
questionstringnoNatural-language question about the data
sqlstringnoRaw SQL SELECT (alternative to question)

db.schema​

Workspace database schema

Effects: read

List the tables and columns of this workspace's own database. Call this before db.query or db.execute to learn what exists.

Arguments​

No arguments.