Your personal database, without a create step

You never create your own database. Opening Databases in the console, running dip db connect or dip db status with no name, or having an agent call its workspace database tool — any of these brings your personal database into being the first time, owned by you. There’s no plane to choose beyond the one already selected and nothing to name. If your first action is dip db exec, dip db load, dip db sql, or an agent’s workspace_db_write_sql, workspace_db_ingest, or workspace_db_connect call, it waits for your personal database to be ready. With an API key, dip prints “creating your personal database, about 90 seconds” while it waits. A successful agent call returns the write result or connection snippet. If creation takes longer than 90 seconds, the command or tool asks you to try again in a minute. dip db create <name> is for a shared database instead — one you own that other people can be invited to write to:
1

Open New shared database

From Databases, click New shared database. Give it a name. Its SQL name, the catalog name Trino reads it under, is derived from this name and stays stable even if you rename the database later. The dialog previews it as you type: accented and non-Latin characters are replaced by underscores, a name with nothing SQL can use becomes catalog, and a short ID is added if the name is already in use. Each of your shared databases on a data plane needs its own name: if you already have one called that (ignoring case), Dippr creates nothing and the message names the one you have by its SQL name (the CLI also shows its ID). Use that one, or pick another name.
2

Pick a data plane, if you have more than one

Leave it on the default and Dippr picks your tenant’s default plane.
3

Pick a kind, if more than one is offered

DuckDB is the only kind Dippr has shipped so far.
4

Invite the people who should write to it

Once created, invite tenant members from the database’s card. An invite is a write grant only; it does not let that person read the catalog in Trino. See who can read your database. Only people whose role allows shared databases (analyst or above) can be invited. For a viewer, share read access instead. While a row filter or column mask covers the database’s tables, only you can write to it, because write access reads the rows around those rules. See when a row filter or column mask is added.

When a row filter or column mask is added

When an admin adds a row filter or column mask to a catalog that is one of your databases, Dippr makes the database owner-only before it reports the rule as saved:
  • the people you invited to write are removed, and their connection tokens stop working;
  • their open DuckDB connections end, and so does their access through dip db exec and the MCP tools;
  • nobody can be invited, and an invited person can’t get a new token, while the rule is there.
This usually takes a few seconds. A statement that is already running finishes first, and the rule is reported as saved only after it has, so a long query can make saving the rule take longer. Your own open connection to the database also ends once, while Dippr restarts it; connect again and carry on. You keep full access. Removing the rule later does not bring the people you invited back: invite them again. If Dippr can’t confirm within about 30 seconds that those connections have ended, the admin sees an error that says the rule is saved but invited writers may still read the database directly. Dippr keeps ending the connections in the background, and saving the rule again (also with dip governance row-filter set or mask set and the same arguments) waits for it to finish. The admin sees the same error if one of those databases is deleted while the rule is being saved: deleting a database does not confirm that its open connections have ended.

Choose an import destination

dip db import finish publishes verified saved pages only to your own personal database. Use dip db status --json to find its UUID and pass it with --database. Start with an empty database and a fresh table name. An existing personal database is accepted only when every table is an import-managed output with its matching local record, plus the import control table. A shared database is refused even if you removed its writers. Another person’s personal database, an unrelated table or view, and an existing table without its matching local import record are also refused. Page collection stays local and does not require a destination, so you can finish collecting while you resolve these refusals. You cannot invite writers to a personal database. After publication, use Who can read or dip db share to give colleagues read access. A read share gives them no direct connection token or write access. See Publish saved pages for collection, publication and recovery.

The connect panel

To load a local file (CSV, Parquet, JSON or Excel) from the CLI, run dip db load --from FILE for your personal database or dip db load <name> --from FILE for a shared one. Use the connection panel or dip db connect when you need to attach the database to your own DuckDB. The dip db connect follow-up uses the database ID for shared databases, so the command still works when two databases have the same display name. Click Connect on any database you can write to. The panel shows the connection address and, once you mint one, a token:
1

Give the token a label

Something you’ll recognise later, like laptop or claude.
2

Mint it

Dippr returns two SQL statements — a CREATE SECRET and an ATTACH — composed for you and shown exactly once. Paste them into your own DuckDB as they are; don’t rewrite them.
3

Attach and write

Your DuckDB now has the database attached as a remote catalog. Load a spreadsheet, create a table, insert rows — see what works directly below.
The clear token is never shown again and never stored anywhere except as a one-way digest — losing it means minting a new one, not recovering the old one.

dip db connect

With no name, this acts on your personal database. Name a shared database instead — dip db list prints the names you can use. --print-token is required to mint a token at all — without it dip prints the database and its address only, and mints nothing: a token is a real, live credential, so dip does not create one just to show it to you redacted. With --print-token the clear token is written to stdout only — never to your shell history or a log — together with the connect snippet, both shown exactly once. Your machine needs exactly DuckDB 2.0.0, the build your tenant’s databases run. DuckDB only connects a client to a server of the same build. Any other version fails to attach, and a 1.x client fails with Serialization Error: Failed to deserialize, which looks like a fault on our side but is the version. The easiest way to get it is dip db duckdb, which downloads exactly that build, checks it and prints its path. To install it yourself:
On Windows, download duckdb-cli-windows-amd64.tar.gz (or -arm64) from https://github.com/duckdb/duckdb/releases/download/v2.0.0/, unpack it with tar -xzf and put duckdb.exe on your PATH.
A plain pip install duckdb installs a 1.x release, which cannot attach. Pin the version shown above. dip db connect checks the duckdb your PATH resolves to and, when it is a different build, prints its version and path. That is how it catches a pyenv or asdf shim that shadows another install.

What your own DuckDB will let you write

Once attached, you work with the database the way you would with a local one. Reads, writes and transactions all run as you type them:
Load a spreadsheet, then fix a column
A BEGIN … ROLLBACK from your own client rolls back, and nobody else sees the rows until you commit. Your client sees the tables that existed when it attached. A table someone else creates later (another member, dip db exec, an agent) fails with Catalog Error: Table with name … does not exist until you run DETACH mydb and attach again. dip db status always shows the current tables. From Python, fetch the result of every write. DuckDB streams results, so a write is finished when its result is read. End each statement with .fetchall(), for example con.execute("INSERT INTO mydb.sales VALUES (1, 'EMEA')").fetchall(). The DuckDB command line prints every result, so it is not affected.
An agent writing through the workspace_db_write_sql tool needs no DuckDB at all: the statement runs on Dippr’s own connection to the database, and each call is its own transaction.
dip db exec is the CLI form of that same path: one statement per call, run on Dippr’s own connection, with no attached client:
Write one statement without attaching DuckDB
On this path the query(), query_table(), json_execute_serialized_sql(), histogram() and histogram_values() table functions are refused, because they read a table named by a string built when the statement runs. Name the table directly instead. The histogram() aggregate, as in SELECT histogram(amount) FROM sales, still works in a plain SELECT. Inside CREATE TABLE ... AS, INSERT ... SELECT or PIVOT it is refused too, so run the aggregate as a SELECT first. It works on your ordinary dip login or on an alt_ key in $DIPPR_API_KEY. On a login, dip gets a token for that data plane from your login, with no browser, and gets a new one when it expires. This works on every data plane your tenant has. If your workspace cannot issue that token yet, the first dip db exec opens one browser consent bound to that data plane’s MCP endpoint instead, and that consent covers every exec afterwards. The token carries three capabilities, because these are the calls the command makes on the plane:
  • workspace_db:write, for the write itself;
  • query_engines:execute_sql, so dip can look a named database up to its unique id before writing (the lookup uses the plane’s workspace_db_list tool, which requires it). Your dip login already carries this capability for the workspace, so the consent adds nothing you haven’t approved;
  • metadata:read, which the plane needs to find your database for you.
dip login already lets your login write databases (workspace_db:write) and read their records back (metadata:read, which dip db status and dip db list use). If an older dip, or dip login --scope, gave you a narrower consent, the next exec notices that the saved consent is missing a capability and asks you once more. Rows written this way are in the next Trino query’s result, once the engines have mounted the database’s catalog (see When your database becomes queryable). For more than a few thousand rows, use dip db load instead: thousands of exec calls is far slower.

Loading files with dip db load

dip db load loads a file, a set of files, or the result of a query into a table, using the DuckDB built into dip. It reads the files on your machine and streams the rows into your database, so you install nothing and the files don’t pass through any other storage:
Load local files into a table
It reads CSV, Parquet, JSON and Excel files. See Load data for previewing a load, loading the result of a query, and what to do when a load fails. It needs only the one-time consent every dip db write asks for, not the data plane consent above. The loaded rows are queryable in Trino as soon as they land: engines read the database live, so nothing else has to happen before the next query.

Write with Trino SQL

A workspace database’s catalog takes writes as well as reads, so you can fill it from any other catalog your engine reaches without leaving SQL. Run the statement in the SQL workbench or from any Trino client connected to the engine (see Connect to an engine), against the database’s catalog name:
Land a federated result in your database
Who can write. A database’s owner can, automatically: the owner’s grant on its catalog covers reading and writing it. Anybody else needs a grant that names this database’s catalog, its schemas or its tables: an admin gives one under Settings → Roles (INSERT, UPDATE, DELETE, CREATE or DROP). Grants that cover every catalog don’t count here, and being a Data admin or Account admin isn’t enough on its own, so a workspace database is never written by someone its owner and admins didn’t choose. Members invited to write it with their own DuckDB don’t write it through Trino unless they get such a grant. A share gives read access only. The rows you read into a write are still filtered and masked for you, exactly as they are when you query them. When writes are on. A database’s catalog takes writes only once the platform has set up its owner’s grants on it, and until then every write is refused with Access Denied: … this workspace database catalog is read-only, while reads keep working. For a new database that happens by the time it first serves. A database created before writes through Trino existed gets it within half an hour of the upgrade, and each engine picks it up the next time it applies its catalogs. The database’s row on the Databases page says why writes are off, if they are:
  • its catalog is not named <name>: another catalog already holds the database’s SQL name, so the database is readable under the name its engine shows, but writing it through Trino stays off. Rename or remove the other catalog, or write with your own DuckDB or dip db exec.
  • its owner’s role no longer carries the workspace-database marker: an admin removed that grant or the owner’s role. Writing it through Trino stays off until the grant is back, because without it broad grants would reach the database.
An engine running an image from before writes through Trino existed refuses to apply a catalog that takes writes, and says so on the engine’s page; applying the pending platform update fixes it. A write lands whole or not at all. The rows of an INSERT or CREATE TABLE AS reach the table in one step at the end of the query. A write that fails, is cancelled, or whose engine restarts partway through leaves the table exactly as it was. Anything it had already copied is cleaned up automatically. If the connection to the database drops while the write is finishing, the error says the write may or may not have been committed: check the table before you run it again, or the rows may be written twice. What works: Anything else is refused before it changes a row:
  • MERGE, an UPDATE that computes the new value (SET amount = amount * 2), and a DELETE or UPDATE whose condition uses a function, a timestamp column or an OR across two columns all fail with This connector does not support modifying table rows. Run those with your own DuckDB or dip db exec.
  • ALTER TABLE, renaming, TRUNCATE, views and CREATE SCHEMA or DROP SCHEMA are denied. Use your own DuckDB or dip db exec for them.
  • The system.query table function isn’t available.
  • A column of a type that Trino shows as varchar although DuckDB stores something else (for example TIME, UUID, BLOB or a nested type) can’t be written from Trino.
  • A database over its storage quota refuses writes that add data. The write is refused with workspace database catalog '<catalog>' refused the write, and nothing was changed, and the table is unchanged. Reads keep working. See When a database is full to free space.
  • The same message appears when a statement names a table or column called load, copy, attach, detach, install, export, import, pragma, call or checkpoint, or one containing _auth (including pr_author and last_author): rename the column. The database also reserves _snapshot_export, CREATE SECRET, and statement-leading SET, RESET or USE. Statement text is screened, including literals and comments. Bound row values are separate from statement text. A generic Authorization failed does not establish quota exhaustion.
Timestamps keep their precision: a timestamp(3) column is created as DuckDB TIMESTAMP_MS, timestamp(6) as TIMESTAMP and timestamp(9) as TIMESTAMP_NS, and they read back the same way. A write through Trino copies rows into the database at roughly ten thousand rows a second. For loading a large file, dip db load is faster. Agent tools don’t write through Trino: run_sql only reads. An agent writes with workspace_db_write_sql (see The agent tools).

Listing tables

The tables you see in the console or from dip db status come from the data plane, not from your attached client. Your client lists the tables that existed when it attached, and misses any created since, so don’t rely on it to tell you what’s in the database right now. Use dip db status or an agent’s list tool instead. The console’s database card no longer browses tables; dip db status and workspace_db_list list the live tables. dip db status reads that list from your own data plane’s MCP endpoint — the same place an agent’s list tool reads it. It needs two capabilities:
  • metadata:read — reads the record (state, size);
  • query_engines:execute_sql — reads the table list from the plane.
On your dip login, you don’t need an alt_ key. Your login carries metadata:read, so the record prints. A session from an older dip, or one narrowed with dip login --scope, gains it with its first dip db write; if dip db status is the first thing such a session runs, it asks for that same one-time approval in your browser itself, then prints the record. The table list needs a token for the data plane itself, because the plane’s MCP endpoint only accepts tokens issued for it and never your login token. dip db status gets that token from your login, with no browser. If your workspace cannot issue one yet, it uses the plane consent you already gave dip db exec (or dip mcp login), and without one the record still prints and the tables line says to run dip db exec once. A status command never opens your browser for the table list. With an alt_ key in $DIPPR_API_KEY, mint it with both capabilities:
If your key has metadata:read but not query_engines:execute_sql, the record still prints and the tables line names exactly the capability to add — it never tells you to re-run dip db status. If the data plane is genuinely unreachable, that line reports the endpoint and operation that failed, so you know it’s connectivity rather than a missing table. When the read fails, dip db status says could not read the table list. Its --json report has tables_unavailable: true, an empty tables array, and one tables_error with the message and any request ID. An empty list, tables: [], means the read succeeded and found no tables. There is no table_count field and dip db list shows no table count: the live list is tables. Advice to grant consent appears only for authentication or missing-capability errors. If the catalog mount state could not be read either, catalog_pending is null; this does not mean the database is unmounted. With no <name>, dip db status acts on your personal database, which — like dip db connect — also needs workspace_db:write (the personal database is yours to create on first use); a named shared database needs only metadata:read for the record.

Revoking a token

Revoke a token from the connect panel, or with:
A revoked token stops authenticating new connections once the database picks up the revocation, and a session already attached with it may stay attached. Revocation alone only stops new connections: a client already attached keeps reading and writing, and there is nothing available to end that one session. So revoking also asks the platform to restart the database’s instance, which is meant to end those sessions — but nothing confirms the restart reached them, and an attached session has been seen to keep reading and writing after a revoke. When the restart does happen, it disconnects everyone currently attached to that database, not only the token’s owner. While it restarts, a query that reads the database through a query engine (run_sql, a data app) fails with workspace database catalog '<catalog>' is unreachable (its database is restarting or was deleted); retry shortly (through MCP on an engine that has not been upgraded yet: a workspace database this query reads is unreachable …). Retry after a few seconds; the same error right after dip db delete means the database is gone. A write that lands in that window still fails with the engine’s own error text for now.
Besides a session that stays attached, a revoked token can still authenticate a new connection for a short window right after revocation, while the restarted instance catches up with which tokens are still valid. Don’t treat a revoked token as immediately unusable if that timing matters — for example, during an incident — and restart the instance again, or wait, before relying on it being dead.

Idle connections are closed

A connection that sits idle for a long time (by default an hour) may be closed to free the resources it holds — an abandoned session should not keep a slot forever. Your data is untouched; just attach again with the same connect string, or your tool reconnects on its next query. An instance is only recycled when every connection on it is idle, so a running query is never interrupted. A connection whose client has gone away, because the process was killed or the network dropped, is usually closed about two minutes after the client stopped, and any statement it left unfinished is rolled back. Only that connection is closed. What keeps a connection open is its heartbeat. While it is attached, a client tells the database it is still there about every twenty seconds, and dip, DuckDB and the query engine all do this on their own, including while a long statement runs. A client that keeps doing so keeps its connection however long its query takes. A client that cannot send a heartbeat for longer than a minute, for example because the machine went to sleep or lost its network, loses the connection and has to attach again.

What happens to my database when Dippr is updated?

Each workspace database restarts once after an update to Dippr, so it runs the new version. This happens within a few minutes of the update and does not wait for the database to be idle. Your data is untouched. Every existing database restarts, including one with no tables in it. The only exception is a workspace with no databases left on that data plane, for example after its last one was deleted: nothing is served there, so nothing restarts, and the next database created there runs the new version. While it restarts:
  • Every open connection to the database ends. Attach again with the same connect string, or your tool reconnects on its next query.
  • A statement or load running at that moment is cut off, and you may not get its result. It may or may not have been saved. Once the database answers, check what landed before running it again, as described in When a load fails, so an append is not added twice.
  • A query through a query engine fails with workspace database catalog '<catalog>' is unreachable (its database is restarting or was deleted); retry shortly. Retry after a few seconds.

The agent tools

An agent working in your tenant’s data plane can reach a workspace database through MCP tools, without a console session. The main ones: Write access to workspace databases is a capability an agent’s connection has to be granted separately — it doesn’t come bundled with ordinary read access, and a connection without it gets a clear message saying so rather than a silent failure.

Workspace databases overview

Personal vs shared databases, and how Trino reads them.

Query and share a database

Query it live from Trino and share read access.