Your personal database, without a create step
You never create your own database. Opening Databases in the console, runningdip 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 execand the MCP tools; - nobody can be invited, and an invited person can’t get a new token, while the rule is there.
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, rundip 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.
dip db connect
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:
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.
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
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
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’sworkspace_db_listtool, which requires it). Yourdip loginalready 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
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
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 ordip 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.
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, anUPDATEthat computes the new value (SET amount = amount * 2), and aDELETEorUPDATEwhose condition uses a function, a timestamp column or anORacross two columns all fail withThis connector does not support modifying table rows. Run those with your own DuckDB ordip db exec.ALTER TABLE, renaming,TRUNCATE, views andCREATE SCHEMAorDROP SCHEMAare denied. Use your own DuckDB ordip db execfor them.- The
system.querytable function isn’t available. - A column of a type that Trino shows as
varcharalthough DuckDB stores something else (for exampleTIME,UUID,BLOBor 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,callorcheckpoint, or one containing_auth(includingpr_authorandlast_author): rename the column. The database also reserves_snapshot_export,CREATE SECRET, and statement-leadingSET,RESETorUSE. Statement text is screened, including literals and comments. Bound row values are separate from statement text. A genericAuthorization faileddoes not establish quota exhaustion.
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 fromdip 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.
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:
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: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.
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, anddip, 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.
Related
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.