@onreza/sqlx-js 0.3.0 → 0.4.0

package/README.md

@@ -36,8 +36,10 @@ const rows = await sql(
 - **Linear migrations** with hash tampering detection.
 - **Migration squash baselines** via `migrate squash`: generate a schema-only baseline from a shadow database, then hash-adopt it on already-migrated databases.
 - **Runtime `migrate()`** with PostgreSQL advisory lock, safe for multi-replica startup.
+- **Optional pgschema workflow** via `init --schema-provider pgschema` and `sqlx-js db install|check|plan|apply` for PostgreSQL schema-as-code projects.
 - **Offline cache** committed to your repo. CI verifies via `prepare --check` without a database.
 - **Schema snapshot + LLM manifest** via `schema dump` / `schema check`: tables, columns, constraints, indexes, types, and function/procedure metadata are introspected from PostgreSQL.
+- **Generated function catalog** via `KnownFunctions`: `prepare` records user-schema PostgreSQL functions/procedures from `pg_proc` with approximate parameter and return TypeScript types.
 - **Shadow database validation** via `migrate dev` / `migrate verify`: auto-create a disposable shadow DB, apply migrations, validate SQL, and drop it afterwards.
 - **Safe identifier quoting** via `sql.id(...)`, backed by the committed schema snapshot whitelist.
 - **Single runtime adapter**: Postgres.js backs the runtime on Node/Bun-compatible environments — no Bun.SQL-specific adapter to choose.
@@ -64,6 +66,16 @@ npx @onreza/sqlx-js init
 
 Creates `sqlx-js.config.ts`, a `migrations/` directory, and `.env.example` if they don't already exist (it never overwrites existing files), then prints the next steps. Skip it if you prefer to wire things up manually.
 
+For declarative PostgreSQL schema management, scaffold the pgschema workflow instead:
+
+```bash
+npx @onreza/sqlx-js init --schema-provider pgschema
+```
+
+This creates `schema.sql` and configures `schema.provider = "pgschema"` in `sqlx-js.config.ts`. The npm package does not bundle pgschema, but `sqlx-js db install` downloads the pinned pgschema binary into `node_modules/.cache/sqlx-js/pgschema/`; then `sqlx-js db check` verifies it.
+
+The managed pgschema workflow supports Linux and macOS. On Windows, run sqlx-js under WSL/Linux/macOS or use the built-in `sqlx-js migrate` workflow.
+
 ### 1. Configure the database URL
 
 ```bash
@@ -334,7 +346,8 @@ In addition to `import { sql } from "@onreza/sqlx-js"`, the scanner recognises `
 ## CLI
 
 ```
-sqlx-js init [--root <dir>]
+sqlx-js init [--root <dir>] [--schema-provider builtin|pgschema]
+sqlx-js db install | check | plan | apply [--root <dir>] [-- <pgschema args>]
 sqlx-js prepare [--check | --watch] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]
 sqlx-js migrate dev [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | verify [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | run [--dry-run] [--json] [--lock-timeout <ms>] | info [--json] | check [--json] | revert [--dry-run] [--json] [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | add <name> | squash <name> [--shadow-admin-url <url> | --shadow-url <url>] [--replace] [--pg-dump <path>] [--lock-timeout <ms>] | archive list | archive restore <name> [--force]
 sqlx-js schema dump | check [--schema <path>] [--manifest <path>] [--no-manifest] [--shadow-url <url>]
@@ -362,6 +375,7 @@ Regular `prepare` describes queries across a small connection pool (default 8, o
 | `--schema <path>`     | Schema snapshot path (default: `<root>/.sqlx-js/schema/schema.json`).               |
 | `--manifest <path>`   | LLM schema manifest path (default: `<root>/.sqlx-js/schema/schema.md`).             |
 | `--no-manifest`       | Skip writing the LLM schema manifest during `schema dump`.                           |
+| `--schema-provider <name>` | For `init`: `builtin` (default) or `pgschema`.                                |
 
 Flags that take a value accept both `--flag value` and `--flag=value` forms.
 
@@ -369,6 +383,20 @@ Flags that take a value accept both `--flag value` and `--flag=value` forms.
 
 ### Development and deployment flows
 
+For complex PostgreSQL schemas with functions, triggers, RLS, grants, partitions, and other schema-level objects, prefer pgschema for DDL ownership and use sqlx-js for application-query typing:
+
+```bash
+sqlx-js init --schema-provider pgschema
+sqlx-js db install
+sqlx-js db check
+# edit schema.sql
+sqlx-js db plan -- --output-json plan.json
+sqlx-js db apply -- --auto-approve
+sqlx-js prepare
+```
+
+`sqlx-js db install` installs the pinned pgschema version used by this sqlx-js release. `sqlx-js db check`, `plan`, and `apply` use `schema.command` when configured; otherwise they prefer the managed binary under `node_modules/.cache/sqlx-js/pgschema/` and fall back to `pgschema` on `PATH`. `plan` and file-backed `apply` translate `DATABASE_URL` into `--host`, `--port`, `--db`, `--user`, `--file`, and `--schema` arguments, pass the password through `PGPASSWORD`, pass TLS settings through `PGSSLMODE` / `PGSSLROOTCERT` / `PGSSLCERT` / `PGSSLKEY`, and forward any arguments after `--` directly to pgschema. `sqlx-js db apply -- --plan plan.json` applies a reviewed pgschema plan without requiring the local `schema.sql` file. The schema provider is configured in `sqlx-js.config.ts`; by default the schema file is `schema.sql` and the schema is `public`. The pinned pgschema 1.12.0 CLI accepts a single `--schema` value, so sqlx-js rejects pgschema configs with more than one schema instead of silently applying only one.
+
 Use `migrate dev` while developing migrations and SQL:
 
 ```bash
@@ -379,6 +407,8 @@ sqlx-js migrate dev
 
 `migrate dev` creates a disposable shadow database, applies all migrations from scratch, validates that the latest migration's `.down.sql` restores the previous schema (squash baselines may omit `.down.sql`), prepares project SQL against the shadow schema, writes `.sqlx-js/` plus `sqlx-js-env.d.ts`, and drops the shadow database. This means you can keep editing a local WIP migration before it is merged. You do not need to drop your application database or create a new migration for every local edit.
 
+The built-in `migrate` workflow is kept for simple projects and embedded application startup. PostgreSQL-heavy schema lifecycle features belong in pgschema rather than in sqlx-js.
+
 Use `migrate verify` in PR/CI before merge:
 
 ```bash
@@ -449,6 +479,11 @@ Phases reported separately: `describe failed`, `analyze failed`, `paramMap faile
 import type { SqlxJsConfig } from "@onreza/sqlx-js";
 
 const config: SqlxJsConfig = {
+  schema: {
+    provider: "pgschema",
+    file: "schema.sql",
+    schemas: ["public"],
+  },
   jsonbTypes: {
     "users.settings":     "SqlxJsJson.UserSettings",
     "posts.meta":         "SqlxJsJson.PostMeta",
@@ -459,6 +494,8 @@ const config: SqlxJsConfig = {
 export default config;
 ```
 
+The `schema` block is optional. Use `provider: "pgschema"` when sqlx-js should delegate schema planning/apply commands to pgschema. `command` can override the managed binary lookup and point at another executable. With the pinned pgschema 1.12.0 CLI, `schemas` must contain exactly one schema name.
+
 Declare the referenced types anywhere in your project (`.d.ts` file is conventional):
 
 ```ts
@@ -535,7 +572,10 @@ Commit the generated `sqlx-js-env.d.ts` and the `.sqlx-js/` cache directory to y
 
 ```yaml
 - run: bun install
-- run: sqlx-js migrate verify    # builds schema from migrations in a disposable shadow DB
+- run: sqlx-js migrate verify    # built-in migration workflow
+# or, when schema.provider is "pgschema":
+- run: sqlx-js db install
+- run: sqlx-js db plan -- --output-json plan.json
 - run: sqlx-js prepare --check   # fails if any query is missing from the committed cache
 - run: sqlx-js schema check      # fails if the committed schema snapshot is stale
 - run: tsc --noEmit               # fails if types are stale
@@ -543,7 +583,9 @@ Commit the generated `sqlx-js-env.d.ts` and the `.sqlx-js/` cache directory to y
 - run: bun run build              # emits publishable JS + declarations under dist/
 ```
 
-The `migrate verify` step needs `DATABASE_URL` credentials that can either create a temporary database or use `--shadow-admin-url` / `--shadow-url`. It does not write `.sqlx-js/` or `sqlx-js-env.d.ts`. The `prepare --check` step then runs without a database; your committed offline cache is the source of truth. `schema check` intentionally uses a live database because it verifies the committed schema contract against PostgreSQL.
+The `migrate verify` step needs `DATABASE_URL` credentials that can either create a temporary database or use `--shadow-admin-url` / `--shadow-url`. It does not write `.sqlx-js/` or `sqlx-js-env.d.ts`. For pgschema projects, `sqlx-js db plan` checks the desired `schema.sql` against the target database and leaves application query typing to `prepare`. The `prepare --check` step then runs without a database; your committed offline cache is the source of truth. `schema check` intentionally uses a live database because it verifies the committed schema contract against PostgreSQL.
+
+The managed pgschema binary is installed under `node_modules/.cache/sqlx-js/pgschema/`, not `.sqlx-js/`, so it is not part of the committed offline cache.
 
 ## Contributing
 

package/ROADMAP.md

@@ -6,7 +6,8 @@ Items already shipped live in the [README](./README.md) feature list; this file
 
 | Feature | ROI | Notes |
 |---------|-----|-------|
-| Migration lifecycle improvements | 8 | Squash baseline MVP, `migrate run --dry-run`, read-only `migrate info`, archive/restore helpers, JSON operator output, filesystem-only `migrate check`, and shadow-based `migrate revert --dry-run` exist; continue with safer migration lifecycle guardrails. This is the foundation for reliable external migration import. |
+| pgschema integration hardening | 8 | Basic `init --schema-provider pgschema` plus managed `sqlx-js db install/check/plan/apply` exists. Continue with better docs, CI examples, schema snapshot handoff, and migration guidance for projects that outgrow built-in migrations. |
+| Built-in migration lifecycle maintenance | 5 | Keep `migrate run/dev/verify/revert/squash/archive` stable for simple projects and application startup, but avoid expanding it into a full PostgreSQL schema-as-code system. |
 | Prisma migration assistant | 7 | Import Prisma Migrate SQL history and Prisma TypedSQL/raw SQL into `sqlx-js`; classify Prisma Client CRUD/nested-write sites as assisted/manual instead of promising a fully automatic ORM rewrite. |
 | Self-join precision (unqualified ColumnRef) | 4 | `SELECT name FROM users u1 JOIN users u2 ON ...` with unqualified `name` can't be attributed to a specific alias. PG would reject ambiguous unqualified refs anyway, but explicit aliasing currently has no narrowing benefit in self-joins. |
 | `INSERT INTO t VALUES (...)` without column list | 3 | Map params by `pg_attribute attnum` ordering. Rare in practice — most teams use explicit column lists. |

package/dist/bin/sqlx-js.js

@@ -7,6 +7,8 @@ import { runWatch } from "../src/commands/watch.js";
 import { migrateArchiveList, migrateArchiveRestore, migrateCheck, migrateDev, migrateRun, migrateInfo, migrateRevert, migrateAdd, migrateSquash, migrateVerify, } from "../src/commands/migrate.js";
 import { applyShadowMigrations, runSchemaCheck, runSchemaDump } from "../src/commands/schema.js";
 import { runInit } from "../src/commands/init.js";
+import { runPgschemaCommand, runPgschemaInstall } from "../src/commands/pgschema.js";
+import { loadConfig } from "../src/config.js";
 function packageVersion() {
     const here = dirname(fileURLToPath(import.meta.url));
     for (const path of [join(here, "../package.json"), join(here, "../../package.json")]) {
@@ -23,7 +25,8 @@ function help() {
     console.error(`sqlx-js — compile-time-checked SQL for TypeScript + Postgres (v${VERSION})
 
 usage:
-  sqlx-js init [--root <dir>]
+  sqlx-js init [--root <dir>] [--schema-provider builtin|pgschema]
+  sqlx-js db install | check | plan | apply [--root <dir>] [-- <pgschema args>]
   sqlx-js prepare [--check | --watch] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]
   sqlx-js migrate dev [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | verify [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | run [--dry-run] [--json] [--lock-timeout <ms>] | info [--json] | check [--json] | revert [--dry-run] [--json] [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | add <name> | squash <name> [--shadow-admin-url <url> | --shadow-url <url>] [--replace] [--pg-dump <path>] [--lock-timeout <ms>] | archive list | archive restore <name> [--force]
   sqlx-js schema dump | check [--schema <path>] [--manifest <path>] [--no-manifest] [--shadow-url <url>]
@@ -52,23 +55,26 @@ flags:
   --schema <path>          schema snapshot path (default: <root>/.sqlx-js/schema/schema.json)
   --manifest <path>        LLM schema manifest path (default: <root>/.sqlx-js/schema/schema.md)
   --no-manifest            skip writing the LLM schema manifest during schema dump
+  --schema-provider <name> init schema workflow: builtin (default) or pgschema
 `);
     process.exit(2);
 }
+const passthroughIndex = process.argv.indexOf("--");
+const cliArgv = passthroughIndex >= 0 ? process.argv.slice(0, passthroughIndex) : process.argv;
+const passthroughArgs = passthroughIndex >= 0 ? process.argv.slice(passthroughIndex + 1) : [];
 function arg(name, def) {
-    const argv = process.argv;
     const eq = `${name}=`;
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
+    for (let i = 0; i < cliArgv.length; i++) {
+        const a = cliArgv[i];
         if (a === name)
-            return argv[i + 1] ?? def;
+            return cliArgv[i + 1] ?? def;
         if (a.startsWith(eq))
             return a.slice(eq.length);
     }
     return def;
 }
 function flag(name) {
-    for (const a of process.argv) {
+    for (const a of cliArgv) {
         if (a === name)
             return true;
     }
@@ -96,7 +102,41 @@ const schemaPath = schemaArg ? resolve(schemaArg) : join(root, ".sqlx-js/schema/
 const manifestArg = arg("--manifest");
 const manifestPath = manifestArg ? resolve(manifestArg) : join(root, ".sqlx-js/schema/schema.md");
 if (cmd === "init") {
-    runInit({ root });
+    const provider = arg("--schema-provider", "builtin");
+    if (provider !== "builtin" && provider !== "pgschema") {
+        console.error("--schema-provider must be builtin or pgschema");
+        process.exit(2);
+    }
+    runInit({ root, schemaProvider: provider });
+}
+else if (cmd === "db") {
+    const sub = process.argv[3];
+    if (sub === "install") {
+        try {
+            await runPgschemaInstall({ root });
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exit(2);
+        }
+    }
+    else {
+        if (sub !== "check" && sub !== "plan" && sub !== "apply")
+            help();
+        try {
+            runPgschemaCommand({
+                root,
+                databaseUrl,
+                config: await loadConfig(root),
+                subcommand: sub,
+                passthrough: passthroughArgs,
+            });
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exit(2);
+        }
+    }
 }
 else if (cmd === "prepare") {
     if (flag("--check") && shadowUrlArg) {

package/dist/src/codegen.d.ts

@@ -1,2 +1,3 @@
 import { type CacheEntry } from "./cache.js";
-export declare function emitDts(outPath: string, entries: CacheEntry[]): void;
+import type { FunctionEntry } from "./function-cache.js";
+export declare function emitDts(outPath: string, entries: CacheEntry[], functions?: FunctionEntry[]): void;

package/dist/src/codegen.js

@@ -16,18 +16,18 @@ function entrySignature(e) {
     });
     return { params, row: `{ ${cols.join("; ")} }` };
 }
-export function emitDts(outPath, entries) {
+export function emitDts(outPath, entries, functions = []) {
     mkdirSync(dirname(outPath), { recursive: true });
     const lines = [];
     lines.push("// AUTO-GENERATED by sqlx-js. Do not edit.");
     lines.push("// Run `sqlx-js prepare` to regenerate.");
     lines.push("");
-    emitModule(lines, "@onreza/sqlx-js", entries);
+    emitModule(lines, "@onreza/sqlx-js", entries, functions);
     lines.push("");
     lines.push("export {};");
     writeFileSync(outPath, lines.join("\n") + "\n");
 }
-function emitModule(lines, moduleName, entries) {
+function emitModule(lines, moduleName, entries, functions) {
     lines.push(`declare module ${JSON.stringify(moduleName)} {`);
     lines.push("  interface KnownQueries {");
     const inlineSeen = new Set();
@@ -70,5 +70,22 @@ function emitModule(lines, moduleName, entries) {
         lines.push(`    ${JSON.stringify(path)}: { params: ${params}; row: ${row} };`);
     }
     lines.push("  }");
+    lines.push("");
+    lines.push("  interface KnownFunctions {");
+    const functionSeen = new Set();
+    for (const fn of functions.slice().sort((a, b) => a.signature.localeCompare(b.signature))) {
+        if (functionSeen.has(fn.signature))
+            continue;
+        functionSeen.add(fn.signature);
+        const params = inputParams(fn);
+        lines.push(`    ${JSON.stringify(fn.signature)}: { kind: ${JSON.stringify(fn.kind)}; params: ${params}; returns: ${fn.returns}; returnsSet: ${fn.returnsSet} };`);
+    }
+    lines.push("  }");
     lines.push("}");
 }
+function inputParams(fn) {
+    const params = fn.params
+        .filter((p) => p.mode === "in" || p.mode === "inout" || p.mode === "variadic")
+        .map((p) => p.tsType);
+    return params.length === 0 ? "[]" : `[${params.join(", ")}]`;
+}

package/dist/src/commands/init.d.ts

@@ -1,5 +1,6 @@
 export type InitOptions = {
     root: string;
+    schemaProvider?: "builtin" | "pgschema";
     log?: (msg: string) => void;
 };
 export declare function runInit(opts: InitOptions): void;

package/dist/src/commands/init.js

@@ -11,6 +11,20 @@ const config: SqlxJsConfig = {
   customTypes: {},
 };
 
+export default config;
+`;
+const PGSCHEMA_CONFIG_TEMPLATE = `import type { SqlxJsConfig } from "@onreza/sqlx-js";
+
+const config: SqlxJsConfig = {
+  schema: {
+    provider: "pgschema",
+    file: "schema.sql",
+    schemas: ["public"],
+  },
+  jsonbTypes: {},
+  customTypes: {},
+};
+
 export default config;
 `;
 const ENV_TEMPLATE = `# Connection string used by sqlx-js prepare/migrate and the runtime.
@@ -18,6 +32,11 @@ DATABASE_URL=postgres://user:password@localhost:5432/your_db
 # Managed Postgres with TLS:
 # DATABASE_URL=postgres://user:password@db.example.com:5432/your_db?sslmode=verify-full
 `;
+const PGSCHEMA_TEMPLATE = `-- Desired PostgreSQL schema managed by pgschema.
+-- Edit this file, then run:
+--   sqlx-js db plan -- --output-json plan.json
+--   sqlx-js db apply -- --auto-approve
+`;
 export function runInit(opts) {
     const log = opts.log ?? console.log;
     const created = [];
@@ -41,8 +60,12 @@ export function runInit(opts) {
         mkdirSync(full, { recursive: true });
         created.push(`${rel}/`);
     };
-    ensureFile("sqlx-js.config.ts", CONFIG_TEMPLATE);
-    ensureDir("migrations");
+    const schemaProvider = opts.schemaProvider ?? "builtin";
+    ensureFile("sqlx-js.config.ts", schemaProvider === "pgschema" ? PGSCHEMA_CONFIG_TEMPLATE : CONFIG_TEMPLATE);
+    if (schemaProvider === "pgschema")
+        ensureFile("schema.sql", PGSCHEMA_TEMPLATE);
+    else
+        ensureDir("migrations");
     ensureFile(".env.example", ENV_TEMPLATE);
     for (const f of created)
         log(`created ${f}`);
@@ -51,7 +74,15 @@ export function runInit(opts) {
     log("");
     log("Next steps:");
     log("  1. Set DATABASE_URL (see .env.example).");
-    log("  2. Add a migration:  sqlx-js migrate add init");
-    log("  3. Make sure tsconfig.json \"include\" covers sqlx-js-env.d.ts.");
-    log("  4. Develop locally:  sqlx-js migrate dev");
+    if (schemaProvider === "pgschema") {
+        log("  2. Install managed pgschema:  sqlx-js db install");
+        log("  3. Verify it:  sqlx-js db check");
+        log("  4. Edit schema.sql, then review:  sqlx-js db plan");
+        log("  5. After applying schema changes, run:  sqlx-js prepare");
+    }
+    else {
+        log("  2. Add a migration:  sqlx-js migrate add init");
+        log("  3. Make sure tsconfig.json \"include\" covers sqlx-js-env.d.ts.");
+        log("  4. Develop locally:  sqlx-js migrate dev");
+    }
 }

package/dist/src/commands/pgschema.d.ts

@@ -0,0 +1,25 @@
+import type { SqlxJsConfig } from "../config.js";
+export type PgschemaSubcommand = "check" | "plan" | "apply";
+export declare const PGSCHEMA_VERSION = "1.12.0";
+export type PgschemaAsset = {
+    key: string;
+    name: string;
+    sha256: string;
+};
+export type PgschemaCommandOptions = {
+    root: string;
+    databaseUrl: string;
+    config: SqlxJsConfig;
+    subcommand: PgschemaSubcommand;
+    passthrough?: string[];
+};
+export type PgschemaInstallOptions = {
+    root: string;
+    asset?: PgschemaAsset;
+    baseUrl?: string;
+    log?: (msg: string) => void;
+};
+export declare function resolvePgschemaAsset(platform?: NodeJS.Platform, arch?: NodeJS.Architecture): PgschemaAsset;
+export declare function managedPgschemaPath(root: string, asset?: PgschemaAsset): string;
+export declare function runPgschemaInstall(opts: PgschemaInstallOptions): Promise<void>;
+export declare function runPgschemaCommand(opts: PgschemaCommandOptions): void;

package/dist/src/commands/pgschema.js

@@ -0,0 +1,178 @@
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseDatabaseUrl } from "../pg/wire.js";
+export const PGSCHEMA_VERSION = "1.12.0";
+const PGSCHEMA_BASE_URL = `https://github.com/pgplex/pgschema/releases/download/v${PGSCHEMA_VERSION}`;
+const WINDOWS_UNSUPPORTED = "sqlx-js db: pgschema is not supported on Windows. Run sqlx-js under WSL/Linux/macOS or use the built-in sqlx-js migrate workflow.";
+const PGSCHEMA_ASSETS = {
+    "darwin:x64": {
+        key: "darwin-amd64",
+        name: `pgschema-${PGSCHEMA_VERSION}-darwin-amd64`,
+        sha256: "c64b2ac24c4246344908910e892c4123be282bbb449f0b535079ff41d0f47c8f",
+    },
+    "darwin:arm64": {
+        key: "darwin-arm64",
+        name: `pgschema-${PGSCHEMA_VERSION}-darwin-arm64`,
+        sha256: "f01ea488f21700752d5747bc013c406daa583a68b631739f33af430d5d3ec449",
+    },
+    "linux:x64": {
+        key: "linux-amd64",
+        name: `pgschema-${PGSCHEMA_VERSION}-linux-amd64`,
+        sha256: "12610adf748b0dafe4e488ee7e9e68e6ffbef1f4e0f038dda36cf0138eede598",
+    },
+    "linux:arm64": {
+        key: "linux-arm64",
+        name: `pgschema-${PGSCHEMA_VERSION}-linux-arm64`,
+        sha256: "58ec57023954a0239cf9d607c4e5432da6dd0b279399d1c318204120619a221d",
+    },
+};
+export function resolvePgschemaAsset(platform = process.platform, arch = process.arch) {
+    if (platform === "win32")
+        throw new Error(WINDOWS_UNSUPPORTED);
+    const asset = PGSCHEMA_ASSETS[`${platform}:${arch}`];
+    if (!asset)
+        throw new Error(`sqlx-js db install: unsupported platform ${platform}/${arch}`);
+    return asset;
+}
+function pgschemaConfig(config) {
+    if (config.schema?.provider !== "pgschema") {
+        throw new Error("sqlx-js db: set schema.provider = \"pgschema\" in sqlx-js.config.ts");
+    }
+    return config.schema;
+}
+export function managedPgschemaPath(root, asset = resolvePgschemaAsset()) {
+    return join(root, "node_modules/.cache/sqlx-js/pgschema", `v${PGSCHEMA_VERSION}`, asset.key, "pgschema");
+}
+function maybeManagedPgschemaPath(root) {
+    try {
+        const asset = resolvePgschemaAsset();
+        const managed = managedPgschemaPath(root, asset);
+        if (!existsSync(managed))
+            return undefined;
+        if (sha256(readFileSync(managed)) !== asset.sha256) {
+            throw new Error(`sqlx-js db: managed pgschema checksum mismatch at ${managed}. Run sqlx-js db install.`);
+        }
+        chmodSync(managed, 0o755);
+        return managed;
+    }
+    catch (e) {
+        if (e.message.includes("checksum mismatch"))
+            throw e;
+        return undefined;
+    }
+}
+function commandName(root, config) {
+    if (process.platform === "win32")
+        throw new Error(WINDOWS_UNSUPPORTED);
+    if (config.command)
+        return config.command;
+    const managed = maybeManagedPgschemaPath(root);
+    if (managed && existsSync(managed))
+        return managed;
+    return "pgschema";
+}
+function schemaFile(root, config) {
+    return resolve(root, config.file ?? "schema.sql");
+}
+function appliesPlan(subcommand, passthrough) {
+    return subcommand === "apply" && (passthrough ?? []).some((arg) => arg === "--plan" || arg.startsWith("--plan="));
+}
+function installHint(command) {
+    return `sqlx-js db: ${command} was not found. Run sqlx-js db install or set schema.command in sqlx-js.config.ts.`;
+}
+function run(command, args, env) {
+    const child = spawnSync(command, args, { encoding: "utf8", env, stdio: "inherit" });
+    if (child.error) {
+        const code = child.error.code;
+        if (code === "ENOENT")
+            throw new Error(installHint(command));
+        throw child.error;
+    }
+    if (child.signal)
+        throw new Error(`sqlx-js db: ${command} terminated by signal ${child.signal}`);
+    if (child.status && child.status !== 0)
+        process.exit(child.status);
+}
+function pgschemaEnv(db) {
+    return {
+        ...process.env,
+        ...(db.password ? { PGPASSWORD: db.password } : {}),
+        ...(db.sslmode ? { PGSSLMODE: db.sslmode } : {}),
+        ...(db.sslRootCert ? { PGSSLROOTCERT: db.sslRootCert } : {}),
+        ...(db.sslCert ? { PGSSLCERT: db.sslCert } : {}),
+        ...(db.sslKey ? { PGSSLKEY: db.sslKey } : {}),
+    };
+}
+function sha256(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+export async function runPgschemaInstall(opts) {
+    const asset = opts.asset ?? resolvePgschemaAsset();
+    const baseUrl = opts.baseUrl ?? PGSCHEMA_BASE_URL;
+    const log = opts.log ?? console.log;
+    const target = managedPgschemaPath(opts.root, asset);
+    if (existsSync(target) && sha256(readFileSync(target)) === asset.sha256) {
+        chmodSync(target, 0o755);
+        log(`pgschema v${PGSCHEMA_VERSION} already installed at ${target}`);
+        return;
+    }
+    const url = `${baseUrl.replace(/\/$/, "")}/${asset.name}`;
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`sqlx-js db install: failed to download pgschema v${PGSCHEMA_VERSION}: HTTP ${response.status}`);
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const actual = sha256(bytes);
+    if (actual !== asset.sha256) {
+        throw new Error(`sqlx-js db install: checksum mismatch for ${asset.name}`);
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        writeFileSync(tmp, bytes, { mode: 0o755 });
+        chmodSync(tmp, 0o755);
+        renameSync(tmp, target);
+    }
+    catch (e) {
+        rmSync(tmp, { force: true });
+        throw e;
+    }
+    writeFileSync(`${target}.json`, JSON.stringify({ version: PGSCHEMA_VERSION, asset: asset.name, sha256: asset.sha256 }, null, 2) + "\n");
+    log(`installed pgschema v${PGSCHEMA_VERSION} to ${target}`);
+}
+export function runPgschemaCommand(opts) {
+    const config = pgschemaConfig(opts.config);
+    const command = commandName(opts.root, config);
+    if (opts.subcommand === "check") {
+        run(command, ["--help"], process.env);
+        return;
+    }
+    if (!opts.databaseUrl)
+        throw new Error("DATABASE_URL is required for sqlx-js db commands");
+    const file = appliesPlan(opts.subcommand, opts.passthrough) ? undefined : schemaFile(opts.root, config);
+    if (file && !existsSync(file))
+        throw new Error(`sqlx-js db: schema file not found: ${file}`);
+    const db = parseDatabaseUrl(opts.databaseUrl);
+    const schemas = pgschemaSchemas(config);
+    const args = [
+        opts.subcommand,
+        "--host", db.host,
+        "--port", String(db.port),
+        "--db", db.database,
+        "--user", db.user,
+    ];
+    if (file)
+        args.push("--file", file);
+    args.push("--schema", schemas[0]);
+    args.push(...opts.passthrough ?? []);
+    run(command, args, pgschemaEnv(db));
+}
+function pgschemaSchemas(config) {
+    const schemas = config.schemas?.length ? config.schemas : ["public"];
+    if (schemas.length > 1) {
+        throw new Error("sqlx-js db: pgschema 1.12.0 supports exactly one --schema value; split plan/apply per schema or use a single schema in sqlx-js.config.ts");
+    }
+    return schemas;
+}

package/dist/src/commands/prepare.d.ts

@@ -32,6 +32,7 @@ export declare function prepareOnce(opts: PrepareOptions, session: PrepareSessio
     entries: number;
     failures: number;
     pruned: number;
+    functions: number;
 }>;
 export declare function runPrepare(opts: PrepareOptions): Promise<void>;
 export {};

package/dist/src/commands/prepare.js

@@ -6,6 +6,8 @@ import { scanProject } from "../scan/scanner.js";
 import { Cache, fingerprint, effectiveNullable } from "../cache.js";
 import { emitDts } from "../codegen.js";
 import { loadConfig, lookupJsonbType } from "../config.js";
+import { readFunctionCache, writeFunctionCache } from "../function-cache.js";
+import { introspectFunctions } from "../pg/functions.js";
 import { buildParamMap } from "../pg/param-map.js";
 import { mergeExtensionTypes } from "../pg/extensions.js";
 const JSON_OIDS = new Set([114, 3802]);
@@ -344,8 +346,13 @@ export async function prepareOnce(opts, session, log = console.log, err = consol
         if (pruned > 0)
             log(`pruned ${pruned} orphaned cache entry/entries`);
     }
-    emitDts(opts.dtsPath, entries);
-    return { entries: entries.length, failures, pruned };
+    let functions = [];
+    if (failures === 0) {
+        functions = await introspectFunctions(client, schema);
+        writeFunctionCache(opts.cacheDir, functions);
+    }
+    emitDts(opts.dtsPath, entries, functions);
+    return { entries: entries.length, failures, pruned, functions: functions.length };
 }
 export async function runPrepare(opts) {
     if (opts.check) {
@@ -377,8 +384,9 @@ export async function runPrepare(opts) {
             const entry = cache.read(u.fp);
             return entry ? { ...entry, ...siteUsage(u.sites) } : null;
         }).filter((e) => e !== null);
-        emitDts(opts.dtsPath, entries);
-        console.log(`ok — ${entries.length} unique queries, types regenerated`);
+        const functions = readFunctionCache(opts.cacheDir);
+        emitDts(opts.dtsPath, entries, functions);
+        console.log(`ok — ${entries.length} unique queries, ${functions.length} function(s), types regenerated`);
         return;
     }
     const session = await openSession(opts);
@@ -389,7 +397,7 @@ export async function runPrepare(opts) {
             await session.client.end();
             process.exit(1);
         }
-        console.log(`\nprepared ${r.entries} unique query/queries → ${opts.dtsPath}`);
+        console.log(`\nprepared ${r.entries} unique query/queries, ${r.functions} function(s) → ${opts.dtsPath}`);
     }
     finally {
         await session.client.end();

package/dist/src/config.d.ts

@@ -1,6 +1,12 @@
 export type SqlxJsConfig = {
     jsonbTypes?: Record<string, string>;
     customTypes?: Record<string, string>;
+    schema?: {
+        provider?: "builtin" | "pgschema";
+        file?: string;
+        schemas?: string[];
+        command?: string;
+    };
 };
 export declare function loadConfig(root: string): Promise<SqlxJsConfig>;
 export declare function lookupJsonbType(cfg: SqlxJsConfig, schema: string, table: string, column: string): string | undefined;

package/dist/src/function-cache.d.ts

@@ -0,0 +1,18 @@
+export type FunctionKind = "function" | "procedure" | "aggregate" | "window";
+export type FunctionParamMode = "in" | "out" | "inout" | "variadic" | "table";
+export type FunctionParamEntry = {
+    mode: FunctionParamMode;
+    tsType: string;
+    name?: string;
+};
+export type FunctionEntry = {
+    schema: string;
+    name: string;
+    signature: string;
+    kind: FunctionKind;
+    params: FunctionParamEntry[];
+    returns: string;
+    returnsSet: boolean;
+};
+export declare function readFunctionCache(cacheDir: string): FunctionEntry[];
+export declare function writeFunctionCache(cacheDir: string, functions: FunctionEntry[]): void;

package/dist/src/function-cache.js

@@ -0,0 +1,38 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+function cachePath(cacheDir) {
+    return join(cacheDir, "functions", "functions.json");
+}
+function parseFunctionCache(raw) {
+    if (!raw || typeof raw !== "object")
+        return [];
+    const obj = raw;
+    if (obj.version !== 1 || !Array.isArray(obj.functions))
+        return [];
+    return obj.functions;
+}
+export function readFunctionCache(cacheDir) {
+    const path = cachePath(cacheDir);
+    if (!existsSync(path))
+        return [];
+    const text = readFileSync(path, "utf8");
+    return parseFunctionCache(JSON.parse(text));
+}
+export function writeFunctionCache(cacheDir, functions) {
+    const path = cachePath(cacheDir);
+    mkdirSync(dirname(path), { recursive: true });
+    const payload = { version: 1, functions };
+    const tmp = `${path}.tmp-${randomBytes(4).toString("hex")}`;
+    writeFileSync(tmp, JSON.stringify(payload, null, 2));
+    try {
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { }
+        throw err;
+    }
+}

package/dist/src/index.d.ts

@@ -4,6 +4,8 @@ export interface KnownQueries {
 }
 export interface KnownFileQueries {
 }
+export interface KnownFunctions {
+}
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
 export type JsonObject = {

package/dist/src/pg/functions.d.ts

@@ -0,0 +1,4 @@
+import type { FunctionEntry } from "../function-cache.js";
+import { type PgClient } from "./wire.js";
+import { SchemaCache } from "./schema.js";
+export declare function introspectFunctions(client: PgClient, schema: SchemaCache): Promise<FunctionEntry[]>;

package/dist/src/pg/functions.js

@@ -0,0 +1,150 @@
+import { decodeText } from "./wire.js";
+const JSON_OIDS = new Set([114, 3802]);
+const JSON_ARRAY_OIDS = new Set([199, 3807]);
+const JSON_INPUT = 'import("@onreza/sqlx-js").JsonInput';
+export async function introspectFunctions(client, schema) {
+    const rows = await loadFunctionRows(client);
+    const typeOids = new Set();
+    for (const row of rows) {
+        typeOids.add(row.returnOid);
+        for (const oid of row.inputArgOids)
+            typeOids.add(oid);
+        for (const oid of row.allArgOids ?? [])
+            typeOids.add(oid);
+    }
+    await schema.loadCustomTypes([...typeOids]);
+    return rows.map((row) => toEntry(row, schema)).sort((a, b) => a.signature.localeCompare(b.signature));
+}
+async function loadFunctionRows(client) {
+    const result = await client.simpleQueryAll(`
+    SELECT
+      n.nspname,
+      p.proname,
+      p.prokind::text,
+      pg_get_function_identity_arguments(p.oid),
+      to_json(
+        CASE
+          WHEN p.proargtypes::text = '' THEN ARRAY[]::oid[]
+          ELSE string_to_array(p.proargtypes::text, ' ')::oid[]
+        END
+      )::text,
+      to_json(p.proallargtypes)::text,
+      to_json(p.proargmodes)::text,
+      to_json(p.proargnames)::text,
+      p.prorettype::int8,
+      p.proretset
+    FROM pg_proc p
+    JOIN pg_namespace n ON n.oid = p.pronamespace
+    WHERE ${userSchemaFilter("n")}
+    ORDER BY n.nspname, p.proname, pg_get_function_identity_arguments(p.oid)
+  `);
+    return result.rows.map((row) => ({
+        schema: decodeText(row[0]),
+        name: decodeText(row[1]),
+        kind: functionKind(decodeText(row[2])),
+        identityArguments: decodeText(row[3]) ?? "",
+        inputArgOids: parseNumberJsonArray(decodeText(row[4])),
+        allArgOids: parseNullableNumberJsonArray(decodeText(row[5] ?? null)),
+        argModes: parseNullableStringJsonArray(decodeText(row[6] ?? null)),
+        argNames: parseNullableStringJsonArray(decodeText(row[7] ?? null)),
+        returnOid: Number(decodeText(row[8])),
+        returnsSet: decodeText(row[9]) === "t",
+    }));
+}
+function toEntry(row, schema) {
+    const allArgOids = row.allArgOids ?? row.inputArgOids;
+    const modes = row.argModes ?? allArgOids.map(() => "i");
+    const params = allArgOids.map((oid, i) => {
+        const mode = paramMode(modes[i]);
+        const resultTsType = outputTsType(oid, schema);
+        return {
+            mode,
+            tsType: mode === "out" || mode === "table" ? resultTsType : inputTsType(oid, schema),
+            ...(mode === "inout" ? { resultTsType } : {}),
+            ...(row.argNames?.[i] ? { name: row.argNames[i] } : {}),
+        };
+    });
+    const output = params.filter((p) => p.mode === "out" || p.mode === "inout" || p.mode === "table");
+    return {
+        schema: row.schema,
+        name: row.name,
+        signature: `${row.schema}.${row.name}(${row.identityArguments})`,
+        kind: row.kind,
+        params: params.map(persistedParam),
+        returns: returnTsType(row, output, schema),
+        returnsSet: row.returnsSet,
+    };
+}
+function persistedParam(param) {
+    return {
+        mode: param.mode,
+        tsType: param.tsType,
+        ...(param.name ? { name: param.name } : {}),
+    };
+}
+function returnTsType(row, output, schema) {
+    if (output.length > 0)
+        return outputObject(output);
+    if (row.kind === "procedure")
+        return "void";
+    return nullableReturn(schema.tsType(row.returnOid));
+}
+function outputObject(output) {
+    const fields = output.map((p, i) => {
+        const name = p.name && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(p.name) ? p.name : JSON.stringify(p.name ?? `column${i + 1}`);
+        return `${name}: ${nullableReturn(p.resultTsType ?? p.tsType)}`;
+    });
+    return `{ ${fields.join("; ")} }`;
+}
+function inputTsType(oid, schema) {
+    if (JSON_OIDS.has(oid))
+        return JSON_INPUT;
+    if (JSON_ARRAY_OIDS.has(oid))
+        return `(${JSON_INPUT})[]`;
+    return schema.tsType(oid);
+}
+function outputTsType(oid, schema) {
+    return schema.tsType(oid);
+}
+function nullableReturn(tsType) {
+    if (tsType === "void")
+        return tsType;
+    return `${tsType} | null`;
+}
+function parseNumberJsonArray(raw) {
+    if (!raw)
+        return [];
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.map(Number).filter((n) => Number.isFinite(n)) : [];
+}
+function parseNullableNumberJsonArray(raw) {
+    if (raw === null)
+        return null;
+    return parseNumberJsonArray(raw);
+}
+function parseNullableStringJsonArray(raw) {
+    if (raw === null)
+        return null;
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.map((v) => (typeof v === "string" ? v : "")) : [];
+}
+function paramMode(raw) {
+    switch (raw) {
+        case "o": return "out";
+        case "b": return "inout";
+        case "v": return "variadic";
+        case "t": return "table";
+        default: return "in";
+    }
+}
+function functionKind(raw) {
+    switch (raw) {
+        case "p": return "procedure";
+        case "a": return "aggregate";
+        case "w": return "window";
+        default: return "function";
+    }
+}
+function userSchemaFilter(alias) {
+    return `${alias}.nspname <> 'information_schema' AND ${alias}.nspname NOT LIKE 'pg\\_%' ESCAPE '\\'`;
+}

package/dist/src/pg/oids.js

@@ -42,6 +42,8 @@ const SCALAR = {
     2950: { ts: "string" },
     2205: { ts: "string" },
     2206: { ts: "string" },
+    2249: { ts: "Record<string, unknown>" },
+    2278: { ts: "void" },
     3220: { ts: "string" },
     3614: { ts: "string" },
     3615: { ts: "string" },

package/dist/src/pg/schema.d.ts

@@ -74,4 +74,5 @@ export declare class SchemaCache {
     loadCustomTypes(typeOids: number[]): Promise<void>;
     private resolveBaseTs;
     customType(oid: number): CustomTypeInfo | undefined;
+    tsType(oid: number): string;
 }

package/dist/src/pg/schema.js

@@ -262,6 +262,9 @@ export class SchemaCache {
     customType(oid) {
         return this.customTypes.get(oid);
     }
+    tsType(oid) {
+        return this.resolveBaseTs(oid) ?? "unknown";
+    }
 }
 function key(oid, attno) {
     return `${oid}/${attno}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onreza/sqlx-js",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Compile-time-checked raw SQL for TypeScript + PostgreSQL. Inspired by sqlx.",
   "license": "MIT",
   "type": "module",