@rebasepro/server-postgres 0.12.1-canary.gf5f1d39 → 0.13.1-canary.g06dbe5b

package/dist/cli-helpers.d.ts

@@ -1,9 +1,89 @@
 import type { CollectionConfig } from "@rebasepro/types";
+/**
+ * Why is a dependency's binary missing — never installed, or installed with its
+ * build script blocked?
+ *
+ * These need opposite advice, and getting it wrong is not a cosmetic miss. pnpm
+ * 10+ refuses to run a dependency's lifecycle scripts unless it is allowlisted
+ * (`pnpm.onlyBuiltDependencies`, or `allowBuilds` in `pnpm-workspace.yaml`).
+ * `@ariga/atlas` downloads its platform binary in `preinstall`, so a blocked
+ * script leaves a state that looks like a successful install: the package is on
+ * disk with its `install.js` and `package.json`, `node_modules/.bin` is empty,
+ * the install exits 0, and the only signal is `ERR_PNPM_IGNORED_BUILDS` several
+ * screens up.
+ *
+ * Telling somebody in that state to install the package again sends them round
+ * the same loop forever — the add succeeds, the script is blocked again,
+ * nothing changes. Verified by doing it: `pnpm add @ariga/atlas` into a bare
+ * project yields exactly this, three "Failed to create bin … ENOENT" warnings
+ * and no binary.
+ *
+ * Resolution is attempted from the user's project first and this package
+ * second, matching the order {@link resolveLocalBin} searches — the driver may
+ * be installed a level up from where the command runs.
+ */
+export declare function diagnoseMissingBin(packageName: string): "not-installed" | "build-script-blocked";
 export declare function resolveLocalBin(binName: string): string | null;
-export declare function getTableIncludesFromCollections(collections: CollectionConfig[]): Promise<string[]>;
+export declare function getTableIncludesFromCollections(allCollections: CollectionConfig[]): Promise<string[]>;
 export declare function getTableIncludes(collectionsPath: string): Promise<string[]>;
+/**
+ * Load a project's collections the way the Atlas-facing commands need them.
+ *
+ * Deliberately forgiving — a file that fails to import is skipped rather than
+ * fatal — because the callers use this to *narrow* what Atlas may touch, and a
+ * hard failure here would block a push over an unrelated broken file. Callers
+ * that cannot tolerate a partial answer (the table excludes, which fail closed)
+ * check the result themselves.
+ */
+export declare function loadCollectionsForCli(collectionsPath: string): Promise<CollectionConfig[]>;
 export declare function getDevDatabaseUrl(databaseUrl: string): string;
 export declare function ensureDevDatabaseExists(databaseUrl: string, devDatabaseUrl: string): Promise<void>;
+/**
+ * The generated SQL for the project's `search` blocks, if it has any.
+ *
+ * @param drizzleDir directory holding the generated SQL. Defaults to `drizzle`
+ *        under the working directory.
+ */
+export declare function readSearchDdl(drizzleDir?: string): string;
+/**
+ * Bring the search column, its index and their helpers up to date.
+ *
+ * Runs *after* Atlas, not before: the statements are `ALTER TABLE ... ADD
+ * COLUMN`, so the table has to exist. Atlas is told to ignore these objects
+ * entirely (`getSearchExcludes`) — it cannot manage them, and left to itself it
+ * would plan a `DROP COLUMN` for every one, since they are absent from the
+ * desired state it was given.
+ *
+ * A no-op when no collection declared `search`. A failure is *not* swallowed:
+ * silently pushing a schema whose search column never appeared is how a
+ * collection ends up with search configured, no error anywhere, and no results.
+ */
+export declare function applySearchDdl(databaseUrl: string, drizzleDir?: string): Promise<void>;
+/**
+ * Glob patterns keeping Atlas away from the search objects.
+ *
+ * Returns an empty list — and so changes nothing — for a project with no
+ * `search` block, which is every project that has not opted in.
+ */
+export declare function getSearchExcludes(collectionsPath: string): Promise<string[]>;
+/**
+ * Give the dev database the search helper functions before Atlas plans.
+ *
+ * Excluding the search column keeps Atlas from *diffing* it, but not from
+ * materialising the inspected schema — column and all — in the dev database to
+ * analyse the plan against. That replay is where a push against an
+ * already-searchable database died with `function public.rebase_search_text
+ * (jsonb) does not exist`: the column came across, the function it calls did
+ * not, because Atlas will not carry a function at all.
+ *
+ * Only the extensions and functions, never the tables: the dev database holds
+ * whatever Atlas puts there and nothing of ours.
+ *
+ * Best-effort by design. Failing here would block a push for a project whose
+ * collections merely failed to import, and if the functions really are needed
+ * and really are missing, Atlas says so a moment later in its own words.
+ */
+export declare function seedDevDatabaseSearchHelpers(devDatabaseUrl: string, collectionsPath: string): Promise<void>;
 /**
  * Query the live database for every user table/view outside the system
  * catalogs. Separated from {@link getTableExcludes} so its failure mode can
@@ -37,3 +117,18 @@ export declare function getTableExcludes(databaseUrl: string, collectionsPath: s
     queryExistingTables?: (databaseUrl: string) => Promise<string[]>;
     getIncludes?: (collectionsPath: string) => Promise<string[]>;
 }): Promise<string[]>;
+/**
+ * Ask a yes/no question on an interactive terminal.
+ *
+ * The `isTTY` guard is the contract, not an optimisation: non-interactive
+ * shells (CI, pipes, agents) can never answer, and `readline` on a
+ * non-TTY stdin resolves with whatever the pipe happens to contain — or never
+ * resolves at all. Returning false there is what makes an unattended
+ * `db push` abort instead of auto-confirming a destructive change. Callers
+ * should already have gone through {@link decidePushSafety}, which decides
+ * whether interactive confirmation is even possible; this is the backstop.
+ *
+ * Lives here rather than in cli.ts so it is reachable from a test — cli.ts uses
+ * `import.meta` and cannot be imported by the jest runner.
+ */
+export declare function promptConfirm(question: string): Promise<boolean>;

package/dist/connection-BuZ97wsr.js

@@ -0,0 +1,250 @@
+import { createRequire as __createRequire } from "module";
+import "process";
+const require = __createRequire(import.meta.url);
+import { Pool } from "pg";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { logger } from "@rebasepro/server";
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, { get: (a, b) => (typeof require !== "undefined" ? require : a)[b] }) : x)(function(x) {
+	if (typeof require !== "undefined") return require.apply(this, arguments);
+	throw Error("Calling `require` for \"" + x + "\" in an environment that doesn't expose the `require` function. See https://rolldown.rs/in-depth/bundling-cjs#require-external-modules for more details.");
+});
+//#endregion
+//#region src/connection.ts
+var connection_exports = /* @__PURE__ */ __exportAll({
+	createDirectDatabaseConnection: () => createDirectDatabaseConnection,
+	createPostgresDatabaseConnection: () => createPostgresDatabaseConnection,
+	createReadReplicaConnection: () => createReadReplicaConnection,
+	guardPoolAgainstDirtyRelease: () => guardPoolAgainstDirtyRelease,
+	pinSearchPath: () => pinSearchPath
+});
+var DEFAULT_POOL = {
+	max: 20,
+	searchPath: "public",
+	idleTimeoutMillis: 3e4,
+	connectionTimeoutMillis: 1e4,
+	queryTimeout: 6e4,
+	statementTimeout: 3e4,
+	keepAlive: true
+};
+/** ReadyForQuery status byte: `I` idle, `T` in transaction, `E` failed transaction. */
+var TX_IDLE = "I";
+/**
+* Pin `search_path` into a connection string, so unqualified SQL resolves to a
+* schema this framework chose rather than to one Postgres inferred.
+*
+* Postgres defaults `search_path` to `"$user", public`: the *first* candidate
+* is a schema named after the connecting role. Rebase creates a schema called
+* `rebase` (auth, history, api keys), and every template, compose file and
+* deployment doc names the database role `rebase` too — so `$user` resolves to
+* a schema that exists, and every unqualified statement lands there instead of
+* in `public`. The generated Drizzle schema emits bare `pgTable("posts", …)`
+* for any collection without an explicit `schema`, which makes the *runtime's*
+* own reads and writes unqualified; a developer's raw `rebase.sql(...)`, the
+* Studio SQL editor and any hand-written migration are unqualified too. The
+* result is collection tables created in, and served from, `rebase`.
+*
+* Drizzle cannot express the fix on its side: `pgSchema("public")` throws by
+* design ("just use pgTable() instead"), so there is no way to emit a
+* public-qualified table from the generator. The pin has to live on the
+* connection.
+*
+* Precedence is deliberate and verified against node-postgres: `options` in
+* the connection string wins over the `options` field passed to `Pool`, so
+* rewriting the URL — rather than setting the field — is what makes this
+* authoritative. Two escape hatches survive it:
+*
+*  - an `options` that already mentions `search_path` is left untouched, so a
+*    deployment that deliberately pins something else keeps it;
+*  - `searchPath: false` (or an unparseable, non-URL connection string) sends
+*    nothing and inherits the server default.
+*
+* Anything else in `options` (a `statement_timeout`, say) is preserved and the
+* `search_path` flag is appended to it.
+*/
+function pinSearchPath(connectionString, searchPath = "public") {
+	if (searchPath === false) return connectionString;
+	let url;
+	try {
+		url = new URL(connectionString);
+	} catch {
+		return connectionString;
+	}
+	if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") return connectionString;
+	const existing = url.searchParams.get("options");
+	if (existing && /(^|\s)-c\s*search_path\s*=/.test(existing)) return connectionString;
+	const flag = `-c search_path=${searchPath}`;
+	url.searchParams.set("options", existing ? `${existing} ${flag}` : flag);
+	url.search = Array.from(url.searchParams.entries()).map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`).join("&");
+	return url.toString();
+}
+/**
+* Destroy pool clients that are released while still inside a transaction.
+*
+* pg-pool returns a client to the idle list whenever `release()` is called
+* without an error — even if the connection is still mid-transaction (status
+* `T`/`E`). That happens in practice: drizzle's pool transaction releases in
+* a `finally` after attempting ROLLBACK, and if the ROLLBACK itself fails
+* (e.g. it was queued behind a statement that hit the client-side
+* query_timeout), the client goes back dirty. The next checkout then runs
+* its statements inside the zombie transaction — with the previous request's
+* `app.*` RLS GUCs still applied, which turns unrelated queries into
+* RLS-scoped ones (observed in production as registration failing with
+* SQLSTATE 42501 under a leaked anonymous context).
+*
+* pg-pool emits `release` before it consults its private `_expired` set, so
+* marking the client expired here makes `_release()` destroy it instead of
+* pooling it. Both `client._txStatus` (pg ≥ 8.16) and `pool._expired` are
+* private APIs — feature-detect and fall back to loud logging so an upstream
+* change degrades to observability, never to silent corruption.
+*/
+function guardPoolAgainstDirtyRelease(pool, label) {
+	pool.on("release", (err, client) => {
+		if (err) return;
+		const txStatus = client?._txStatus;
+		if (typeof txStatus !== "string" || txStatus === TX_IDLE) return;
+		const expired = pool._expired;
+		if (expired && typeof expired.add === "function" && typeof expired.has === "function" && client && typeof client === "object") {
+			expired.add(client);
+			logger.error(`[${label}] Client released back to the pool while still in a transaction (status '${txStatus}') — destroying it so the open transaction and its session state (RLS GUCs) cannot leak into the next request.`);
+		} else logger.error(`[${label}] Client released mid-transaction (status '${txStatus}') but the pool's internal expiry set is unavailable (pg-pool internals changed?). The connection may leak its open transaction into subsequent requests.`);
+	});
+}
+/**
+* Create a Drizzle-backed Postgres connection with a production-grade
+* connection pool.
+*
+* @param connectionString  Postgres connection URL
+* @param schema            Optional Drizzle schema for the relational API
+* @param poolConfig        Optional pool tuning (merged over defaults)
+*
+* @returns `{ db, pool, connectionString }` — the `pool` is exposed so
+*          callers can register shutdown hooks (`pool.end()`) or monitor
+*          pool metrics.
+*/
+function createPostgresDatabaseConnection(connectionString, schema, poolConfig) {
+	const opts = {
+		...DEFAULT_POOL,
+		...poolConfig
+	};
+	connectionString = pinSearchPath(connectionString, opts.searchPath);
+	const pool = new Pool({
+		connectionString,
+		max: opts.max,
+		idleTimeoutMillis: opts.idleTimeoutMillis,
+		connectionTimeoutMillis: opts.connectionTimeoutMillis,
+		query_timeout: opts.queryTimeout,
+		statement_timeout: opts.statementTimeout,
+		keepAlive: opts.keepAlive,
+		keepAliveInitialDelayMillis: 0
+	});
+	pool.on("error", (err) => {
+		logger.error("[pg-pool] Unexpected pool error", { detail: err.message });
+		if (err.message.includes("ETIMEDOUT")) logger.warn("[pg-pool] Connection timeout detected — pool will auto-retry");
+	});
+	guardPoolAgainstDirtyRelease(pool, "pg-pool");
+	return {
+		db: schema ? drizzle(pool, { schema }) : drizzle(pool),
+		pool,
+		connectionString
+	};
+}
+/**
+* Create a direct (non-pooled) connection for operations that require
+* session-level features incompatible with PgBouncer transaction mode,
+* such as LISTEN/NOTIFY, prepared statements, or advisory locks.
+*
+* Uses a smaller pool since this is only for specific use cases.
+*/
+function createDirectDatabaseConnection(connectionString, schema, poolConfig) {
+	const opts = {
+		...DEFAULT_POOL,
+		max: 5,
+		...poolConfig
+	};
+	connectionString = pinSearchPath(connectionString, opts.searchPath);
+	const pool = new Pool({
+		connectionString,
+		max: opts.max,
+		idleTimeoutMillis: opts.idleTimeoutMillis,
+		connectionTimeoutMillis: opts.connectionTimeoutMillis,
+		query_timeout: opts.queryTimeout,
+		statement_timeout: opts.statementTimeout,
+		keepAlive: opts.keepAlive,
+		keepAliveInitialDelayMillis: 0
+	});
+	pool.on("error", (err) => {
+		logger.error("[pg-direct-pool] Unexpected pool error", { detail: err.message });
+	});
+	guardPoolAgainstDirtyRelease(pool, "pg-direct-pool");
+	return {
+		db: schema ? drizzle(pool, { schema }) : drizzle(pool),
+		pool,
+		connectionString
+	};
+}
+/**
+* Create a read-only connection for routing read queries to replicas.
+* Uses a moderate pool size since reads are distributed across replicas.
+*/
+function createReadReplicaConnection(connectionString, schema, poolConfig) {
+	const opts = {
+		...DEFAULT_POOL,
+		max: 10,
+		...poolConfig
+	};
+	connectionString = pinSearchPath(connectionString, opts.searchPath);
+	const pool = new Pool({
+		connectionString,
+		max: opts.max,
+		idleTimeoutMillis: opts.idleTimeoutMillis,
+		connectionTimeoutMillis: opts.connectionTimeoutMillis,
+		query_timeout: opts.queryTimeout,
+		statement_timeout: opts.statementTimeout,
+		keepAlive: opts.keepAlive,
+		keepAliveInitialDelayMillis: 0
+	});
+	pool.on("error", (err) => {
+		logger.error("[pg-replica-pool] Unexpected pool error", { detail: err.message });
+	});
+	guardPoolAgainstDirtyRelease(pool, "pg-replica-pool");
+	return {
+		db: schema ? drizzle(pool, { schema }) : drizzle(pool),
+		pool,
+		connectionString
+	};
+}
+//#endregion
+export { guardPoolAgainstDirtyRelease as a, __exportAll as c, createReadReplicaConnection as i, __require as l, createDirectDatabaseConnection as n, pinSearchPath as o, createPostgresDatabaseConnection as r, __commonJSMin as s, connection_exports as t, __toESM as u };
+
+//# sourceMappingURL=connection-BuZ97wsr.js.map

package/dist/connection-BuZ97wsr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-BuZ97wsr.js","names":[],"sources":["../src/connection.ts"],"sourcesContent":["import { Pool, PoolConfig } from \"pg\";\nimport { drizzle } from \"drizzle-orm/node-postgres\";\nimport { logger } from \"@rebasepro/server\";\n\n/**\n * Configuration for the Postgres connection pool.\n *\n * Sensible defaults are provided for production Cloud Run / single-instance\n * deployments. Override via environment variables or explicit config.\n */\nexport interface PostgresPoolConfig {\n    /** Maximum number of connections in the pool (default: 20) */\n    max?: number;\n    /** Close idle connections after this many ms (default: 30 000) */\n    idleTimeoutMillis?: number;\n    /** Abort connection attempts after this many ms (default: 10 000) */\n    connectionTimeoutMillis?: number;\n    /** Per-query timeout in ms (default: 30 000) */\n    queryTimeout?: number;\n    /** Per-statement timeout in ms (default: 30 000) */\n    statementTimeout?: number;\n    /** Enable TCP keep-alive (default: true) */\n    keepAlive?: boolean;\n    /**\n     * `search_path` pinned on every connection (default: `\"public\"`).\n     *\n     * Pass `false` to send no `search_path` at all and inherit whatever the\n     * server/role defaults to. See {@link pinSearchPath} for why the default\n     * is not \"inherit\".\n     */\n    searchPath?: string | false;\n}\n\nconst DEFAULT_POOL: Required<PostgresPoolConfig> = {\n    max: 20,\n    searchPath: \"public\",\n    idleTimeoutMillis: 30_000,\n    connectionTimeoutMillis: 10_000,\n    // The client-side read timeout MUST be comfortably above the server-side\n    // statement_timeout. When the client timer fires first, node-postgres\n    // abandons the in-flight statement but keeps the connection — inside a\n    // transaction that leaves the tx open (and any pending ROLLBACK is\n    // spliced out of the client queue before it ever reaches the wire), so\n    // the pooled connection is returned still in-transaction with its RLS\n    // GUCs set. The server abort (SQLSTATE 57014) is the clean path; the\n    // client timeout is only a backstop for a dead network.\n    queryTimeout: 60_000,\n    statementTimeout: 30_000,\n    keepAlive: true\n};\n\n/** ReadyForQuery status byte: `I` idle, `T` in transaction, `E` failed transaction. */\nconst TX_IDLE = \"I\";\n\n/**\n * Pin `search_path` into a connection string, so unqualified SQL resolves to a\n * schema this framework chose rather than to one Postgres inferred.\n *\n * Postgres defaults `search_path` to `\"$user\", public`: the *first* candidate\n * is a schema named after the connecting role. Rebase creates a schema called\n * `rebase` (auth, history, api keys), and every template, compose file and\n * deployment doc names the database role `rebase` too — so `$user` resolves to\n * a schema that exists, and every unqualified statement lands there instead of\n * in `public`. The generated Drizzle schema emits bare `pgTable(\"posts\", …)`\n * for any collection without an explicit `schema`, which makes the *runtime's*\n * own reads and writes unqualified; a developer's raw `rebase.sql(...)`, the\n * Studio SQL editor and any hand-written migration are unqualified too. The\n * result is collection tables created in, and served from, `rebase`.\n *\n * Drizzle cannot express the fix on its side: `pgSchema(\"public\")` throws by\n * design (\"just use pgTable() instead\"), so there is no way to emit a\n * public-qualified table from the generator. The pin has to live on the\n * connection.\n *\n * Precedence is deliberate and verified against node-postgres: `options` in\n * the connection string wins over the `options` field passed to `Pool`, so\n * rewriting the URL — rather than setting the field — is what makes this\n * authoritative. Two escape hatches survive it:\n *\n *  - an `options` that already mentions `search_path` is left untouched, so a\n *    deployment that deliberately pins something else keeps it;\n *  - `searchPath: false` (or an unparseable, non-URL connection string) sends\n *    nothing and inherits the server default.\n *\n * Anything else in `options` (a `statement_timeout`, say) is preserved and the\n * `search_path` flag is appended to it.\n */\nexport function pinSearchPath(connectionString: string, searchPath: string | false = \"public\"): string {\n    if (searchPath === false) return connectionString;\n\n    let url: URL;\n    try {\n        url = new URL(connectionString);\n    } catch {\n        // Key/value DSNs and anything else we cannot parse are returned as\n        // given: a connection that works unpinned beats one we corrupted.\n        return connectionString;\n    }\n    if (url.protocol !== \"postgres:\" && url.protocol !== \"postgresql:\") return connectionString;\n\n    const existing = url.searchParams.get(\"options\");\n    if (existing && /(^|\\s)-c\\s*search_path\\s*=/.test(existing)) return connectionString;\n\n    const flag = `-c search_path=${searchPath}`;\n    url.searchParams.set(\"options\", existing ? `${existing} ${flag}` : flag);\n    // Re-serialize by hand. `URLSearchParams` writes a space as `+`, which\n    // node-postgres happens to decode but libpq does not — and this same string\n    // is handed to `pg_dump`/`psql` for backups. Percent-encoding is the form\n    // both agree on, and is what the scaffolded `.env` already ships.\n    url.search = Array.from(url.searchParams.entries())\n        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)\n        .join(\"&\");\n    return url.toString();\n}\n\n/**\n * Destroy pool clients that are released while still inside a transaction.\n *\n * pg-pool returns a client to the idle list whenever `release()` is called\n * without an error — even if the connection is still mid-transaction (status\n * `T`/`E`). That happens in practice: drizzle's pool transaction releases in\n * a `finally` after attempting ROLLBACK, and if the ROLLBACK itself fails\n * (e.g. it was queued behind a statement that hit the client-side\n * query_timeout), the client goes back dirty. The next checkout then runs\n * its statements inside the zombie transaction — with the previous request's\n * `app.*` RLS GUCs still applied, which turns unrelated queries into\n * RLS-scoped ones (observed in production as registration failing with\n * SQLSTATE 42501 under a leaked anonymous context).\n *\n * pg-pool emits `release` before it consults its private `_expired` set, so\n * marking the client expired here makes `_release()` destroy it instead of\n * pooling it. Both `client._txStatus` (pg ≥ 8.16) and `pool._expired` are\n * private APIs — feature-detect and fall back to loud logging so an upstream\n * change degrades to observability, never to silent corruption.\n */\nexport function guardPoolAgainstDirtyRelease(pool: Pool, label: string): void {\n    pool.on(\"release\", (err: Error | undefined, client: unknown) => {\n        if (err) return; // errored clients are already destroyed by pg-pool\n        const txStatus = (client as { _txStatus?: string | null })?._txStatus;\n        if (typeof txStatus !== \"string\" || txStatus === TX_IDLE) return;\n\n        // pg-pool keeps expired clients in a WeakSet (a plain object works too\n        // if upstream ever changes it — duck-type on add/has).\n        const expired = (pool as unknown as { _expired?: { add(c: object): unknown; has(c: object): boolean } })._expired;\n        if (expired && typeof expired.add === \"function\" && typeof expired.has === \"function\" && client && typeof client === \"object\") {\n            expired.add(client);\n            logger.error(\n                `[${label}] Client released back to the pool while still in a transaction ` +\n                `(status '${txStatus}') — destroying it so the open transaction and its ` +\n                `session state (RLS GUCs) cannot leak into the next request.`\n            );\n        } else {\n            logger.error(\n                `[${label}] Client released mid-transaction (status '${txStatus}') but the ` +\n                `pool's internal expiry set is unavailable (pg-pool internals changed?). ` +\n                `The connection may leak its open transaction into subsequent requests.`\n            );\n        }\n    });\n}\n\n/**\n * Create a Drizzle-backed Postgres connection with a production-grade\n * connection pool.\n *\n * @param connectionString  Postgres connection URL\n * @param schema            Optional Drizzle schema for the relational API\n * @param poolConfig        Optional pool tuning (merged over defaults)\n *\n * @returns `{ db, pool, connectionString }` — the `pool` is exposed so\n *          callers can register shutdown hooks (`pool.end()`) or monitor\n *          pool metrics.\n */\nexport function createPostgresDatabaseConnection(\n    connectionString: string,\n    schema?: Record<string, unknown>,\n    poolConfig?: PostgresPoolConfig\n) {\n    const opts = { ...DEFAULT_POOL,\n...poolConfig };\n    connectionString = pinSearchPath(connectionString, opts.searchPath);\n\n    const pgPoolConfig: PoolConfig = {\n        connectionString,\n        max: opts.max,\n        idleTimeoutMillis: opts.idleTimeoutMillis,\n        connectionTimeoutMillis: opts.connectionTimeoutMillis,\n        query_timeout: opts.queryTimeout,\n        statement_timeout: opts.statementTimeout,\n        keepAlive: opts.keepAlive,\n        keepAliveInitialDelayMillis: 0\n    };\n\n    const pool = new Pool(pgPoolConfig);\n\n    // ── Pool event logging ────────────────────────────────────────────────\n    // Uses console.* because the structured logger lives in server\n    // (a separate package). The caller can replace these with the structured\n    // logger if desired via pool.on() after creation.\n    pool.on(\"error\", (err) => {\n        logger.error(\"[pg-pool] Unexpected pool error\", { detail: err.message });\n        if (err.message.includes(\"ETIMEDOUT\")) {\n            logger.warn(\"[pg-pool] Connection timeout detected — pool will auto-retry\");\n        }\n    });\n    guardPoolAgainstDirtyRelease(pool, \"pg-pool\");\n\n    // Create drizzle instance — pass schema when available to enable db.query relational API\n    const db = schema ? drizzle(pool, { schema }) : drizzle(pool);\n\n    return { db,\npool,\nconnectionString };\n}\n\n/**\n * Create a direct (non-pooled) connection for operations that require\n * session-level features incompatible with PgBouncer transaction mode,\n * such as LISTEN/NOTIFY, prepared statements, or advisory locks.\n *\n * Uses a smaller pool since this is only for specific use cases.\n */\nexport function createDirectDatabaseConnection(\n    connectionString: string,\n    schema?: Record<string, unknown>,\n    poolConfig?: PostgresPoolConfig\n) {\n    const opts = {\n        ...DEFAULT_POOL,\n        max: 5,\n        ...poolConfig\n    };\n    connectionString = pinSearchPath(connectionString, opts.searchPath);\n\n    const pgPoolConfig: PoolConfig = {\n        connectionString,\n        max: opts.max,\n        idleTimeoutMillis: opts.idleTimeoutMillis,\n        connectionTimeoutMillis: opts.connectionTimeoutMillis,\n        query_timeout: opts.queryTimeout,\n        statement_timeout: opts.statementTimeout,\n        keepAlive: opts.keepAlive,\n        keepAliveInitialDelayMillis: 0\n    };\n\n    const pool = new Pool(pgPoolConfig);\n\n    pool.on(\"error\", (err) => {\n        logger.error(\"[pg-direct-pool] Unexpected pool error\", { detail: err.message });\n    });\n    guardPoolAgainstDirtyRelease(pool, \"pg-direct-pool\");\n\n    const db = schema ? drizzle(pool, { schema }) : drizzle(pool);\n\n    return { db,\npool,\nconnectionString };\n}\n\n/**\n * Create a read-only connection for routing read queries to replicas.\n * Uses a moderate pool size since reads are distributed across replicas.\n */\nexport function createReadReplicaConnection(\n    connectionString: string,\n    schema?: Record<string, unknown>,\n    poolConfig?: PostgresPoolConfig\n) {\n    const opts = {\n        ...DEFAULT_POOL,\n        max: 10,\n        ...poolConfig\n    };\n    connectionString = pinSearchPath(connectionString, opts.searchPath);\n\n    const pgPoolConfig: PoolConfig = {\n        connectionString,\n        max: opts.max,\n        idleTimeoutMillis: opts.idleTimeoutMillis,\n        connectionTimeoutMillis: opts.connectionTimeoutMillis,\n        query_timeout: opts.queryTimeout,\n        statement_timeout: opts.statementTimeout,\n        keepAlive: opts.keepAlive,\n        keepAliveInitialDelayMillis: 0\n    };\n\n    const pool = new Pool(pgPoolConfig);\n\n    pool.on(\"error\", (err) => {\n        logger.error(\"[pg-replica-pool] Unexpected pool error\", { detail: err.message });\n    });\n    guardPoolAgainstDirtyRelease(pool, \"pg-replica-pool\");\n\n    const db = schema ? drizzle(pool, { schema }) : drizzle(pool);\n\n    return { db,\npool,\nconnectionString };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,IAAM,eAA6C;CAC/C,KAAK;CACL,YAAY;CACZ,mBAAmB;CACnB,yBAAyB;CASzB,cAAc;CACd,kBAAkB;CAClB,WAAW;AACf;;AAGA,IAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmChB,SAAgB,cAAc,kBAA0B,aAA6B,UAAkB;CACnG,IAAI,eAAe,OAAO,OAAO;CAEjC,IAAI;CACJ,IAAI;EACA,MAAM,IAAI,IAAI,gBAAgB;CAClC,QAAQ;EAGJ,OAAO;CACX;CACA,IAAI,IAAI,aAAa,eAAe,IAAI,aAAa,eAAe,OAAO;CAE3E,MAAM,WAAW,IAAI,aAAa,IAAI,SAAS;CAC/C,IAAI,YAAY,6BAA6B,KAAK,QAAQ,GAAG,OAAO;CAEpE,MAAM,OAAO,kBAAkB;CAC/B,IAAI,aAAa,IAAI,WAAW,WAAW,GAAG,SAAS,GAAG,SAAS,IAAI;CAKvE,IAAI,SAAS,MAAM,KAAK,IAAI,aAAa,QAAQ,CAAC,CAAC,CAC9C,KAAK,CAAC,KAAK,WAAW,GAAG,mBAAmB,GAAG,EAAE,GAAG,mBAAmB,KAAK,GAAG,CAAC,CAChF,KAAK,GAAG;CACb,OAAO,IAAI,SAAS;AACxB;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,6BAA6B,MAAY,OAAqB;CAC1E,KAAK,GAAG,YAAY,KAAwB,WAAoB;EAC5D,IAAI,KAAK;EACT,MAAM,WAAY,QAA0C;EAC5D,IAAI,OAAO,aAAa,YAAY,aAAa,SAAS;EAI1D,MAAM,UAAW,KAAwF;EACzG,IAAI,WAAW,OAAO,QAAQ,QAAQ,cAAc,OAAO,QAAQ,QAAQ,cAAc,UAAU,OAAO,WAAW,UAAU;GAC3H,QAAQ,IAAI,MAAM;GAClB,OAAO,MACH,IAAI,MAAM,2EACE,SAAS,+GAEzB;EACJ,OACI,OAAO,MACH,IAAI,MAAM,6CAA6C,SAAS,0JAGpE;CAER,CAAC;AACL;;;;;;;;;;;;;AAcA,SAAgB,iCACZ,kBACA,QACA,YACF;CACE,MAAM,OAAO;EAAE,GAAG;EACtB,GAAG;CAAW;CACV,mBAAmB,cAAc,kBAAkB,KAAK,UAAU;CAalE,MAAM,OAAO,IAAI,KAAK;EAVlB;EACA,KAAK,KAAK;EACV,mBAAmB,KAAK;EACxB,yBAAyB,KAAK;EAC9B,eAAe,KAAK;EACpB,mBAAmB,KAAK;EACxB,WAAW,KAAK;EAChB,6BAA6B;CAGX,CAAY;CAMlC,KAAK,GAAG,UAAU,QAAQ;EACtB,OAAO,MAAM,mCAAmC,EAAE,QAAQ,IAAI,QAAQ,CAAC;EACvE,IAAI,IAAI,QAAQ,SAAS,WAAW,GAChC,OAAO,KAAK,8DAA8D;CAElF,CAAC;CACD,6BAA6B,MAAM,SAAS;CAK5C,OAAO;EAAE,IAFE,SAAS,QAAQ,MAAM,EAAE,OAAO,CAAC,IAAI,QAAQ,IAAI;EAGhE;EACA;CAAiB;AACjB;;;;;;;;AASA,SAAgB,+BACZ,kBACA,QACA,YACF;CACE,MAAM,OAAO;EACT,GAAG;EACH,KAAK;EACL,GAAG;CACP;CACA,mBAAmB,cAAc,kBAAkB,KAAK,UAAU;CAalE,MAAM,OAAO,IAAI,KAAK;EAVlB;EACA,KAAK,KAAK;EACV,mBAAmB,KAAK;EACxB,yBAAyB,KAAK;EAC9B,eAAe,KAAK;EACpB,mBAAmB,KAAK;EACxB,WAAW,KAAK;EAChB,6BAA6B;CAGX,CAAY;CAElC,KAAK,GAAG,UAAU,QAAQ;EACtB,OAAO,MAAM,0CAA0C,EAAE,QAAQ,IAAI,QAAQ,CAAC;CAClF,CAAC;CACD,6BAA6B,MAAM,gBAAgB;CAInD,OAAO;EAAE,IAFE,SAAS,QAAQ,MAAM,EAAE,OAAO,CAAC,IAAI,QAAQ,IAAI;EAGhE;EACA;CAAiB;AACjB;;;;;AAMA,SAAgB,4BACZ,kBACA,QACA,YACF;CACE,MAAM,OAAO;EACT,GAAG;EACH,KAAK;EACL,GAAG;CACP;CACA,mBAAmB,cAAc,kBAAkB,KAAK,UAAU;CAalE,MAAM,OAAO,IAAI,KAAK;EAVlB;EACA,KAAK,KAAK;EACV,mBAAmB,KAAK;EACxB,yBAAyB,KAAK;EAC9B,eAAe,KAAK;EACpB,mBAAmB,KAAK;EACxB,WAAW,KAAK;EAChB,6BAA6B;CAGX,CAAY;CAElC,KAAK,GAAG,UAAU,QAAQ;EACtB,OAAO,MAAM,2CAA2C,EAAE,QAAQ,IAAI,QAAQ,CAAC;CACnF,CAAC;CACD,6BAA6B,MAAM,iBAAiB;CAIpD,OAAO;EAAE,IAFE,SAAS,QAAQ,MAAM,EAAE,OAAO,CAAC,IAAI,QAAQ,IAAI;EAGhE;EACA;CAAiB;AACjB"}

package/dist/connection.d.ts

@@ -18,7 +18,49 @@ export interface PostgresPoolConfig {
     statementTimeout?: number;
     /** Enable TCP keep-alive (default: true) */
     keepAlive?: boolean;
+    /**
+     * `search_path` pinned on every connection (default: `"public"`).
+     *
+     * Pass `false` to send no `search_path` at all and inherit whatever the
+     * server/role defaults to. See {@link pinSearchPath} for why the default
+     * is not "inherit".
+     */
+    searchPath?: string | false;
 }
+/**
+ * Pin `search_path` into a connection string, so unqualified SQL resolves to a
+ * schema this framework chose rather than to one Postgres inferred.
+ *
+ * Postgres defaults `search_path` to `"$user", public`: the *first* candidate
+ * is a schema named after the connecting role. Rebase creates a schema called
+ * `rebase` (auth, history, api keys), and every template, compose file and
+ * deployment doc names the database role `rebase` too — so `$user` resolves to
+ * a schema that exists, and every unqualified statement lands there instead of
+ * in `public`. The generated Drizzle schema emits bare `pgTable("posts", …)`
+ * for any collection without an explicit `schema`, which makes the *runtime's*
+ * own reads and writes unqualified; a developer's raw `rebase.sql(...)`, the
+ * Studio SQL editor and any hand-written migration are unqualified too. The
+ * result is collection tables created in, and served from, `rebase`.
+ *
+ * Drizzle cannot express the fix on its side: `pgSchema("public")` throws by
+ * design ("just use pgTable() instead"), so there is no way to emit a
+ * public-qualified table from the generator. The pin has to live on the
+ * connection.
+ *
+ * Precedence is deliberate and verified against node-postgres: `options` in
+ * the connection string wins over the `options` field passed to `Pool`, so
+ * rewriting the URL — rather than setting the field — is what makes this
+ * authoritative. Two escape hatches survive it:
+ *
+ *  - an `options` that already mentions `search_path` is left untouched, so a
+ *    deployment that deliberately pins something else keeps it;
+ *  - `searchPath: false` (or an unparseable, non-URL connection string) sends
+ *    nothing and inherits the server default.
+ *
+ * Anything else in `options` (a `statement_timeout`, say) is preserved and the
+ * `search_path` flag is appended to it.
+ */
+export declare function pinSearchPath(connectionString: string, searchPath?: string | false): string;
 /**
  * Destroy pool clients that are released while still inside a transaction.
  *

package/dist/data-transformer.d.ts

@@ -42,9 +42,14 @@ export declare function sanitizeAndConvertDates(obj: unknown): unknown;
  */
 export declare function serializeDataToServer<M extends Record<string, unknown>>(row: M, properties: Properties, collection?: CollectionConfig, registry?: PostgresCollectionRegistry): SerializedEntityData;
 /**
- * Serialize a single property value for database storage
+ * Serialize a single property value for database storage.
+ *
+ * `propertyKey` is only ever used to phrase errors and warnings. Without it the
+ * one trace a bad value left was `Expected array value for array property, got
+ * string` — no collection, no property, no value, which in the log of a
+ * thousand-row import names nothing at all.
  */
-export declare function serializePropertyToServer(value: unknown, property: Property): unknown;
+export declare function serializePropertyToServer(value: unknown, property: Property, propertyKey?: string): unknown;
 /**
  * Transform IDs back to relation objects for frontend
  */

package/dist/data_driver-ULAyJEi9.js

@@ -0,0 +1,193 @@
+import { createRequire as __createRequire } from "module";
+import "process";
+__createRequire(import.meta.url);
+//#region ../types/src/errors.ts
+/**
+* The single error type thrown across the entire Rebase client surface —
+* HTTP data/control-plane calls, realtime/WebSocket operations, and
+* client-side logic errors (e.g. an unknown collection accessor). A `catch`
+* block only ever needs to check for this one class:
+*
+* ```ts
+* import { RebaseApiError } from "@rebasepro/client"; // re-exported
+*
+* try {
+*   await client.data.products.update(id, { price: 9 });
+* } catch (e) {
+*   if (e instanceof RebaseApiError) {
+*     if (e.status === 404) { ... }   // HTTP failures carry a status
+*     console.error(e.code, e.details);
+*   }
+* }
+* ```
+*
+* `status` is present for HTTP failures and `undefined` otherwise, so its
+* presence distinguishes transport-level errors from realtime/logic errors.
+*
+* @group Errors
+*/
+var RebaseApiError = class extends Error {
+	/** HTTP status code, or `undefined` for non-HTTP errors. */
+	status;
+	/** Stable machine-readable error code, when the server supplied one. See {@link RebaseErrorCode}. */
+	code;
+	/** Structured error payload from the server, when present. */
+	details;
+	constructor(message, init = {}) {
+		super(message);
+		this.name = "RebaseApiError";
+		this.status = init.status;
+		this.code = init.code;
+		this.details = init.details;
+		if (init.cause !== void 0) this.cause = init.cause;
+	}
+};
+//#endregion
+//#region ../types/src/types/policy.ts
+/**
+* The id a request without a logged-in user reports as `rebase.uid()`.
+*
+* A user-context request always sets `app.uid`: blank would read back as
+* `NULL`, and `NULL` is how the trusted server context is recognised, so an
+* anonymous visitor would be promoted to server privileges. The driver
+* therefore substitutes this sentinel at the single chokepoint where the GUC
+* is set.
+*
+* The consequence for policy authors is that **`rebase.uid() IS NOT NULL` is a
+* tautology on the user path** — it is true for anonymous visitors too. Use
+* {@link policy.authenticated} to mean "signed in", and
+* {@link policy.serverContext} to mean "the trusted server context". Do not
+* hand-write the comparison: see {@link ANONYMOUS_USER_IDS} for why one
+* literal is not enough.
+*
+* @group Models
+*/
+var ANONYMOUS_USER_ID = "anonymous";
+/**
+* Every uid that has ever meant "nobody is signed in" — newest first.
+*
+* There are two because there were two. The types, the policy compiler, the
+* JavaScript evaluator and the linter were all built on
+* {@link ANONYMOUS_USER_ID}, while the request path scoped unauthenticated
+* callers as `'anon'` — so `policy.authenticated()`, which compiled to
+* `rebase.uid() <> 'anonymous'`, was *true* for an anonymous visitor. The
+* sanctioned way to write "signed in" granted to everyone, and the linter
+* flagged the spelling that actually worked as a foreign convention.
+*
+* The request path now reports {@link ANONYMOUS_USER_ID}. `'anon'` stays here
+* because policies outlive the server that generated them: a database still
+* holding policies from before the fix, or a project whose server has not been
+* upgraded yet, must not become a grant in either direction. Compile against
+* this list, not against a single literal.
+*
+* No real user id is ever one of these, so a match is always "not signed in".
+*
+* @group Models
+*/
+var ANONYMOUS_USER_IDS = [ANONYMOUS_USER_ID, "anon"];
+/** @group Models */
+var policy = {
+	true: () => ({ kind: "true" }),
+	false: () => ({ kind: "false" }),
+	and: (...operands) => ({
+		kind: "and",
+		operands
+	}),
+	or: (...operands) => ({
+		kind: "or",
+		operands
+	}),
+	not: (operand) => ({
+		kind: "not",
+		operand
+	}),
+	compare: (left, op, right) => ({
+		kind: "compare",
+		op,
+		left,
+		right
+	}),
+	rolesOverlap: (roles) => ({
+		kind: "rolesOverlap",
+		roles
+	}),
+	rolesContain: (roles) => ({
+		kind: "rolesContain",
+		roles
+	}),
+	authenticated: () => ({ kind: "authenticated" }),
+	serverContext: () => ({ kind: "serverContext" }),
+	existsIn: (args) => ({
+		kind: "existsIn",
+		collection: args.collection,
+		where: args.where
+	}),
+	raw: (sql) => ({
+		kind: "raw",
+		sql
+	}),
+	field: (name) => ({
+		kind: "field",
+		name
+	}),
+	outerField: (name) => ({
+		kind: "outerField",
+		name
+	}),
+	literal: (value) => ({
+		kind: "literal",
+		value
+	}),
+	authUid: () => ({ kind: "authUid" }),
+	authRoles: () => ({ kind: "authRoles" })
+};
+/**
+* Thrown by {@link resolveClientListLimit} for a `limit` the platform will not
+* serve. Carries an HTTP status so an ingress that speaks HTTP can forward it
+* verbatim, and `maxLimit` so one can be built without re-deriving the ceiling.
+*
+* @group Errors
+*/
+var ListLimitError = class ListLimitError extends RebaseApiError {
+	/** The ceiling that was exceeded — what the caller should page by instead. */
+	maxLimit;
+	constructor(message, maxLimit) {
+		super(message, {
+			status: 400,
+			code: "INVALID_LIMIT"
+		});
+		this.name = "ListLimitError";
+		this.maxLimit = maxLimit;
+		Object.setPrototypeOf(this, ListLimitError.prototype);
+	}
+};
+/**
+* Resolve a client-supplied list `limit` into a safe, always-defined value.
+*
+* - An absent / blank limit falls back to the mode default:
+*   `vectorDefaultLimit` for a vector search, otherwise `defaultLimit`.
+* - A limit that is present must be an integer in `[1, maxLimit]`. Anything
+*   else — `0`, a negative, `1.5`, `abc`, `100000000` — throws
+*   {@link ListLimitError} rather than being coerced into range, because every
+*   coercion answers a question the caller did not ask with a page it cannot
+*   tell apart from the whole collection.
+*
+* The return is never `undefined` — no ingress that routes its client limit
+* through this can produce an unbounded read.
+*
+* @throws {ListLimitError} when a present `limit` is not an integer in range.
+*/
+function resolveClientListLimit(rawLimit, opts = {}) {
+	const maxLimit = opts.maxLimit ?? 1e3;
+	if (rawLimit != null && String(rawLimit).trim() !== "") {
+		const parsed = typeof rawLimit === "number" ? rawLimit : Number(String(rawLimit).trim());
+		if (!Number.isInteger(parsed) || parsed < 1) throw new ListLimitError(`Invalid \`limit\`: ${String(rawLimit)}. Expected a whole number between 1 and ${maxLimit}.`, maxLimit);
+		if (parsed > maxLimit) throw new ListLimitError(`\`limit\` ${parsed} is above the maximum of ${maxLimit}. Ask for at most ${maxLimit} rows per read and page through the rest with \`offset\` — answering with a smaller page would be indistinguishable from there being no more rows.`, maxLimit);
+		return parsed;
+	}
+	return opts.vectorSearch ? opts.vectorDefaultLimit ?? 10 : opts.defaultLimit ?? 50;
+}
+//#endregion
+export { policy as a, ANONYMOUS_USER_IDS as i, resolveClientListLimit as n, ANONYMOUS_USER_ID as r, ListLimitError as t };
+
+//# sourceMappingURL=data_driver-ULAyJEi9.js.map