A workspace database is a Trino catalog that every engine reads live: a row you write is in the next query’s result, with nothing to run and nothing to apply first. Its owner can also write it with Trino SQL. The catalog appears once, when the database first starts serving, and the engines on its data plane mount it with one catalog apply.

When your database becomes queryable

A workspace database’s catalog is created the first time the database is serving. That happens once in the database’s life, and three things happen with it:
  1. The catalog is registered under the database’s SQL name (see The catalog name).
  2. You, the owner, get a grant on it to read it and to write it with Trino SQL.
  3. The engines on the database’s data plane need one catalog apply to mount it. Read dip db status (name a shared database), or workspace_db_list through MCP, and follow the catalog reason. While catalog_mount_in_progress is true, the engine is mounting catalogs: check again in about a minute. If no restart is running, check again after a minute; if unchanged, someone who manages the engine can apply its catalogs with your approval. A stopped engine picks up catalogs within about 10 minutes without starting. Applying restarts the engine and fails its running queries. See Catalogs and Apply. When your role allows it, use Apply on the engine page, or dip engine apply <name> --yes. Otherwise ask a tenant admin to apply the named engine’s catalogs now, using the direct engine-page link in catalog_reason. The link grants no permissions. While others keep using the engine, it will not apply the catalog on its own. With idle suspension enabled, it must have no queries for its idle timeout before it stops and picks up pending catalogs.
After that, nothing you do to the database needs an apply again. New rows, new tables and dropped tables are all visible to the next query. You write to the database through your own DuckDB, dip db exec, dip db load, an agent’s write tool, or Trino SQL: INSERT, CREATE TABLE [AS], DROP TABLE, DELETE and UPDATE (see Write with Trino SQL for what works and who may). The system.query table function isn’t available on this catalog.
An engine needs a platform update once before it can read workspace databases. Until then, applying its catalogs fails with a message naming plugin.workspacedb and telling you to re-provision. Apply the engine’s pending platform update, then apply its catalogs again. If the message says the data plane runs the stock Trino image, that plane can’t read workspace databases at all; ask the person who runs your data plane.

Is my database queryable yet?

dip db status --json and dip db list --json answer with the apply_pending field: When apply_pending is true, dip db list also checks the query engines with the same credential. If that read succeeds and the database’s plane has no engine, it says the database is ready. An engine is needed only to query it from apps or SQL tools through an engine; a data admin can create one with dip engine create --name N --plane P. The JSON database row includes engine_check: none, present, or failed. The field is absent when apply_pending is false. A failed engine read, an existing engine, or a database error keeps the conservative catalog-mount message; apply_pending itself is unchanged. apply_pending stays true until every engine on the data plane has applied the live catalog. After an upgrade, apply_pending can be true even for a database you can already query. Have someone who manages each affected engine click Apply, then check apply_pending again. Publishing an export does not make the live catalog pending again. This field describes whether the live catalog is mounted; check the engine’s pending changes for name or write-setting changes.

The catalog name

Every database gets a SQL name at creation time, derived from its display name. The console shows it next to In SQL on the database’s card. If another catalog takes that name before the database’s catalog is created, the database is given a short suffix then. The database keeps that SQL name from then on, even if its display name changes. An engine mounts the database under that pinned SQL name. The MCP workspace database tools and dip db status report which engines have mounted it. Their catalog field is the mounted name to use in SQL (<catalog>.<schema>.<table>). engine identifies the engine, and catalog_pending means the next catalog Apply is still needed. expected_catalog is the pinned SQL name to expect after Apply. When a data plane has several engines, engine and catalog describe one of them, preferring an engine that has mounted the database. When the data plane answers, dip db status --json also lists in engines each of its engines that has a name for the database, each with its own engine, catalog and mounted. Catalog names are per engine, so match the name to the engine you query. The MCP tools send the same list as engine_catalogs when more than one engine has a name for the database. In the CLI text output, the in SQL line shows the mounted name and engine, or NOT MOUNTED YET with the name to expect. Once mounted, the engine keeps the recorded catalog name across later applies, including when an older unpinned database later receives a SQL name pin. Use the reported catalog for queries on that engine if it differs from In SQL. Adding a similarly named data source does not rename it. Creating a shared database that would collide with a name already mounted on its data plane is refused; choose a different name. If an integration’s name reduces to the same SQL name, the integration’s catalog takes a suffix and your database keeps its name. See How catalogs are named.

How DuckDB column types appear in Trino

A column keeps its type in Trino, so date functions such as date_trunc('day', order_ts) work on it with no CAST. Timestamps keep the precision DuckDB stored them with, and nested columns keep their structure, so profile.address.city or element_at(attributes, 'color') works directly. A DuckDB TIMESTAMPTZ stores an instant, not the time zone it was written in, so Trino shows it in UTC. A column of a type in the last row is still there and readable as text; CAST it in your query if you need its native type. For a TIME column, cast to time(6): Trino’s plain time is time(3), which rounds 23:59:59.999999 up and wraps it to 00:00:00.000. A DuckDB JSON column is already JSON text, so json_extract and json_parse work on it as it is.

Nested columns

Inside a STRUCT, LIST, ARRAY or MAP, these types map exactly: BOOLEAN, the integer types (UTINYINT, USMALLINT and UINTEGER become the next wider signed type), FLOAT, DOUBLE, DECIMAL, VARCHAR, ENUM (as varchar), DATE, TIMESTAMPTZ and UUID. If a nested column holds anything else anywhere inside it, for example a TIMESTAMP, TIME, INTERVAL, HUGEINT, UBIGINT, BLOB, JSON or UNION, the whole column arrives as varchar holding DuckDB’s own JSON for the value, with nothing lost. Read it with the JSON functions:
One limit applies to that JSON form: a DOUBLE or FLOAT that is NaN or infinite is written as NaN or Infinity, which is not valid JSON, so json_parse fails on that value.

Share read access with a colleague

A share is a read grant the owner of a database gives one member of the tenant: SELECT on that database’s catalog and nothing else. As the owner, open the database’s card on the Databases page, choose a member under Who can read, and click Share. You can add a share only while the database is ready. A database shared with nobody says its catalog is created once the database is ready and serving; one that is already shared says sharing with someone new waits until it is serving again. Or run:
The owner of a database gets a grant on its catalog automatically, to read it and to write it with Trino SQL. Nobody else does: not people invited to write to the database, not analysts (whose read access to every table doesn’t reach a workspace database), and not admins. Until they have a grant, the database’s catalog doesn’t even appear in their SHOW CATALOGS. Write membership and read access are different decisions: inviting someone to a shared database lets them add data to it, not read it in Trino. The person must already be a member of your tenant; sharing never invites anyone. If they’ve been invited but haven’t accepted yet, that looks the same as no invitation at all, so the share is refused as … is not a member of this workspace yet until they accept. Ask them to accept their invitation, or invite them from Settings → Users if nobody has. They see the database in their own dip db list under shared with you, and read it through the engine as its catalog; it gives them no connection token and no way to write, in Trino or anywhere else. The grant covers the catalog, which is the live database, so tables you add or drop later are covered without sharing again. You can never share more than you can read yourself: if an admin has removed your own read access, sharing is refused. A database can be shared only once its catalog exists. Until then, sharing is refused with:
“<name>” has no catalog yet, so there is nothing to read; its catalog is created once the database is serving — check with dip db status <name> and try again
Every share is an ordinary governance grant. An admin sees it under Settings → Roles, in a role named wsdb_share_ followed by the database’s id with its hyphens removed, and can remove a person there. Deleting the database removes every share with it. To take access back yourself, click Remove next to their name under Who can read, or run dip db unshare <name> <email>; dip db shares <name> lists who has it. Who can read lists the shares and offers Remove whatever the database’s status is, so you can take access back while it is Failed. An admin can also grant access from Settings → Roles, by giving a role a privilege on this database’s catalog by name. A grant on every catalog (*) doesn’t reach a workspace database.

Share an imported table

dip db import finish publishes only the recipe’s named typed columns to your personal database. Check the completed import and its table before sharing:
A share covers the entire catalog, including tables added later. The importer therefore refuses a destination containing unrelated tables or views. Readers see the typed output tables and main._dip_import_control, which holds table names and opaque publication identifiers. Raw pages, local preparation files, source-account labels and rejected values stay on the importer’s machine before and after sharing. Collecting more local pages never makes them available through a share. For a data app, name this database’s catalog in its read capability. Each viewer signs in and reads with their own access; the app must not bundle copies of the import’s local files. A share does not grant a connection token or permission to write the database. If an import reports outcome_unknown, run dip db import resume --import ID before treating it as complete. It checks the recorded publication without automatically publishing again. Imports describe the saved pages; they do not freeze a changing source while you collect it. See Recover an import.

The Apply pending badge

A database’s card shows Apply pending while an engine on its data plane hasn’t mounted its catalog yet (apply_pending is true). The database is still queryable on engines that have mounted it, and once every engine has, the badge goes away.

Seeing what’s in a database

A workspace database is read where it lives, over Trino, dip db sql and the agent tools. To see its tables, use dip db status, the workspace_db_list MCP tool, or query its catalog in SQL; all of them read the live database.

Deleting a database

Delete from the database’s card, or:
This refuses without --yes and has no prompt. Deleting stops serving the database: its running instance and its tokens go away immediately, and anyone connected is disconnected. A deleted database is unreachable from the product: nothing in dip, the console or MCP can read, list or restore it. Pass --discard-data to also reclaim your tenant’s pod and disk on the plane when this was its last workspace database (see below); without it the pod stays for your next database. Deleting also removes every access grant on the database’s catalog name, whichever role holds it: your own read and write access, the grants behind its shares, and any grant an administrator added for a role or a member. Grants are tied to the catalog’s name, so without this a later catalog that took the name sales would start out readable by everyone who could read the deleted one. If revoking a grant fails, the delete does not finish and is retried, rather than leaving the grant behind. Share the new catalog again if you want those people to have access. Row filters and column masks are not removed by a delete. They stay listed under Settings → Roles, and in dip governance row-filter list and dip governance mask list, against the deleted database’s catalog name. They apply to whatever is served under that name: to a deleted catalog that a query engine has not dropped yet (an engine keeps serving a deleted catalog until it is next applied), to a connected source that is later given the name, which starts out with them, and to nothing once no engine serves the name. Only creating a workspace database removes them, and only when the new database is given that name: every row filter and column mask found on it at that moment is then cleared, for every role, so the database never starts out hiding rows or rewriting values because of rules written for one that no longer exists. dip db create and the console say so when that happened, and so does the first dip command or console visit that creates your personal database. Two things follow:
  • Setting a filter or mask on a name before you create the database does not work. The create removes it. Create the database first, then set its rules; a rule set after the create is kept.
  • A new rule set on the name while the database is being created is kept; a changed one is not. Only the rules found when the create looked at the name are removed. A rule an administrator adds in the moment after that, for a role and table that had none, is treated as theirs and stays. Changing one of the rules that was already there (the same role and table, a new expression) in that same moment does not save it: it is removed with the rest. Set a database’s rules after it has been created.
  • A leftover rule stays until someone takes the name or removes it. Remove one yourself with dip governance row-filter remove or dip governance mask remove, or under Settings → Roles.
When the name is not cleared, and the database gets a different one. A name is cleared only when Dippr can show nothing else is using it. A new database is given the name you asked for with a short id added (for example sales_1a2b3c4d), and the rules on the plain name are left exactly as they were, when the plain name carries a row filter or column mask and either of these is true:
  • a query engine has the name mounted for another catalog that the registry does not list under it (a name another registered catalog already has is simply taken: the new database gets a short id added as for any taken name, and name_withheld is not set, whether or not that name carries rules); or
  • any query engine in the workspace, on any data plane, is serving a catalog Dippr has no current name for. That is an engine that has not been applied since a catalog it serves was deleted (a connected source or a workspace database, including the one you just deleted, and including an engine that is stopped or whose last apply was refused), or an engine last applied before Dippr recorded catalog names. It does not have to be an engine this database would use: rules are matched by name across the whole workspace, and Dippr cannot tell which name the leftover catalog is served under.
dip db create and the console tell you when this happened (name_withheld under --json), because a catalog name cannot be changed afterwards. To get the plain name, delete the new database, apply every query engine (dip engine list, then dip engine apply <name> --yes), and create it again. If it is withheld again, an engine still has the name mounted for another catalog, or the rules on it are leftovers you can remove under Settings → Roles. The console keeps the explanation on the database’s card while the page is open. A name with no filters or masks on it is never withheld this way. If Dippr cannot check for rules on the name, or cannot remove them, the create is refused with nothing created; try again. Two cases are recorded in the service log only, with the line removed the row filters and column masks left on a catalog name a new workspace database is taking: a database whose catalog name is changed when it is first registered, because another catalog took its name in the meantime; and a create that removed the rules and then failed, so that the retry which succeeds finds none to report. This only touches a catalog name the deleted database actually held. If another catalog holds the database’s SQL name (for example a connected Postgres source already called sales when the database was published, so the database’s catalog was mounted under a different name), that catalog’s grants are left alone, and the grants on the name the database was mounted under are removed instead. If Dippr cannot check who holds the name, the delete does not finish and is retried. One case finishes without this cleanup: a query engine that was last applied before Dippr recorded which catalog names it mounts cannot say whose a name is, so the name is treated as possibly someone else’s and the grants on it are left in place. The delete still completes. Apply that engine once (dip engine apply <name> --yes). Then look for grants still naming the deleted catalog on the console’s Settings → Roles page, which lists each role’s grants, and remove each one there or with the role, the object and the privilege it shows, for example:
If a delete does not finish. A delete runs in the background, and a step of it can fail, for example when the data plane does not answer. The database then stays in the list marked Delete failed, with the reason underneath; dip db status <name> shows the state destroying and the same reason as its error. The reason also says what is known about the database itself: either that it is being taken out of service, or, when Dippr could not arrange that, that it may still be reachable until your workspace’s databases next change. A delete that has shown no result for more than about half an hour is reported the same way. Delete it again to retry; nothing else is needed. The card shows Delete for its owner in this state, including on a personal database, which normally has none. If your role does not allow deleting databases (the built-in viewer role does not), or you are an administrator and not the owner, use dip db delete <name> --yes from an account that may, or ask an administrator to. Until the delete finishes, a personal database in this state is not replaced by a new one. A database that is being deleted never goes back to Ready or Failed, and nothing you do with your other databases brings it back. If you deleted a database by mistake, the product can’t bring it back. Snapshots exported before this feature was removed are not deleted: they stay in your workspace’s object storage under the legacy prefix _altimate/wsdb/<tenant>/dbs/<database>/snapshots/, and are removed when the whole tenant is deleted. An administrator with access to the bucket can still read them; nothing in the product lists or restores them. The catalog leaves an engine at its next catalog apply. Until then the engine still lists it, but its queries fail, because the database no longer serves them. dip db delete waits (about a minute) and reports what happened. Dippr applies it for you when the restart affects nobody else (the rule is in Catalogs and Apply); otherwise it prints the exact dip engine apply <name> --yes command. dip db delete --yes only confirms the delete. It never restarts an engine someone else is using. --no-apply skips the wait if you don’t want to. If the database you’re deleting with --discard-data is your tenant’s last workspace database on that plane, this also tears down the plane’s shared pod and disk that every workspace database on it was running in — not just this one database’s record. This can’t happen from the console’s own Delete button, which never sets --discard-data.

Connect and write to a database

Load data with your own DuckDB, dip or an agent.

Workspace databases overview

Personal vs shared databases, and who can read what you write.