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:- The catalog is registered under the database’s SQL name (see The catalog name).
- You, the owner, get a grant on it to read it and to write it with Trino SQL.
- The engines on the database’s data plane need one catalog apply to mount it. Read
dip db status(name a shared database), orworkspace_db_listthrough MCP, and follow the catalog reason. Whilecatalog_mount_in_progressistrue, 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, ordip engine apply <name> --yes. Otherwise ask a tenant admin to apply the named engine’s catalogs now, using the direct engine-page link incatalog_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.
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 anddip 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 asdate_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 aSTRUCT, 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:
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:
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:
“Every share is an ordinary governance grant. An admin sees it under Settings → Roles, in a role named<name>” has no catalog yet, so there is nothing to read; its catalog is created once the database is serving — check withdip db status <name>and try again
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:
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:--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 removeordip governance mask remove, or under Settings → Roles.
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_withheldis 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:
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.
Related
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.