Warehouse

Every paid workspace has one SQL warehouse. Pipelines land typed tables in it, and agents and people run full SQL against it. The Warehouse page lists what each plan includes. Free workspaces have no warehouse, and SQL analytics answers that it needs a paid plan.

Under the hood a warehouse is a DuckLake: a Postgres catalog plus Parquet files under your workspace's own prefix in SchemaBounce object storage, on shared compute. There is nothing to size, patch or keep warm.

Query it

From the console

Open the SQL Workbench in the console and run SQL. It is the same warehouse your agents use.

From the MCP

Call the sb_adl tool with action: duckdb_query:

{
  "action": "duckdb_query",
  "sql": "SELECT table_schema, table_name FROM information_schema.tables ORDER BY 1, 2",
  "max_rows": 100
}

max_rows defaults to 100 and caps at 10,000. The workspace is always the one your credential is bound to. A workspace_id argument cannot redirect the query. Reads need the adl:view permission. Statements that change data need adl:manage.

From an agent

A hosted agent with the warehouse tool runs the same SQL and gets the same rows. Agents hold no warehouse credentials.

What tables exist

Run SHOW TABLES, DESCRIBE or query information_schema to see them.

Schema	Contents	Access
sb_pipelines	Typed tables your pipelines land	Read only
your own	Tables you create	Read and write
sb_platform	Metadata about your workspace: agent runs, tool calls, credits, usage and warehouse queries. Never conversation content.	Read only

You can copy from sb_pipelines and sb_platform into your own tables. You cannot write into them. A query never reads another workspace.

Writes and approvals

CREATE, INSERT, UPDATE or DELETE with a WHERE, MERGE and ALTER run on their own for a caller with adl:manage.

A destructive statement from an agent waits for a person to approve it first: DROP, TRUNCATE, DELETE or UPDATE with no WHERE, ALTER ... DROP COLUMN, and CREATE OR REPLACE. The approval is one audited record, answerable in the Inbox. Time travel restores a table after a destructive change.

ATTACH, INSTALL, LOAD, SET, COPY and file or URL reads are refused. Send one statement per call when it changes data.

What it costs

Each paid plan includes analytics hours and storage every month, listed on the Warehouse page. Past that:

• Compute bills per second of query execution at the live rate, with a one second minimum. Ingest, compaction and idle time are not billed, and neither is a query that fails on our side or is refused for capacity.
• Storage bills per GB-month past your plan's allowance.

Both draw from your credits. With no credits, queries stop and new ingest pauses. Nothing is deleted. Buy credits on the workspace's billing page.

Freezing and deletion

If you downgrade to Free or cancel, the warehouse freezes at once: no queries, writes or ingest. Your data stays for 30 days, and the owner and billing members get notices at day 0, 23 and 29. Upgrade inside the window and the warehouse comes back as it was. After 30 days it is deleted. A failed card payment changes nothing while Stripe retries.

Security

Every data file has its own encryption key. Nothing rests unencrypted in the catalog, the catalog volume and the bucket are encrypted at rest, and backups are encrypted under SchemaBounce's KMS key. SchemaBounce manages the encryption for every warehouse. Customer-held keys cover your agent data, not the warehouse.

BI tools connect over the Postgres protocol. That endpoint is built and not open yet, so nothing here depends on it.

API

The warehouse has four routes under /api/v1/workspaces/:id/agent-data-layer/duckdb/. Authenticate with a service account's bearer token, which you get from POST /api/v1/oauth/token. The workspace is always the one in the path and the token. A request body has no workspace field. Request and response fields are camelCase.

Method and route	What it does	Permission
POST .../duckdb/query	Runs one read statement.	adl:view
POST .../duckdb/classify	Names the class of a statement without running it. Free, and answers on any plan.	adl:view
POST .../duckdb/execute	Runs one statement that reads or changes data.	adl:manage
GET .../duckdb/warehouse	Returns the warehouse state.	adl:view

Query and execute

Both take { "sql": "...", "params": [], "limit": 100 }. limit defaults to 100 and caps at 10,000. execute also reads confirmDestructive, which is ignored by query. Send true only after a person confirmed that exact statement.

{
  "columns": ["table_schema", "table_name"],
  "rows": [["sb_pipelines", "orders"]],
  "rowCount": 1,
  "truncated": false,
  "limitApplied": 100,
  "maxRows": 10000,
  "statementClass": "read"
}

statementClass is read, write or destructive. A write or destructive result also carries action, a short phrase naming what the statement did. query refuses a statement that changes data with a 403.

Classify

Takes the same body and returns statementClass (read, write, destructive or refused), action, detail and statements, the number of statements in the text.

Warehouse state

Returns managed, state (none, provisioning, active, frozen, deleting or deleted) and entitled. It adds provisionedAt, frozenAt, deleteAt, seededAt and retentionDays when they apply.

Errors

Every error body has error, code and message.

Status	Code	Meaning
402	PLAN_FEATURE_REQUIRED	The workspace is on Free or eval. Upgrade to a paid plan.
402	WAREHOUSE_FROZEN	The warehouse is frozen after a downgrade or cancellation. Upgrade inside the 30 days to restore it.
402	MANAGED_INFERENCE_REQUIRES_CARD	No credits left for usage past the plan's allowance. Buy credits.
409	DUCKDB_PROVISIONING	The warehouse is still being set up. The response has Retry-After: 10.
409	DUCKDB_CONFIRMATION_REQUIRED	A destructive statement reached execute without confirmDestructive. Nothing ran. The body names what it would do.
403	DUCKDB_STATEMENT_REFUSED	The statement is never run here, or it changes data on the read route.
400	DUCKDB_QUERY_FAILED	The engine rejected the statement. message is its sentence.
413	DUCKDB_RESULT_TOO_LARGE	The result is too large. Narrow the query or lower limit.
429	DUCKDB_BUSY	The warehouse is at capacity. Nothing ran. Retry after the Retry-After seconds.