docs(db): describe the plugin SQL layers and the refused restore roles

The Postgres wiki page and the plugin author guide list what the plugin
SQL guard now refuses and the two layers behind it, and the wiki and
server/CLAUDE.md name every kind of role a restore refuses, including
CREATEROLE on PostgreSQL 14 and 15, which the managed postgres role on
such a server holds.
This commit is contained in:
Maurice
2026-11-17 20:45:53 +01:00
parent 2983971c8b
commit a9cdb2f91c
3 changed files with 17 additions and 8 deletions
+10 -1
View File
@@ -206,7 +206,16 @@ What changes on Postgres:
temporary tables, `SELECT ... INTO`, `COPY`, `SET`, transaction control (`tx()` makes a
batch atomic), `WITH RECURSIVE`, and no `ALTER` of a schema, owner or tablespace.
Dollar-quoted strings, `E'...'` and `U&'...'` are refused; write plain single-quoted
strings.
strings. The words `TEMP` and `TEMPORARY` are refused anywhere outside a string (quote a
column named `"temp"`), and so is `INTO` anywhere but `INSERT INTO` and `MERGE INTO`.
Numbers are decimal: `0x1F`, `0o17`, `0b1` and `1_000` are refused, because Postgres
before 16 reads them differently. Outside strings, quoted names and comments, whitespace is
space, tab, newline, carriage return or form feed; any other control character or non-ASCII
whitespace (a no-break space, a byte order mark) is refused. A `--` comment ends at a
newline or a carriage return.
- **One statement at a time.** Each statement goes to Postgres on its own, over the protocol
that runs exactly one: `query` and each `tx` entry take one statement, and an `exec`
script is split at its semicolons and sent statement by statement.
- **Limits**: the same row cap and quota as on SQLite. The 2 s budget is a
`statement_timeout` here, so it also stops a single long statement, and an `exec` with
bound args is held to it too; `migrate` stays untimed. A write that takes your schema past
+2 -2
View File
File diff suppressed because one or more lines are too long
+5 -5
View File
@@ -14,7 +14,7 @@ Postgres does not make TREK scale out. TREK still runs as one process. See [Limi
- **PostgreSQL 14 to 18.** TREK refuses to start on any other server version, before it writes anything.
- **An empty database dedicated to TREK.** TREK creates its schema in an empty database. It refuses a database that holds tables it did not create, and a restore replaces everything in the schema it loads into. Do not share the database with another application.
- **A role that is not a superuser,** which owns the database or can create objects in its schema. A backup archive is a SQL script run by this role during a restore, so a role with fewer privileges limits what a crafted archive can do. A restore refuses a superuser and a role that holds `pg_execute_server_program` or `pg_write_server_files`, and TREK warns about such a role when it starts. See [A role that is not a superuser](#a-role-that-is-not-a-superuser).
- **A role that is not a superuser,** which owns the database or can create objects in its schema. A backup archive is a SQL script run by this role during a restore, so a role with fewer privileges limits what a crafted archive can do. A restore refuses a role that could reach the database server from SQL (a superuser, a member of a superuser role, a role that holds `pg_execute_server_program`, `pg_read_server_files` or `pg_write_server_files`, and on PostgreSQL 14 and 15 a role with CREATEROLE), and TREK warns about such a role when it starts. See [A role that is not a superuser](#a-role-that-is-not-a-superuser).
- **ICU support in the server.** The schema creates the collation `nocase` with `provider = icu`, so the server must be built with ICU. The official `postgres` images include it.
- **PostgreSQL client tools** (`pg_dump`, `pg_restore`, `psql`) for backups, restores and the copy TREK takes before a migration. The Docker image installs the version 18 client, which works with every supported server. A client works with servers up to its own major version, so a client outside the image must be at least as new as the server; TREK refuses an older one with a message that names both versions. See [Configuration](#configuration).
- **Client tool versions that carry the CVE-2025-8714 fix.** A restore refuses `pg_restore` or `psql` older than 18.0, 17.6, 16.10, 15.14 or 14.19.
@@ -78,7 +78,7 @@ CREATE DATABASE trek OWNER trek;
ALTER SCHEMA public OWNER TO trek;
```
Then use `postgres://trek:<password>@<host>:5432/trek` as `TREK_DB_URL`. A restore refuses a role that is a superuser, or that holds `pg_execute_server_program` or `pg_write_server_files`, because a crafted archive could use those to run commands or write files on the database server. TREK also logs a warning about such a role when it starts.
Then use `postgres://trek:<password>@<host>:5432/trek` as `TREK_DB_URL`. A restore refuses a role that is a superuser or a member of one (`SET ROLE` would make it a superuser), that holds `pg_execute_server_program`, `pg_read_server_files` or `pg_write_server_files`, or, on PostgreSQL 14 and 15, that has CREATEROLE (there it may grant itself those roles). A crafted archive could use any of these to run commands on the database server or to read or write its files. TREK also logs a warning about such a role when it starts.
TREK creates its tables in the role's current schema, normally `public`. A role whose `search_path` points at a schema of its own works too: TREK keeps its tables and its migration history there, and backups and restores cover that schema.
@@ -177,7 +177,7 @@ Restoring a backup on Postgres follows these rules:
- **Plugin data is replaced with the archive's.** The same transaction drops every `trek_plugin_*` schema the role owns and loads the ones the dump holds, so a plugin installed after the backup loses its data, as it does on SQLite. Schemas the role does not own, and every other schema of the database, are never touched.
- **TREK checks the archive before it replaces anything.** The archive must hold a Postgres dump, not a SQLite file. The dump must carry TREK's migration history, and it must not come from a newer TREK. TREK refuses the restore with a message saying which check failed.
- **The client tools must be recent enough.** The restore refuses `pg_restore` or `psql` older than 18.0, 17.6, 16.10, 15.14 or 14.19, and tools older than the server.
- **The role must not be a superuser.** The restore refuses a role that is a superuser or holds `pg_execute_server_program` or `pg_write_server_files`. See [A role that is not a superuser](#a-role-that-is-not-a-superuser).
- **The role must not be a superuser.** The restore refuses a role that is a superuser or a member of one, holds `pg_execute_server_program`, `pg_read_server_files` or `pg_write_server_files`, or has CREATEROLE on PostgreSQL 14 or 15. See [A role that is not a superuser](#a-role-that-is-not-a-superuser).
- **The restore needs free space in the data directory.** `pg_restore` writes the dump out as a SQL script next to the unpacked archive before `psql` runs it, and the script is several times larger than the dump. It may grow to `BACKUP_MAX_DECOMPRESSED_MB` (5 GB by default); a larger one is stopped, nothing is replaced, and the work files are removed. Raise the limit for a genuine backup that needs more.
`RESTORE_FROM_BACKUP` works on Postgres too. On the first start, TREK loads the archive's dump into the database when that database holds no tables. When the database already has tables, the variable is ignored and TREK logs a warning. See [Backups: Restoring on a new install, before setup](Backups#restoring-on-a-new-install-before-setup).
@@ -187,7 +187,7 @@ Restoring a backup on Postgres follows these rules:
A plugin with the `db:own` permission keeps its own database. On SQLite that is a `plugin.db` file in its data directory. On Postgres it is a schema of its own in TREK's database, named `trek_plugin_<plugin id>` with each dash an underscore, so a Postgres install writes no SQLite file to the data volume, and the data volume can sit on network storage (NFS). Each plugin's directory under `data/plugins-data` is still created, for files a plugin keeps beside its database.
- **TREK's role creates the schemas**, so it needs the `CREATE` privilege on the database, which the role that owns the database has.
- **A plugin's SQL stays in its schema.** Only that schema is on the plugin's `search_path`, and TREK refuses a statement before it runs when it names another schema, the system catalogs or a function that could reach past it. The rules are in the [plugin-sdk README](https://github.com/liketrek/TREK/blob/main/plugin-sdk/README.md#your-own-database-on-postgres).
- **A plugin's SQL stays in its schema.** Only that schema is on the plugin's `search_path`, and TREK refuses a statement before it runs when it names another schema, the system catalogs or a function that could reach past it. It also refuses temporary objects (the words `TEMP` and `TEMPORARY`, and `SELECT ... INTO`), hexadecimal, octal and binary numbers, and control characters or non-ASCII whitespace outside strings, which Postgres reads differently from the check. Each statement is sent on its own over the extended query protocol, which runs one statement and no more, and every connection of TREK's pool searches the temporary schema last, so a temporary table can never stand in for one of TREK's. The rules are in the [plugin-sdk README](https://github.com/liketrek/TREK/blob/main/plugin-sdk/README.md#your-own-database-on-postgres).
- **A plugin writes Postgres SQL** on a Postgres install, not SQLite SQL. TREK does not translate it. A plugin written for SQLite only fails its `db:own` calls with the database's error; ask its author for Postgres support (`ctx.db.engine()` tells a plugin which engine it runs on).
- **Plugin calls share TREK's pool**, at most half of `TREK_DB_POOL_MAX` at once, one at a time per plugin.
- **Uninstalling a plugin with "delete data"** drops its schema.
@@ -214,7 +214,7 @@ Supabase runs PostgreSQL and can host TREK's database. The checklist below has b
- **Use the direct connection or the session pooler.** The direct connection uses port 5432. Its host resolves only to IPv6 unless the project has the IPv4 add-on. A container on a network without IPv6 (Docker Desktop's default network, for example) cannot reach it; use the session pooler there, which also listens on port 5432 on its own host.
- **Do not use the transaction pooler** (port 6543) for TREK. `pg_dump` and `psql` need a session that lasts for the whole run, and the transaction pooler does not give one.
- **Verify the server with Supabase's CA.** Supabase's certificate is signed by its own certificate authority, which the system's trusted authorities do not include, so `sslmode=require` alone fails for the backup and restore tools. Download the CA certificate from the project's database settings, mount it into the container, and use `sslmode=verify-full&sslrootcert=/certs/<file>.crt` with the path inside the container.
- **The `postgres` role works as TREK's role.** It is not a superuser, and it can create the schema and the `nocase` collation. If a restore refuses it because it holds `pg_execute_server_program` or `pg_write_server_files`, create a dedicated role as in [A role that is not a superuser](#a-role-that-is-not-a-superuser) (the `postgres` role may create roles) and connect TREK as that one.
- **The `postgres` role works as TREK's role.** It is not a superuser, and it can create the schema and the `nocase` collation. If a restore refuses it, because it holds `pg_execute_server_program`, `pg_read_server_files` or `pg_write_server_files`, or because the project runs PostgreSQL 14 or 15, where its right to create roles lets it grant itself those, create a dedicated role without CREATEROLE as in [A role that is not a superuser](#a-role-that-is-not-a-superuser) (the `postgres` role may create roles) and connect TREK as that one.
- **The database's `public` schema must hold no tables** when TREK first starts, because TREK refuses a database with tables it did not create. A new project's `public` schema is empty.
- **Backups hold only TREK's schema.** The project's own schemas (`auth`, `storage` and the others Supabase manages) are left out of every backup, and a restore replaces only TREK's schema.
- **Pick a region close to the TREK server.** Every statement crosses the network, so a distant region makes the first boot and a restore take minutes. During a restore, scheduled jobs that touch the database can log statement timeouts; they run again on their next schedule.