mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-11-20 02:56:10 +00:00
docs(db): describe plugin SQL on its own pool client instead of the marker hook
The guard's header, server/CLAUDE.md and the Postgres wiki page named extended-query.ts and a hook on every pool connection. They now say that the store sends each plugin statement over the extended protocol on a client it checks out per call, and drops that client's temporary tables and session state before handing it back.
This commit is contained in:
+1
-1
File diff suppressed because one or more lines are too long
@@ -12,12 +12,14 @@ import { PLUGIN_SCHEMA_PREFIX } from './plugin-schema';
|
||||
* 1. This guard holds the statement to what cannot leave the schema, before
|
||||
* it runs.
|
||||
* 2. The store sends every statement on its own over the extended query
|
||||
* protocol (`extended-query.ts`), which runs exactly one statement, so a
|
||||
* second statement the guard missed is an error, never run.
|
||||
* protocol, on a pool client it checked out for the call
|
||||
* (`plugin-data-store.ts`): Postgres parses exactly one statement there,
|
||||
* so a second statement the guard missed is an error, never run.
|
||||
* 3. The transaction puts the plugin's schema on the `search_path` with
|
||||
* `pg_temp` explicitly last, and TREK's own pool connections put `pg_temp`
|
||||
* last too (`session-search-path.ts`), so a temporary table never stands
|
||||
* in for a table of TREK's or of the plugin's.
|
||||
* `pg_temp` explicitly last, TREK's own pool connections put `pg_temp`
|
||||
* last too (`session-search-path.ts`), and the store drops every
|
||||
* temporary table on its client before giving it back, so a temporary
|
||||
* table never stands in for a table of TREK's or of the plugin's.
|
||||
*
|
||||
* The SQL is split into tokens the way Postgres's own lexer splits it (string
|
||||
* and identifier quoting, comments, dollar signs). Where JavaScript and the
|
||||
|
||||
@@ -187,9 +187,9 @@ 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. 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'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. Every connection of TREK's pool searches the temporary schema last, and a plugin call drops the temporary tables and other session state of the connection it used before handing it back, 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.
|
||||
- **Plugin calls share TREK's pool**, at most half of `TREK_DB_POOL_MAX` at once, one at a time per plugin. Each call takes a connection of its own from the pool for its transaction and gives it back when it ends.
|
||||
- **Uninstalling a plugin with "delete data"** drops its schema.
|
||||
- **One TREK per database.** The schema names depend only on the plugin id, so two TREK instances on one database would share their plugins' data.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user