feat(db): keep a plugin's own data in a Postgres schema of its own

A plugin with db:own got a SQLite WAL file in the data volume whatever the
engine, so a Postgres install still needed a local disk (discussion #386).
This adds the plugin data port (db/engine/plugin-data.ts) and its Postgres
side: one schema per plugin, trek_plugin_<id>, reached through TREK's pool.

Every call runs in a transaction that creates the schema if missing, puts
only it on the search_path and sets statement_timeout to the call's budget.
Reads stream through a cursor and stop at the row cap, a write that grows
the schema past the quota rolls back, and the calls of one plugin run one at
a time on at most half of the pool.

TREK's role may read every table, and a role per plugin would need
CREATEROLE, so plugin-sql-guard.ts checks each statement first: it lexes the
SQL as Postgres does and refuses another schema as a qualifier, the pg_
catalogs and functions, functions that run SQL from a string or reach an
object by a name in one, temporary tables, and every statement but DML and
DDL on tables, indexes, views, sequences and types.
This commit is contained in:
Maurice
2026-11-17 13:00:39 +01:00
parent a26db47cb6
commit b144781e9f
7 changed files with 1165 additions and 6 deletions
+9 -6
View File
@@ -23,14 +23,17 @@ export function resolveEngine(db: DbEngineSettings = readEnv().db): DatabaseEngi
}
/**
* The Postgres URL and the directory of its client tools, when the settings
* name a Postgres database; null on SQLite. For the code that drives pg_dump
* and pg_restore, which needs both and must not read them from the environment
* again.
* The Postgres URL, the directory of its client tools and the pool's size,
* when the settings name a Postgres database; null on SQLite. For the code
* that drives pg_dump and pg_restore, which needs the first two, and the
* plugin data stores, which share the pool, and must not read them from the
* environment again.
*/
export function postgresTarget(db: DbSettings): { url: string; binDir: string | undefined } | null {
export function postgresTarget(
db: DbSettings,
): { url: string; binDir: string | undefined; poolMax: number } | null {
if (db.engine !== 'postgres') return null;
return { url: db.url, binDir: db.pgBinDir };
return { url: db.url, binDir: db.pgBinDir, poolMax: db.poolMax };
}
/**
+59
View File
@@ -0,0 +1,59 @@
import type { EngineId } from '../../app-config/db-settings';
/**
* A plugin's own database (`db:own`), as the host's RPC handlers reach it.
* One implementation per engine: on SQLite a file of the plugin's own
* (`nest/plugins/host/plugin-data.service.ts`), on Postgres a schema of the
* plugin's own (`postgres/plugin-data-store.ts`). The plugin's SQL is its
* own, written for the engine `engine` names; neither implementation
* translates it.
*
* The SQLite handle answers synchronously, the Postgres one with a promise,
* so every method may return either. The caller awaits the result.
*/
export interface PluginDataStore {
readonly pluginId: string;
/** The engine the plugin's SQL runs on, which decides the SQL dialect it has to be written in. */
readonly engine: EngineId;
/** One read statement: its rows, up to the row cap and within the time budget. */
query(sql: string, args?: unknown[]): MaybePromise<unknown[]>;
/** One statement with bound args, or a script of statements without. */
exec(sql: string, args?: unknown[]): MaybePromise<{ changes: number }>;
/** Statements that commit or roll back together. */
tx(ops: PluginTxOp[]): MaybePromise<PluginTxResult>;
/** Runs `sql` once per `id`; a second call with the same id is a no-op. */
migrate(id: string, sql: string): MaybePromise<{ applied: boolean }>;
/** False once `close` ran: the host then opens a new store instead of reusing this one. */
isOpen(): boolean;
close(): void;
}
type MaybePromise<T> = T | Promise<T>;
/** One statement of a `tx` batch. */
export interface PluginTxOp {
sql: string;
args?: unknown[];
}
/** A `tx` batch's results, one per op: the rows of a statement that returns rows, the change count of any other. */
export interface PluginTxResult {
results: Array<{ changes?: number; rows?: unknown[] }>;
}
/**
* The limits every plugin database is held to, whatever the engine. The
* plugin-sdk README's "Runtime limits" table documents them.
*/
export const PLUGIN_DATA_CAPS = {
/** The longest SQL text one call may carry. */
maxSqlLength: 100_000,
/** The most rows a query, or a whole tx batch, returns. */
maxRows: 100_000,
/** The most statements one tx batch holds. */
maxTxOps: 100,
/** Wall-clock time for one query, one tx batch or one exec script. */
timeBudgetMs: 2_000,
/** The most a plugin's data may take on disk. */
quotaBytes: 256 * 1024 * 1024,
} as const;
@@ -0,0 +1,378 @@
import { PLUGIN_DATA_CAPS, type PluginDataStore, type PluginTxOp, type PluginTxResult } from '../plugin-data';
import { isPluginId, pluginSchemaName, quotePluginSchema } from './plugin-schema';
import { checkPlaceholders, checkQualifiers, parsePluginSql, type PluginStatement } from './plugin-sql-guard';
import { CompiledQuery, type Kysely, type Transaction } from 'kysely';
/**
* A plugin's own data on Postgres (`db:own`): a schema of its own in TREK's
* database (`plugin-schema.ts`), reached through TREK's pool.
*
* Every call runs in one transaction that first makes sure the schema and its
* migration table exist, then puts only that schema on the `search_path` and
* sets `statement_timeout` to the call's time budget. The plugin's SQL is
* checked by `plugin-sql-guard.ts` before it runs, so it cannot name another
* schema. Reads stream through a cursor and stop at the row cap. A call that
* may write measures the schema's size before and after, and rolls back one
* that leaves it past the quota and larger than it found it, so a plugin at
* its quota can still delete.
*
* The calls of one plugin run one at a time, as they do on its SQLite file,
* and all plugins together hold at most half of TREK's pool
* (`pluginDataSlots`), so a busy plugin never takes the connections TREK's
* own requests need.
*
* The SQLite store's semantics carry over: `query` and `tx` are held to the
* row cap, `query`, a `tx` batch and an `exec` script to the time budget, a
* script's statements each commit on their own, and `migrate` runs once per
* id with no time budget. What Postgres adds is that the budget also stops a
* single statement (`statement_timeout`), which SQLite cannot, and that an
* `exec` with bound args is held to it as well.
*/
/** The limits one store enforces. Overridable for tests; production uses `PLUGIN_DATA_CAPS`. */
interface PostgresPluginDataLimits {
maxRows: number;
timeBudgetMs: number;
quotaBytes: number;
/** The clock the time budget reads. */
now: () => number;
}
const DEFAULT_LIMITS: PostgresPluginDataLimits = {
maxRows: PLUGIN_DATA_CAPS.maxRows,
timeBudgetMs: PLUGIN_DATA_CAPS.timeBudgetMs,
quotaBytes: PLUGIN_DATA_CAPS.quotaBytes,
now: () => Date.now(),
};
/** Postgres's SQLSTATE for a statement cancelled by `statement_timeout`. */
const QUERY_CANCELED = '57014';
/** Rows a cursor fetches at once. */
const CHUNK_ROWS = 500;
/** What better-sqlite3 says about a closed handle, which the host recognizes. */
const CLOSED = 'The database connection is not open';
/** How many plugin transactions may hold a pool connection at once: half of TREK's pool, at least one. */
export function pluginDataSlots(poolMax: number): number {
return Math.max(1, Math.floor(poolMax / 2));
}
/** A counting semaphore: at most `size` pieces of work at once, the rest wait in order. */
export class PluginDataSlots {
private active = 0;
private readonly waiting: Array<() => void> = [];
constructor(readonly size: number) {}
async run<T>(work: () => Promise<T>): Promise<T> {
if (this.active < this.size) this.active++;
else await new Promise<void>((resolve) => this.waiting.push(resolve));
try {
return await work();
} finally {
// A waiting call takes the slot over, so the count stays where it is.
const next = this.waiting.shift();
if (next) next();
else this.active--;
}
}
}
type Trx = Transaction<object>;
/** The rows one call has returned so far, against the cap they share. */
interface RowBudget {
count: number;
readonly max: number;
readonly message: string;
}
/** Drops the plugin `id`'s schema and everything in it. An id no schema can be made from has none. */
export async function dropPluginSchema(db: Kysely<object>, id: string): Promise<void> {
if (!isPluginId(id)) return;
const schema = quotePluginSchema(pluginSchemaName(id));
await db.executeQuery(CompiledQuery.raw(`drop schema if exists ${schema} cascade`));
}
export class PostgresPluginDataStore implements PluginDataStore {
readonly engine = 'postgres' as const;
private readonly schema: string;
private readonly quoted: string;
private readonly limits: PostgresPluginDataLimits;
private open = true;
private queue: Promise<unknown> = Promise.resolve();
constructor(
readonly pluginId: string,
private readonly db: Kysely<object>,
private readonly slots: PluginDataSlots,
limits: Partial<PostgresPluginDataLimits> = {},
) {
this.schema = pluginSchemaName(pluginId);
this.quoted = quotePluginSchema(this.schema);
this.limits = { ...DEFAULT_LIMITS, ...limits };
}
isOpen(): boolean {
return this.open;
}
/** Stops new calls. One already running finishes: it holds a pool connection of its own, not this store. */
close(): void {
this.open = false;
}
async query(sql: string, args: unknown[] = []): Promise<unknown[]> {
const statement = this.single(sql, args);
const { maxRows } = this.limits;
return this.call('query', (budget) =>
this.transaction(budget.ms, [statement], (trx) => {
const rows = { count: 0, max: maxRows, message: `query returned more than ${maxRows} rows` };
return this.stream(trx, statement, args, rows, budget.check);
}),
);
}
async exec(sql: string, args: unknown[] = []): Promise<{ changes: number }> {
if (args.length > 0) {
const statement = this.single(sql, args);
return this.call('exec', (budget) =>
this.transaction(budget.ms, [statement], async (trx) => ({ changes: await this.run(trx, statement, args) })),
);
}
const statements = this.parse(sql);
return this.call('exec', async (budget) => {
// A script runs as SQLite runs one: each statement commits on its own, and
// the clock is read before every statement but the first.
await inOrder(statements, (statement, index) => {
if (index > 0) budget.check();
return this.transaction(budget.remaining(), [statement], (trx) => this.run(trx, statement, []));
});
return { changes: 0 };
});
}
async tx(ops: PluginTxOp[]): Promise<PluginTxResult> {
if (!Array.isArray(ops)) throw new Error('tx requires an array of { sql, args }');
if (ops.length === 0) return { results: [] };
if (ops.length > PLUGIN_DATA_CAPS.maxTxOps) {
throw new Error(`tx allows at most ${PLUGIN_DATA_CAPS.maxTxOps} statements`);
}
const statements = ops.map((op) => this.single(op?.sql, op?.args ?? []));
const { maxRows } = this.limits;
return this.call('tx', (budget) =>
this.transaction(budget.ms, statements, async (trx) => {
const rows = { count: 0, max: maxRows, message: `tx returned more than ${maxRows} rows in total` };
const results = await inOrder(statements, async (statement, index) => {
const args = ops[index].args ?? [];
// One budget for the whole batch: each statement after the first gets what is left of it.
if (index > 0) await this.setTimeout(trx, budget.remaining());
const result = statement.returnsRows
? { rows: await this.stream(trx, statement, args, rows, budget.check) }
: { changes: await this.run(trx, statement, args) };
budget.check();
return result;
});
return { results };
}),
);
}
/** No time budget, as on SQLite: a migration stopped part of the way would fail the same way on every start. */
async migrate(id: string, sql: string): Promise<{ applied: boolean }> {
const statements = this.parse(sql);
return this.enqueue(() =>
this.transaction(null, statements, async (trx) => {
const seen = await trx.executeQuery(
CompiledQuery.raw(`select 1 from ${this.quoted}._plugin_migrations where id = $1`, [id]),
);
if (seen.rows.length > 0) return { applied: false };
await inOrder(statements, (statement) => this.run(trx, statement, []));
await trx.executeQuery(
CompiledQuery.raw(`insert into ${this.quoted}._plugin_migrations (id, applied_at) values ($1, $2)`, [
id,
Date.now(),
]),
);
return { applied: true };
}),
);
}
/** `sql` as exactly one statement, checked against `args`. */
private single(sql: unknown, args: readonly unknown[]): PluginStatement {
const statements = this.parse(sql);
if (statements.length !== 1) throw new Error('sql must hold exactly one statement here; use exec() for a script');
checkPlaceholders(statements[0], args);
return statements[0];
}
/** The statements of `sql`, refused when the guard does not allow one or none is there. */
private parse(sql: unknown): PluginStatement[] {
if (!this.open) throw new Error(CLOSED);
if (typeof sql !== 'string') throw new Error('sql must be a string');
if (sql.length > PLUGIN_DATA_CAPS.maxSqlLength) throw new Error('sql too long');
const statements = parsePluginSql(sql);
if (statements.length === 0) throw new Error('The supplied SQL string contains no statements');
return statements;
}
/**
* Runs `work` in this plugin's turn with a time budget that starts when its
* turn comes, and reports a statement Postgres cancelled at
* `statement_timeout` as the budget running out.
*/
private call<T>(what: string, work: (budget: Budget) => Promise<T>): Promise<T> {
const { now, timeBudgetMs } = this.limits;
return this.enqueue(async () => {
const startedAt = now();
const budget: Budget = {
ms: timeBudgetMs,
remaining: () => Math.max(1, timeBudgetMs - (now() - startedAt)),
check: () => {
if (now() - startedAt > timeBudgetMs) throw new Error(`${what} exceeded its ${timeBudgetMs} ms time budget`);
},
};
try {
return await work(budget);
} catch (err) {
if (sqlState(err) === QUERY_CANCELED) {
throw new Error(`${what} exceeded its ${timeBudgetMs} ms time budget`, { cause: err });
}
throw err;
}
});
}
/** Queues `work` behind this plugin's earlier calls, then waits for a pool slot. */
private enqueue<T>(work: () => Promise<T>): Promise<T> {
const turn = this.queue.then(() => this.slots.run(work));
this.queue = turn.catch(() => undefined);
return turn;
}
/**
* One transaction on this plugin's schema: created if missing, alone on the
* `search_path`, with `statement_timeout` at `timeoutMs` (none for null).
* The statements' qualified names are checked against the database's
* schemas first, and a call that may write is held to the quota.
*/
private transaction<T>(
timeoutMs: number | null,
statements: readonly PluginStatement[],
work: (trx: Trx) => Promise<T>,
): Promise<T> {
return this.db.transaction().execute(async (trx) => {
const setup = [
`create schema if not exists ${this.quoted}`,
`create table if not exists ${this.quoted}._plugin_migrations (id text primary key, applied_at bigint)`,
`set local search_path to ${this.quoted}`,
'set local standard_conforming_strings to on',
];
if (timeoutMs !== null) setup.push(`set local statement_timeout to ${Math.max(1, Math.floor(timeoutMs))}`);
await trx.executeQuery(CompiledQuery.raw(setup.join(';\n')));
if (statements.some((s) => s.qualifies)) {
const schemas = await this.schemaNames(trx);
for (const statement of statements) checkQualifiers(statement, this.schema, schemas);
}
const writes = statements.some((s) => s.mayWrite);
const before = writes ? await this.sizeBytes(trx) : 0;
const result = await work(trx);
if (writes) {
const after = await this.sizeBytes(trx);
if (after > this.limits.quotaBytes && after > before) {
throw new Error(`the plugin database is past its ${this.limits.quotaBytes / 1024 / 1024} MB quota`);
}
}
return result;
});
}
private async setTimeout(trx: Trx, ms: number): Promise<void> {
await trx.executeQuery(
CompiledQuery.raw("select set_config('statement_timeout', $1, true)", [String(Math.max(1, Math.floor(ms)))]),
);
}
/** Every schema name of the database, which a qualified name in plugin SQL may not use. */
private async schemaNames(trx: Trx): Promise<Set<string>> {
const result = await trx.executeQuery<{ nspname: string }>(CompiledQuery.raw('select nspname from pg_namespace'));
return new Set(result.rows.map((row) => row.nspname));
}
/** What this plugin's tables, indexes and materialized views take on disk. */
private async sizeBytes(trx: Trx): Promise<number> {
const result = await trx.executeQuery<{ bytes: number | string }>(
CompiledQuery.raw(
'select coalesce(sum(pg_total_relation_size(c.oid)), 0) as bytes from pg_class c ' +
"join pg_namespace n on n.oid = c.relnamespace where n.nspname = $1 and c.relkind in ('r', 'm')",
[this.schema],
),
);
return Number(result.rows[0]?.bytes ?? 0);
}
/** Runs a statement for its effect: the rows it changed, or 0 for a read, whose rows are streamed past and dropped. */
private async run(trx: Trx, statement: PluginStatement, args: readonly unknown[]): Promise<number> {
if (!statement.mayWrite) {
const chunks = trx.getExecutor().stream(CompiledQuery.raw(statement.text, [...args]), CHUNK_ROWS);
for await (const _chunk of chunks) {
// Read to the end so the statement runs whole; its rows are not wanted.
}
return 0;
}
const result = await trx.executeQuery(CompiledQuery.raw(statement.text, [...args]));
return Number(result.numAffectedRows ?? 0);
}
/**
* The rows of a statement, read through a cursor a chunk at a time: past the
* row cap the read stops and throws, and the clock is read between chunks.
*/
private async stream(
trx: Trx,
statement: PluginStatement,
args: readonly unknown[],
budget: RowBudget,
checkTime: () => void,
): Promise<unknown[]> {
const rows: unknown[] = [];
const chunks = trx.getExecutor().stream(CompiledQuery.raw(statement.text, [...args]), CHUNK_ROWS);
for await (const chunk of chunks) {
if (rows.length > 0) checkTime();
for (const row of chunk.rows) {
rows.push(row);
budget.count++;
if (budget.count > budget.max) throw new Error(budget.message);
}
}
return rows;
}
}
/** `work` for each item, one after the other, each started once the one before it has finished. */
async function inOrder<T, R>(items: readonly T[], work: (item: T, index: number) => Promise<R>): Promise<R[]> {
const results: R[] = [];
await items.reduce<Promise<void>>(
(previous, item, index) =>
previous.then(async () => {
results.push(await work(item, index));
}),
Promise.resolve(),
);
return results;
}
/** A call's time budget: its whole length, what is left of it, and a check that throws once it is spent. */
interface Budget {
readonly ms: number;
remaining(): number;
check(): void;
}
/** The SQLSTATE of a `pg` error, or null. */
function sqlState(err: unknown): string | null {
if (typeof err !== 'object' || err === null || !('code' in err)) return null;
return typeof err.code === 'string' ? err.code : null;
}
@@ -0,0 +1,51 @@
/**
* The schema a plugin's own data lives in on Postgres (`db:own`): one per
* plugin, named from its id, beside TREK's schema in the same database.
*
* A plugin id is what the manifest allows (`PLUGIN_ID_RE` in
* `nest/plugins/protocol/manifest-rules.ts`): a lowercase letter, then 2 to 39
* lowercase letters, digits or dashes. The schema name is the prefix plus the
* id with each dash spelled as an underscore. An id never holds an underscore,
* so two ids never share a name, and the longest name (52 characters) stays
* under Postgres's 63. The pattern is repeated here rather than imported,
* because `src/db` does not import `src/nest`; a unit test holds the two equal.
*
* Every name TREK gives a plugin schema starts with the prefix, so a backup,
* a restore and the plugin SQL guard can tell them from every other schema of
* the database. Two TREK instances on one database would share these names,
* so each instance needs a database of its own (the wiki says so).
*/
/** What every plugin schema's name starts with. */
export const PLUGIN_SCHEMA_PREFIX = 'trek_plugin_';
/** The plugin ids a schema name can be made from: the manifest's rule. */
const PLUGIN_ID = /^[a-z][a-z0-9-]{2,39}$/;
/** A plugin schema's name, as `pluginSchemaName` makes it. */
const PLUGIN_SCHEMA = /^trek_plugin_[a-z][a-z0-9_]{2,39}$/;
/** Whether `id` is a plugin id a schema name can be made from. */
export function isPluginId(id: string): boolean {
return PLUGIN_ID.test(id);
}
/** The schema of the plugin `id`. Throws for anything the manifest would not accept as an id. */
export function pluginSchemaName(id: string): string {
if (!isPluginId(id)) throw new Error(`"${id}" is not a plugin id, so it has no data schema.`);
return PLUGIN_SCHEMA_PREFIX + id.replaceAll('-', '_');
}
/** Whether `name` is a schema name `pluginSchemaName` makes. */
export function isPluginSchemaName(name: string): boolean {
return PLUGIN_SCHEMA.test(name);
}
/**
* `name` as a quoted SQL identifier. Only plugin schema names reach it, which
* hold no quote, so the quoting cannot be escaped; it is checked all the same.
*/
export function quotePluginSchema(name: string): string {
if (!isPluginSchemaName(name)) throw new Error(`"${name}" is not a plugin schema name.`);
return `"${name}"`;
}
@@ -0,0 +1,400 @@
import { PLUGIN_SCHEMA_PREFIX } from './plugin-schema';
/**
* What keeps a plugin's own SQL on Postgres inside its own schema.
*
* On SQLite a plugin's database is a file of its own, so it cannot name
* TREK's tables at all. On Postgres its schema sits in TREK's database and
* its statements run as TREK's role, which may read every table TREK has: a
* role per plugin would need CREATEROLE, which TREK's role is not given. So
* the statement itself is held to what cannot leave the schema, before it
* runs, and the transaction it runs in names only that schema on its
* `search_path`, so an unqualified name finds nothing else.
*
* The SQL is split into tokens the way Postgres's own lexer splits it (string
* and identifier quoting, comments, dollar signs), and refused when it holds:
*
* - a statement other than SELECT, INSERT, UPDATE, DELETE, MERGE, WITH,
* VALUES, TABLE, TRUNCATE, REFRESH, or a CREATE, ALTER or DROP of a table,
* index, view, materialized view, sequence or type. No function, schema,
* role, setting, transaction control, COPY, LOCK, prepared statement or
* notification. Several statements are split at their semicolons and each
* is checked;
* - a qualified name whose qualifier is another schema of the database
* (`public.users`, another plugin's schema), or any name starting with
* `pg_` or naming `information_schema`: the catalogs, the server functions
* and the temporary schema;
* - a function that runs SQL handed to it as text (`query_to_xml`, `ts_stat`,
* `ts_rewrite`), reads or changes settings (`set_config`,
* `current_setting`), reaches objects by a name in a string (`nextval`,
* `setval`, the `reg*` casts), large objects (`lo_*`) or `dblink`;
* - a temporary table (`CREATE TEMP`, `SELECT ... INTO`), which would outlive
* the call on a pooled connection another plugin uses next, and
* `WITH RECURSIVE`, refused on SQLite too;
* - in an ALTER, a change of a table's schema, owner or tablespace;
* - escape strings (`E'...'`), Unicode escapes (`U&'...'`), dollar-quoted
* strings and a number running straight into a name, whose reading
* differs between Postgres versions and settings.
*
* An alias that happens to share a schema's name (`auth.id` on a database
* that has an `auth` schema) is refused too; the plugin renames the alias.
*/
/** Why a plugin's SQL is refused. The message is the plugin's to read, so it says what to change. */
export class PluginSqlRefused extends Error {
constructor(reason: string) {
super(`statement type not allowed for plugin databases: ${reason}`);
this.name = 'PluginSqlRefused';
}
}
/** One token of plugin SQL. A word is a name or a keyword: `value` is folded to lower case unless it was quoted. */
type Token = (
| { kind: 'word'; value: string; quoted: boolean }
| { kind: 'string' }
| { kind: 'number' }
| { kind: 'param' }
| { kind: 'punct'; value: string }
) & {
/** Where the token starts in the SQL text. */
at: number;
};
/** One statement of plugin SQL: its tokens, without the semicolon that ended it. */
export interface PluginStatement {
/** The statement's own text, as Postgres is handed it. */
readonly text: string;
readonly tokens: readonly Token[];
/** Whether it returns rows: a SELECT, VALUES or TABLE, or anything with a RETURNING clause. */
readonly returnsRows: boolean;
/** Whether it may change data or schema, which is what the disk quota is checked after. */
readonly mayWrite: boolean;
/** Whether it names a qualified object (`x.y`), which needs the database's schema names to check. */
readonly qualifies: boolean;
/** How many `$n` placeholders it holds. */
readonly params: number;
}
/** Postgres keeps the first 63 bytes of a name (NAMEDATALEN - 1) and drops the rest. */
const MAX_NAME_BYTES = 63;
/** The first word of each statement a plugin may run. */
const STATEMENTS = new Set([
'select',
'insert',
'update',
'delete',
'merge',
'with',
'values',
'table',
'truncate',
'refresh',
'create',
'alter',
'drop',
]);
/** Transaction control: every call already runs in a transaction of the host's. */
const TRANSACTION_CONTROL = new Set(['begin', 'start', 'commit', 'end', 'rollback', 'abort', 'savepoint', 'release']);
/** What a CREATE, ALTER or DROP may act on. */
const OBJECTS = new Set(['table', 'index', 'view', 'materialized', 'sequence', 'type']);
/** The words that make up a statement's main verb, after a WITH clause. */
const VERBS = new Set(['select', 'insert', 'update', 'delete', 'merge', 'values', 'table']);
/** The verbs of a statement that only reads. */
const READ_VERBS = new Set(['select', 'values', 'table']);
/** Functions and types refused under any spelling, quoted or not. */
const REFUSED_NAMES = new Set([
'set_config',
'current_setting',
'ts_stat',
'ts_rewrite',
'nextval',
'setval',
'currval',
'lastval',
'loread',
'lowrite',
'regclass',
'regproc',
'regprocedure',
'regoper',
'regoperator',
'regnamespace',
'regrole',
'regcollation',
'information_schema',
]);
/** Name prefixes refused under any spelling. */
const REFUSED_PREFIXES = ['pg_', 'lo_', 'dblink', 'to_reg', 'binary_upgrade_'];
/** A name refused wherever it appears: the XML exports of a query, a table, a schema or the database. */
const XML_EXPORT = /_to_xml/;
/** Starts a name: a letter, an underscore or any character past ASCII, as Postgres reads it. */
const NAME_START = /[A-Za-z_\u0080-￿]/;
/** Continues a name; a dollar sign is part of one. */
const NAME_PART = /[A-Za-z0-9_$\u0080-￿]/;
/** The single-character punctuation and operator characters. */
const PUNCT = new Set([...'.,()[];+-*/<>=~!@#%^&|?']);
/** `name` lower-cased the way Postgres folds an unquoted name: ASCII letters only. */
function fold(name: string): string {
return name.replace(/[A-Z]/g, (c) => c.toLowerCase());
}
/** `name` cut to the bytes Postgres keeps of it, never in the middle of a character. */
function truncateName(name: string): string {
if (Buffer.byteLength(name, 'utf8') <= MAX_NAME_BYTES) return name;
let out = '';
for (const ch of name) {
if (Buffer.byteLength(out + ch, 'utf8') > MAX_NAME_BYTES) break;
out += ch;
}
return out;
}
/** Splits `sql` into tokens, or refuses what this guard does not read the way Postgres would. */
export function tokenize(sql: string): Token[] {
const tokens: Token[] = [];
let i = 0;
const n = sql.length;
while (i < n) {
const at = i;
const c = sql[i];
const next = sql[i + 1];
if (/\s/.test(c)) {
i++;
} else if (c === '-' && next === '-') {
while (i < n && sql[i] !== '\n') i++;
} else if (c === '/' && next === '*') {
i = skipBlockComment(sql, i);
} else if (c === "'") {
i = skipQuoted(sql, i, "'", 'a string');
tokens.push({ kind: 'string', at });
} else if (c === '"') {
const end = skipQuoted(sql, i, '"', 'a quoted name');
const value = sql.slice(i + 1, end - 1).replaceAll('""', '"');
if (value === '') throw new PluginSqlRefused('a quoted name may not be empty');
tokens.push({ kind: 'word', value: truncateName(value), quoted: true, at });
i = end;
} else if (c === '$') {
if (!/[0-9]/.test(next ?? '')) {
throw new PluginSqlRefused('dollar-quoted strings are not accepted; write the string in single quotes');
}
i++;
while (i < n && /[0-9]/.test(sql[i])) i++;
tokens.push({ kind: 'param', at });
} else if (/[0-9]/.test(c) || (c === '.' && /[0-9]/.test(next ?? ''))) {
i = skipNumber(sql, i);
if (i < n && NAME_PART.test(sql[i])) {
throw new PluginSqlRefused('a number may not run straight into a name; put a space between them');
}
tokens.push({ kind: 'number', at });
} else if (NAME_START.test(c)) {
if ((c === 'e' || c === 'E') && next === "'") {
throw new PluginSqlRefused("escape strings (E'...') are not accepted; write the string in single quotes");
}
if ((c === 'u' || c === 'U') && next === '&' && (sql[i + 2] === "'" || sql[i + 2] === '"')) {
throw new PluginSqlRefused('Unicode escapes (U&) are not accepted');
}
while (i < n && NAME_PART.test(sql[i])) i++;
tokens.push({ kind: 'word', value: truncateName(fold(sql.slice(at, i))), quoted: false, at });
} else if (c === ':' && next === ':') {
tokens.push({ kind: 'punct', value: '::', at });
i += 2;
} else if (c === ':' || PUNCT.has(c)) {
tokens.push({ kind: 'punct', value: c, at });
i++;
} else {
throw new PluginSqlRefused(`unexpected character ${JSON.stringify(c)}`);
}
}
return tokens;
}
/** The index past a block comment starting at `start`; Postgres nests them. */
function skipBlockComment(sql: string, start: number): number {
let depth = 0;
let i = start;
while (i < sql.length) {
if (sql[i] === '/' && sql[i + 1] === '*') {
depth++;
i += 2;
} else if (sql[i] === '*' && sql[i + 1] === '/') {
depth--;
i += 2;
if (depth === 0) return i;
} else {
i++;
}
}
throw new PluginSqlRefused('a comment is not closed');
}
/** The index past a quoted string or name starting at `start`; a doubled quote stands for one. */
function skipQuoted(sql: string, start: number, quote: string, what: string): number {
let i = start + 1;
while (i < sql.length) {
if (sql[i] === quote) {
if (sql[i + 1] === quote) {
i += 2;
continue;
}
return i + 1;
}
i++;
}
throw new PluginSqlRefused(`${what} is not closed`);
}
/** The index past a numeric constant starting at `start`: decimal, with a fraction and an exponent, or 0x/0o/0b. */
function skipNumber(sql: string, start: number): number {
const rest = sql.slice(start);
const match =
/^0[xX][0-9a-fA-F_]+|^0[oO][0-7_]+|^0[bB][01_]+|^(?:[0-9][0-9_]*(?:\.[0-9_]*)?|\.[0-9][0-9_]*)(?:[eE][+-]?[0-9]+)?/.exec(
rest,
);
return start + (match ? match[0].length : 1);
}
/** Splits `sql` into its statements, each checked on its own; empty ones (`;;`, a comment) are dropped. */
export function parsePluginSql(sql: string): PluginStatement[] {
const statements: PluginStatement[] = [];
let current: Token[] = [];
const flush = (end: number) => {
if (current.length > 0) statements.push(describe(sql.slice(current[0].at, end).trimEnd(), current));
current = [];
};
for (const token of tokenize(sql)) {
if (token.kind === 'punct' && token.value === ';') flush(token.at);
else current.push(token);
}
flush(sql.length);
return statements;
}
/** The unquoted keyword at `token`, or null for anything else. */
function keyword(token: Token | undefined): string | null {
return token?.kind === 'word' && !token.quoted ? token.value : null;
}
/** Reads what a statement's caller needs to know about it, and refuses one this guard does not allow. */
function describe(text: string, tokens: Token[]): PluginStatement {
const first = tokens[0];
const opensWithParen = first.kind === 'punct' && first.value === '(';
const verb = opensWithParen ? 'select' : keyword(first);
if (verb !== null && TRANSACTION_CONTROL.has(verb)) {
throw new PluginSqlRefused(
'transaction-control statements are not allowed: each call runs in its own transaction, and tx() makes a batch atomic',
);
}
if (verb === null || !STATEMENTS.has(verb)) {
throw new PluginSqlRefused(`a statement may not start with ${describeToken(first)}`);
}
if (verb === 'create' || verb === 'alter' || verb === 'drop' || verb === 'refresh') checkObject(verb, tokens);
let depth = 0;
let main: string | null = verb === 'with' ? null : verb;
let returning = false;
let selectInto = false;
let params = 0;
let qualifies = false;
for (const [index, token] of tokens.entries()) {
if (token.kind === 'param') params++;
if (token.kind === 'punct' && token.value === '(') depth++;
if (token.kind === 'punct' && token.value === ')') depth--;
if (token.kind !== 'word') continue;
checkName(token.value);
const after = tokens[index + 1];
if (after?.kind === 'punct' && after.value === '.') qualifies = true;
if (token.quoted) continue;
if (token.value === 'recursive') throw new PluginSqlRefused('WITH RECURSIVE is not allowed');
if (token.value === 'tablespace') throw new PluginSqlRefused('a tablespace may not be named');
if (verb === 'alter' && (token.value === 'schema' || token.value === 'owner')) {
throw new PluginSqlRefused(`an ALTER may not change the ${token.value}`);
}
if (depth !== 0) continue;
if (main === null && VERBS.has(token.value)) main = token.value;
if (token.value === 'returning') returning = true;
if (token.value === 'into' && main === 'select') selectInto = true;
}
if (selectInto) throw new PluginSqlRefused('SELECT ... INTO is not allowed; use CREATE TABLE ... AS');
const reads = main !== null && READ_VERBS.has(main);
const writesInside = tokens.some((t) => {
const word = keyword(t);
return word !== null && ['insert', 'update', 'delete', 'merge'].includes(word);
});
return {
text,
tokens,
returnsRows: reads || returning,
mayWrite: !reads || writesInside,
qualifies,
params,
};
}
/** Refuses a CREATE, ALTER, DROP or REFRESH of anything but the objects a plugin keeps in its schema. */
function checkObject(verb: string, tokens: readonly Token[]): void {
let at = 1;
if (verb === 'create') {
if (keyword(tokens[at]) === 'or' && keyword(tokens[at + 1]) === 'replace') at += 2;
while (keyword(tokens[at]) === 'unique' || keyword(tokens[at]) === 'unlogged') at++;
}
const object = keyword(tokens[at]);
const allowed = verb === 'refresh' ? object === 'materialized' : object !== null && OBJECTS.has(object);
if (!allowed) {
throw new PluginSqlRefused(`${verb.toUpperCase()} ${describeToken(tokens[at])} is not allowed`);
}
}
/** Refuses a name that reaches past the plugin's schema whatever qualifies it. */
function checkName(name: string): void {
if (REFUSED_NAMES.has(name) || REFUSED_PREFIXES.some((p) => name.startsWith(p)) || XML_EXPORT.test(name)) {
throw new PluginSqlRefused(`"${name}" may not be named in a plugin's SQL`);
}
}
/** A token as an error message shows it. */
function describeToken(token: Token | undefined): string {
if (token === undefined) return 'nothing';
if (token.kind === 'word') return token.quoted ? `"${token.value}"` : token.value.toUpperCase();
if (token.kind === 'punct') return `"${token.value}"`;
return `a ${token.kind}`;
}
/**
* Refuses a qualified name in `statement` whose qualifier is a schema other
* than `ownSchema`: one of `schemas` (every schema of the database), or one
* named like a plugin schema even before it exists.
*/
export function checkQualifiers(statement: PluginStatement, ownSchema: string, schemas: ReadonlySet<string>): void {
const { tokens } = statement;
for (const [index, token] of tokens.entries()) {
const after = tokens[index + 1];
if (token.kind !== 'word' || after?.kind !== 'punct' || after.value !== '.') continue;
if (token.value === ownSchema) continue;
if (schemas.has(token.value) || token.value.startsWith(PLUGIN_SCHEMA_PREFIX) || token.value === 'public') {
throw new PluginSqlRefused(`"${token.value}" is another schema; a plugin reaches its own tables only`);
}
}
}
/**
* Refuses `?` placeholders where bound args were given: Postgres numbers its
* placeholders `$1`, `$2`, ..., and reads a `?` as an operator.
*/
export function checkPlaceholders(statement: PluginStatement, args: readonly unknown[]): void {
if (args.length === 0 || statement.params > 0) return;
const questionMark = statement.tokens.some((t) => t.kind === 'punct' && t.value === '?');
if (questionMark) {
throw new PluginSqlRefused('this TREK runs on Postgres, which numbers its placeholders $1, $2, ... instead of ?');
}
}
@@ -0,0 +1,92 @@
/**
* The schema a plugin's own data lives in on Postgres
* (src/db/engine/postgres/plugin-schema.ts), the restore's statements for the
* plugin schemas (clear-schema.ts) and the pool slots the plugin stores share
* (plugin-data-store.ts), without a database.
*/
import { pluginSchemasSql } from '../../../../../src/db/engine/postgres/clear-schema';
import { PluginDataSlots, pluginDataSlots } from '../../../../../src/db/engine/postgres/plugin-data-store';
import {
isPluginId,
isPluginSchemaName,
PLUGIN_SCHEMA_PREFIX,
pluginSchemaName,
quotePluginSchema,
} from '../../../../../src/db/engine/postgres/plugin-schema';
import { PLUGIN_ID_RE } from '../../../../../src/nest/plugins/protocol/manifest-rules';
import { describe, expect, it } from 'vitest';
describe('plugin schema names', () => {
it('PGSCHEMA-001: a name is the prefix plus the id, each dash an underscore', () => {
expect(pluginSchemaName('notes')).toBe('trek_plugin_notes');
expect(pluginSchemaName('trip-weather-2')).toBe('trek_plugin_trip_weather_2');
expect(quotePluginSchema(pluginSchemaName('trip-weather-2'))).toBe('"trek_plugin_trip_weather_2"');
});
it('PGSCHEMA-002: accepts exactly the ids the manifest accepts', () => {
const samples = ['abc', 'a-b', 'a--b', 'z9', 'notes', 'Notes', '9abc', '-abc', 'a_b', 'a.b', '', 'a'.repeat(40)];
samples.push('a'.repeat(41), '../x', 'abc ', 'ab"c', 'abc;drop');
for (const id of samples) expect(isPluginId(id), id).toBe(PLUGIN_ID_RE.test(id));
expect(String(PLUGIN_ID_RE)).toBe('/^[a-z][a-z0-9-]{2,39}$/');
});
it('PGSCHEMA-003: refuses anything that is not an id, before any SQL is written', () => {
for (const id of ['Notes', '../x', 'a"b', 'ab', 'a b', 'a'.repeat(41)]) {
expect(() => pluginSchemaName(id), id).toThrow(/is not a plugin id/);
}
expect(() => quotePluginSchema('public')).toThrow(/is not a plugin schema name/);
expect(() => quotePluginSchema('trek_plugin_x"; drop')).toThrow(/is not a plugin schema name/);
});
it('PGSCHEMA-004: two ids never share a name, and every name fits in a Postgres identifier', () => {
expect(pluginSchemaName('a-b-c')).not.toBe(pluginSchemaName('a--bc'));
const longest = pluginSchemaName(`a${'-'.repeat(39)}`);
expect(longest.length).toBeLessThanOrEqual(63);
expect(isPluginSchemaName(longest)).toBe(true);
expect(isPluginSchemaName('trek_plugin_ab')).toBe(false);
expect(isPluginSchemaName('public')).toBe(false);
expect(isPluginSchemaName(`${PLUGIN_SCHEMA_PREFIX}Notes`)).toBe(false);
});
it("PGSCHEMA-005: a restore drops only the role's own plugin schemas, then creates the dump's", () => {
const sql = pluginSchemasSql(['trek_plugin_a', 'trek_plugin_b']);
expect(sql).toContain("starts_with(nspname, 'trek_plugin_')");
expect(sql).toContain('pg_get_userbyid(nspowner) = current_user');
expect(sql).toContain("EXECUTE format('DROP SCHEMA %I CASCADE', r.nspname);");
expect(sql.endsWith('CREATE SCHEMA "trek_plugin_a";\nCREATE SCHEMA "trek_plugin_b";\n')).toBe(true);
expect(pluginSchemasSql([])).not.toContain('CREATE SCHEMA');
expect(() => pluginSchemasSql(['auth'])).toThrow(/is not a plugin schema name/);
});
});
describe('plugin data pool slots', () => {
it('PGSCHEMA-006: plugins hold at most half of the pool, at least one connection', () => {
expect(pluginDataSlots(10)).toBe(5);
expect(pluginDataSlots(3)).toBe(1);
expect(pluginDataSlots(1)).toBe(1);
});
it('PGSCHEMA-007: no more than `size` pieces of work run at once, and the rest run in order', async () => {
const slots = new PluginDataSlots(2);
let running = 0;
let most = 0;
const order: number[] = [];
const work = (n: number) =>
slots.run(async () => {
running++;
most = Math.max(most, running);
await new Promise((resolve) => setTimeout(resolve, 5));
order.push(n);
running--;
if (n === 2) throw new Error('fails');
return n;
});
const results = await Promise.allSettled([1, 2, 3, 4, 5].map(work));
expect(most).toBe(2);
expect(order.slice(2)).toEqual([3, 4, 5]);
expect(results.map((r) => r.status)).toEqual(['fulfilled', 'rejected', 'fulfilled', 'fulfilled', 'fulfilled']);
// A failure gives its slot back like a success does.
await expect(slots.run(async () => 'next')).resolves.toBe('next');
});
});
@@ -0,0 +1,176 @@
/**
* The guard that keeps a plugin's own SQL inside its schema on Postgres
* (src/db/engine/postgres/plugin-sql-guard.ts), without a database: what it
* lets through, what it refuses and why, how it reads quoting and comments
* the way Postgres does, and what it tells the store about a statement. The
* same rules against a real database are PGPLUG-003/004 in the Postgres lane.
*/
import {
checkPlaceholders,
checkQualifiers,
parsePluginSql,
PluginSqlRefused,
tokenize,
} from '../../../../../src/db/engine/postgres/plugin-sql-guard';
import { describe, expect, it } from 'vitest';
const OWN = 'trek_plugin_notes';
const SCHEMAS = new Set(['public', 'auth', 'pg_catalog', 'information_schema', OWN, 'trek_plugin_other']);
/** Parses `sql` and checks its qualified names as the store does. */
function check(sql: string): void {
for (const statement of parsePluginSql(sql)) checkQualifiers(statement, OWN, SCHEMAS);
}
describe('plugin SQL guard', () => {
it.each([
'SELECT * FROM notes WHERE id = $1',
'select n.body, t.name from notes n join tags t on t.note_id = n.id',
'INSERT INTO notes (body) VALUES ($1) RETURNING id',
"UPDATE notes SET body = 'it''s' WHERE id = 1",
'DELETE FROM notes WHERE id IN (SELECT note_id FROM trash)',
'WITH recent AS (SELECT * FROM notes ORDER BY id DESC LIMIT 5) SELECT count(*) FROM recent',
'VALUES (1), (2)',
'TABLE notes',
'(SELECT 1) UNION (SELECT 2)',
'CREATE TABLE notes (id bigserial PRIMARY KEY, body text, temp real, schema text)',
'CREATE UNIQUE INDEX notes_body ON notes (body)',
'CREATE UNLOGGED TABLE cache (k text)',
'CREATE OR REPLACE VIEW v AS SELECT body FROM notes',
'CREATE MATERIALIZED VIEW mv AS SELECT 1',
'CREATE SEQUENCE s',
"CREATE TYPE mood AS ENUM ('ok', 'sad')",
'ALTER TABLE notes ADD COLUMN tag text',
'DROP TABLE IF EXISTS notes CASCADE',
'TRUNCATE notes',
'REFRESH MATERIALIZED VIEW mv',
'SELECT body FROM trek_plugin_notes.notes',
'SELECT "notes"."body" FROM "notes"',
"SELECT 'public.users -- not code' AS text",
'SELECT 1 -- public.users\n',
'SELECT /* public.users */ 1',
'SELECT 1.5e3, .5, 0x1F',
'INSERT INTO kv VALUES ($1, $2) ON CONFLICT (k) DO NOTHING',
])('lets through %s', (sql) => {
expect(() => check(sql)).not.toThrow();
});
it.each([
['SELECT * FROM public.users', /another schema/],
['SELECT * FROM "public"."users"', /another schema/],
['SELECT * FROM PUBLIC . users', /another schema/],
['SELECT * FROM public/**/.users', /another schema/],
['SELECT * FROM auth.secret', /another schema/],
['SELECT * FROM trek_plugin_other.notes', /another schema/],
['SELECT * FROM trek_plugin_not_yet.notes', /another schema/],
['SELECT * FROM trek.public.users', /another schema/],
['SELECT * FROM pg_stats', /"pg_stats" may not be named/],
['SELECT * FROM "pg_catalog".pg_authid', /"pg_catalog" may not be named/],
['SELECT * FROM information_schema.tables', /"information_schema" may not be named/],
["SELECT query_to_xml('select 1', true, true, '')", /"query_to_xml" may not be named/],
["SELECT database_to_xml(true, true, '')", /"database_to_xml" may not be named/],
["SELECT ts_stat('select 1')", /"ts_stat" may not be named/],
["SELECT \"set_config\"('search_path', 'public', true)", /"set_config" may not be named/],
["SELECT current_setting('search_path')", /"current_setting" may not be named/],
["SELECT nextval('users_id_seq')", /"nextval" may not be named/],
["SELECT 'users'::regclass", /"regclass" may not be named/],
["SELECT to_regclass('users')", /"to_regclass" may not be named/],
['SELECT lo_get(1)', /"lo_get" may not be named/],
["SELECT dblink('x', 'y')", /"dblink" may not be named/],
['WITH RECURSIVE r(x) AS (SELECT 1 UNION ALL SELECT x + 1 FROM r) SELECT * FROM r', /RECURSIVE/],
['SELECT 1 AS x INTO copy_of', /SELECT \.\.\. INTO/],
['CREATE TEMP TABLE t (x int)', /CREATE TEMP is not allowed/],
['CREATE TEMPORARY TABLE t (x int)', /CREATE TEMPORARY is not allowed/],
["CREATE FUNCTION f() RETURNS int LANGUAGE sql AS 'select 1'", /CREATE FUNCTION is not allowed/],
['CREATE OR REPLACE FUNCTION f() RETURNS int', /CREATE FUNCTION is not allowed/],
['CREATE SCHEMA mine', /CREATE SCHEMA is not allowed/],
['CREATE EXTENSION dblink', /CREATE EXTENSION is not allowed/],
['DROP SCHEMA trek_plugin_notes', /DROP SCHEMA is not allowed/],
['DROP OWNED BY current_user', /DROP OWNED is not allowed/],
['ALTER TABLE notes SET SCHEMA x', /may not change the schema/],
['ALTER TABLE notes OWNER TO someone', /may not change the owner/],
['ALTER ROLE trek SUPERUSER', /ALTER ROLE is not allowed/],
['CREATE TABLE t (x int) TABLESPACE pg_default', /tablespace/],
['SET search_path TO public', /may not start with SET/],
['RESET ROLE', /may not start with RESET/],
['COPY notes TO STDOUT', /may not start with COPY/],
['GRANT SELECT ON notes TO PUBLIC', /may not start with GRANT/],
['DO $$ BEGIN END $$', /dollar-quoted/],
['LISTEN x', /may not start with LISTEN/],
['PREPARE p AS SELECT 1', /may not start with PREPARE/],
['EXPLAIN ANALYZE SELECT 1', /may not start with EXPLAIN/],
['BEGIN', /transaction-control/],
['COMMIT', /transaction-control/],
['SAVEPOINT a', /transaction-control/],
["SELECT E'\\x'", /escape strings/],
["SELECT U&'\\0041'", /Unicode escapes/],
['SELECT * FROM U&"\\0070ublic".users', /Unicode escapes/],
['SELECT $tag$x$tag$', /dollar-quoted/],
['SELECT 1.public', /a number may not run straight into a name/],
["SELECT 'open", /a string is not closed/],
['SELECT "open', /a quoted name is not closed/],
['SELECT /* open', /a comment is not closed/],
['SELECT ""', /a quoted name may not be empty/],
['SELECT `x`', /unexpected character/],
['SELECT 1; SELECT * FROM public.users', /another schema/],
])('refuses %s', (sql, reason) => {
expect(() => check(sql)).toThrow(PluginSqlRefused);
expect(() => check(sql)).toThrow(reason);
});
it('reads nested block comments as Postgres does, so code after the inner close is still a comment', () => {
expect(() => check('SELECT 1 /* outer /* inner */ public.users */')).not.toThrow();
expect(() => check('SELECT 1 /* one */ FROM public.users')).toThrow(/another schema/);
});
it('compares a long name the way Postgres keeps it: cut to 63 bytes', () => {
const own = `trek_plugin_${'a'.repeat(51)}`;
expect(own).toHaveLength(63);
const statement = parsePluginSql(`SELECT * FROM ${own}zzzz.notes`)[0];
expect(() => checkQualifiers(statement, own, new Set([own]))).not.toThrow();
const other = `public${'x'.repeat(70)}`;
const cut = other.slice(0, 63);
expect(() => checkQualifiers(parsePluginSql(`SELECT * FROM ${other}.t`)[0], own, new Set([cut]))).toThrow(
/another schema/,
);
});
it('splits a script at its semicolons, keeps each statement text and drops empty ones', () => {
const statements = parsePluginSql("CREATE TABLE a (x text);;\n-- note\nINSERT INTO a VALUES ('a;b');");
expect(statements.map((s) => s.text)).toEqual(['CREATE TABLE a (x text)', "INSERT INTO a VALUES ('a;b')"]);
expect(parsePluginSql('-- nothing\n;')).toEqual([]);
});
it('says whether a statement returns rows, may write, qualifies a name and how many placeholders it has', () => {
const [select] = parsePluginSql('SELECT * FROM notes WHERE id = $1 AND tag = $2');
expect(select).toMatchObject({ returnsRows: true, mayWrite: false, qualifies: false, params: 2 });
const [returning] = parsePluginSql('UPDATE notes SET body = $1 RETURNING id');
expect(returning).toMatchObject({ returnsRows: true, mayWrite: true });
const [insert] = parsePluginSql('INSERT INTO notes (body) VALUES ($1)');
expect(insert).toMatchObject({ returnsRows: false, mayWrite: true });
const [cte] = parsePluginSql('WITH gone AS (DELETE FROM notes RETURNING id) SELECT count(*) FROM gone');
expect(cte).toMatchObject({ returnsRows: true, mayWrite: true });
const [ddl] = parsePluginSql('CREATE TABLE t (x int)');
expect(ddl).toMatchObject({ returnsRows: false, mayWrite: true });
const [qualified] = parsePluginSql('SELECT n.body FROM notes n');
expect(qualified.qualifies).toBe(true);
});
it('turns a SQLite ? placeholder into a message about $1 when args are bound', () => {
const [sqliteStyle] = parsePluginSql('SELECT * FROM notes WHERE id = ?');
expect(() => checkPlaceholders(sqliteStyle, [1])).toThrow(/\$1, \$2/);
expect(() => checkPlaceholders(sqliteStyle, [])).not.toThrow();
const [pgStyle] = parsePluginSql('SELECT * FROM notes WHERE id = $1');
expect(() => checkPlaceholders(pgStyle, [1])).not.toThrow();
});
it('folds unquoted names to lower case and keeps quoted ones as written', () => {
expect(tokenize('Select "MiXed", Plain')).toEqual([
{ kind: 'word', value: 'select', quoted: false, at: 0 },
{ kind: 'word', value: 'MiXed', quoted: true, at: 7 },
{ kind: 'punct', value: ',', at: 14 },
{ kind: 'word', value: 'plain', quoted: false, at: 16 },
]);
});
});