Upgrading to 0.12

Coming from 0.11.0, apply From 0.11.0 to 0.12.0 and then From 0.12.0 to 0.12.1. Coming from 0.10.x, start with Upgrading to 0.11.0.

From 0.12.0 to 0.12.1

Checklist

Before upgrading

1. Back up the control-plane database. Liquibase changeset 0057 runs at boot. It makes a change of a database's object-store keys move every tenant's policy version.
2. Give a login to every database on another Postgres server. QoD's login is no longer filled in for a metastore that names another server than QoD's own, so a database with no login of its own stops connecting at the next node start or restart. Have a superuser set its pgUser and pgPassword with qod database update, or leave pgHost and pgPort out to use QoD's server. Hosts are compared as text: with the default localhost, a row naming 127.0.0.1 counts as another server. A stored row with whitespace in pgHost, pgPort, pgUser, dbName or schemaName also counts as another server.
3. Check every superuser initSql that sets temp_directory. See Spill folders: a node can now refuse to start where it started before.
4. Limit keys on shared buckets. See Tenants on a shared bucket.
5. Rename pools that differ only by _ and -. See Node ids and per-pool Secrets.
6. Check QOD_NODE_BIN. qod-node now requires --spill-dir and --node-dir in serve mode, which this release's spawn scripts pass. A QOD_NODE_BIN naming an earlier build, or a stale native/qod-node/build, fails every spawn with unknown option '--spill-dir'. Rebuild it, or unset QOD_NODE_BIN to use the bundled binary.
7. Recompile modules that call PoolSupervisor.createTenantDb. It now states writerTrusted. With false, it names no server and no path of its own, as a tenant admin.

While upgrading

8. Upgrade the node image and the fleet servers with the manager, and restart every node.
9. Under HA on Kubernetes, finish the rolling upgrade before stopping or deleting a pool: a replica still on 0.12.0 removes only the old Secret names.

Spill folders

A node whose superuser initSql sets temp_directory now makes a folder of its own under that path, and refuses to start rather than spill elsewhere. The error is cannot create the spill directory under <folder>: ..., naming the path at fault. It refuses:

• an existing folder of the path, a symbolic link followed in it, or a folder or link on that link's real path, owned by a user other than root and the node's own. Examples are a group-writable folder shared with colleagues, an NFS export with root_squash that shows nobody, and a host folder bind-mounted into a rootless container or under userns-remap, where a host-root folder also shows nobody;
• with a node running as root, a folder of the path owned by any non-root user;
• a path that cannot be created (permission, a read-only filesystem, a component that is a file);
• on Windows, any symbolic link, junction or mounted folder in the path;
• a path holding a line break.

Point temp_directory at a folder that root or the node's OS user owns all the way up, or drop the SET to keep the default spill folder. See Temp directory and spilling.

Node ids and per-pool Secrets

A node keeps its stored id across every restart, and a new slot takes the new form, quack--<tenant>--<db>--<pool>--<index>, so one pool can show both.

On Kubernetes, a running pod reads its per-pool Secrets under their old names until the manager next starts it, which moves it to the new ones. A container restart does not do that. The old names go once no pod reads them.

Two pools that already read alike come apart at the first boot: a node keeps its stored id, and a pool left with no node row starts in the new form, on the fleet runtime once a server is free. On Kubernetes, a running pod keeps reading the old-named Secrets, which can hold the other pool's values, until the manager next starts it.

Two pools of one database that differ only by _ and - (eu-west, eu_west) read alike in the new form too, and no restart ends it. On the local and fleet runtimes a fresh slot takes the other's id again, and on Kubernetes each start writes the per-pool Secrets both read. Recreate one under another name, and on Kubernetes then restart the other's nodes.

Tenants on a shared bucket

A database holding complete keys of its own no longer blocks other tenants' users. Its data folder counts against the users of its own tenant only, for 400 scope_in_data_folder and for a statement naming a URL there.

On a bucket tenants share, a user's own keys now reach another tenant's folder holding its own keys wherever the store allows them, for reads and writes. The store's key permissions are what protects that folder, so give each tenant keys limited to its own prefix.

New names

Names that exist keep working, and a manifest import keeps importing them, with one ERROR per name. A fresh node of such a name takes a hashed id. New names follow these rules:

Name	Rule	Refusal
Database or pool	May not hold __ nor start or end with _	400 invalid_name
Pool	1 to 63 letters, digits, _ or -, starting with a letter, not ending with -, holding none of --, _- or -_	400 invalid_name
Pool	Reads the same as another pool of its database once _ becomes -	409 pool_reads_alike
Tenant	Letters and digits only, starting with a letter. This applies to a superuser too	400 invalid_id

A metastore pgUser or pgHost holding whitespace, or a pgHost holding any of ? & = #, is refused on every write, a manifest import included.

What a tenant admin can no longer do

These writes answer 403 superuser_required with nothing written. Existing rows are not judged and keep working, and an edit that leaves the value as stored still works.

• Add, change or remove pgHost, pgPort, pgUser, pgPassword or dbName on a database, on REST or MCP. A password sent counts as a change whatever it says, and rotating the password of a database on another server is a superuser's job. The dbName of a duckdb-file database stays free.
• Set a dataPath other than a remote path (s3://, s3a://, r2://, gs://, az://, azure://, abfss://) with complete explicit keys in objectStore, or set metastore.dataPath. Leave dataPath out of a DuckLake database and QoD places it.
• Name a bucket's or a container's root, or a path with a . or .. segment, a glob or an escape in it.
• Change objectStore, except on a database holding complete keys of its own, which stay complete. Any change to them needs the scheme's secret sent in the same request.
• Change the connection or config of a federated source holding a secret, or make a read-only one holding a secret writable. A superuser makes the change, or delete the source and create it again with its secrets.

GET /api/database/metastore-defaults and MCP metastore_defaults now answer only a superuser.

A tenant admin's database/create on QoD's server no longer takes over a Postgres database holding anything: it answers 409 database_name_taken, and an empty one is reused. A named remote path at, under or above a folder the location rules deny answers 409 data_path_taken.

Postgres servers other than QoD's

• database/create and database/update answer 400 own_login_required to a superuser's metastore whose pgHost or pgPort differ from the default's without its own pgUser and pgPassword. A stored password does not follow a change of host or port: send it again.
• QoD creates and drops no Postgres database on another server. The catalog database must exist first (400 catalog_database_missing names it), database/delete and a tenant delete leave it, logged at ERROR, and the database cannot be branched (400 branch_own_server).
• database/delete and a tenant delete drop a Postgres database only for a DuckLake row.

What only a superuser now sees

/api/pool/list, GET /api/pool/{tenant}/{tenantDb}/{pool}/status, /api/database/list, the answers of database create and update, and MCP get_pool_status, list_pools and list_databases show anyone else no pgHost, pgPort or pgUser of a database on QoD's server, and nothing else the manager's defaults filled in, such as an inherited schemaName. A database on another server still shows its own.

Other changes

• A DuckLake create naming no path no longer answers 400: the database gets a folder of its own beside the default data path. With no default data path, or one that is a bucket's root, it answers 400 invalid_contract.
• A node's quack_azure secret, the manager's QOD_AZURE_CONNECTION_STRING, exists only for a database with no objectStore, and is scoped to its data path and its branches' prefix. A superuser reading any other az:// path creates a secret of their own.

From 0.11.0 to 0.12.0

Before upgrading

1. Back up the control-plane database. Liquibase changeset 0056 runs at boot and adds the columns of a three-way merge to qodstate_branch_merge.
2. On Kubernetes, read your maintenance policies. No maintenance node had ever started on a real cluster, so a database with maintenance enabled runs it for the first time after this upgrade. Its first runs do all the snapshot expiry, compaction and file cleanup that never ran.
3. On an OPA tenant, read any rule keyed on columns. A branch's change count now reads rowids only, so OPA is asked about that statement with columns: [], and a rule that refuses by column no longer refuses a count. To keep counts from a user, refuse on the table.

After upgrading

4. Propose open branch merges again. A proposal from before the upgrade is refused 409 proposal_stale on merge.
5. Under HA, finish the rolling upgrade before merging a branch: a replica still on 0.11.0 serves its fast-forward merge on a row a new replica proposed.

Branch merges

• POST /api/branch/merge requires proposalId and qod branch merge requires --proposal. The approver names the proposal they read, and another one in its place is 409 proposal_replaced. One that has already merged is 409 already_merged, naming the main snapshot and the tag.
• A merge refuses 409 proposal_stale when the branch moved since the proposal, where it used to take the newer head. Proposing a branch that is already proposed replaces its open proposal, and 409 already_proposed is gone.
• A table with a column named snapshot_id no longer merges (422 merge_unsupported): rename the column.