@onreza/sqlx-js 0.2.0 → 0.4.0

package/README.md

@@ -2,9 +2,9 @@
 
 Compile-time-checked raw SQL for TypeScript + PostgreSQL. Inspired by Rust's [sqlx](https://github.com/launchbadge/sqlx).
 
-You write plain SQL strings. A `prepare` step validates them against your database via the PostgreSQL wire protocol and generates a TypeScript declaration file. Wrong column names, mismatched parameter types, stale queries after a migration — all become compile errors.
+You write plain SQL strings. A `prepare` step validates them against your database via the PostgreSQL wire protocol and generates a TypeScript declaration file. Wrong column names and stale queries fail during `prepare`; mismatched parameter types and row usage become TypeScript errors.
 
-The runtime uses [Postgres.js](https://github.com/porsager/postgres), so both the runtime and the CLI work on **Node ≥ 18, Bun, and Deno** — the CLI ships a `#!/usr/bin/env node` shebang and uses no runtime-specific APIs.
+The runtime uses [Postgres.js](https://github.com/porsager/postgres) through a single adapter instead of a Bun-specific client. The published CLI is a **Node ≥ 18** binary (`#!/usr/bin/env node`) and can also be run through Bun's npm tooling.
 
 ```ts
 import { sql } from "@onreza/sqlx-js";
@@ -24,11 +24,11 @@ const rows = await sql(
 - **Precise nullability inference** through `libpg-query`: `JOIN` direction (LEFT/RIGHT/FULL), inner `JOIN ... ON` predicates, DML `RETURNING`, `COALESCE`, `CASE`, `COUNT`, expression propagation. Parameters become `T | null` when wrapped in `COALESCE`/`NULLIF`/`IS [NOT] NULL`/`IS [NOT] DISTINCT FROM`, or when bound to a nullable column in `INSERT`/`UPDATE`.
 - **WHERE narrowing**: `IS NOT NULL`, equality chains, `IN`, `LIKE`, `BETWEEN` make columns non-null. Tracks `AND`/`OR` semantics.
 - **PostgreSQL enums** generated as TypeScript literal unions (read + write side).
-- **Schema-aware `jsonb`** via a `SqlxJsJson` global namespace and a config-driven column → type mapping. Works for both result columns and `INSERT`/`UPDATE`/`WHERE` parameters.
+- **Schema-aware `jsonb`** via a `SqlxJsJson` global namespace and a config-driven column → type mapping. Works for both result columns and `INSERT`/`UPDATE`/`WHERE` parameters. Unmapped `json`/`jsonb` falls back to `JsonValue` for rows and `JsonInput` for parameters instead of `unknown`.
 - **Extension types out of the box**: `pgvector` (`vector`, `halfvec`, `sparsevec`), `hstore`, `citext`, `ltree`/`lquery`/`ltxtquery`. Add your own through `customTypes` config.
 - **Domains** resolve to their base TypeScript type (`CREATE DOMAIN email AS text` → `string`), including domains over extension types or other domains.
 - **Wide built-in type coverage**: numeric, text, date/time, UUID, json/jsonb, network (inet/cidr/macaddr/macaddr8), bit strings, ranges/multiranges, geometric, money, tsvector/tsquery, xml — and the matching array variants.
-- **External SQL files** via `sql.file("queries/foo.sql", ...)` — typed exactly like inline queries. Watch mode re-prepares on `.sql` edits too.
+- **External SQL files** via `sql.file("queries/foo.sql", ...)` — prepared and typed through `KnownFileQueries`. Watch mode re-prepares on `.sql` edits too.
 - **One-row helpers**: `sql.one(...)`, `sql.optional(...)`, `sql.file.one(...)`, `sql.file.optional(...)`, and the same chain on the `tx` callback — friendly with `noUncheckedIndexedAccess: true`. The scanner walks all of them.
 - **Array params** for `text[]`, `int[]`, etc. are auto-serialised to PostgreSQL array literals (`{a,b,c}`) at runtime — no more `string_to_array` workaround.
 - **Typed transactions** via `sql.transaction(async tx => …)` — the `tx` callback parameter is recognized by the scanner, so queries inside the block keep full type checking.
@@ -36,12 +36,14 @@ 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.
-- **Cross-runtime**: one Postgres.js-backed runtime that works on Node, Bun, and Deno — no runtime-specific adapter to choose.
-- **Watch mode**: ~15ms incremental re-prepare on file change.
+- **Single runtime adapter**: Postgres.js backs the runtime on Node/Bun-compatible environments — no Bun.SQL-specific adapter to choose.
+- **Watch mode**: debounced re-prepare with a warm `PgClient` + `SchemaCache` on `.ts` / `.tsx` / `.mts` / `.cts` / `.sql` changes.
 - **Cache pruning** removes orphaned entries automatically (toggleable with `--no-prune`).
 
 ## Install
@@ -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
@@ -73,7 +85,7 @@ DATABASE_URL=postgres://user:password@localhost:5432/your_db
 # DATABASE_URL=postgres://user:password@db.example.com:5432/your_db?sslmode=require
 ```
 
-Supported `sslmode` values: `disable`, `prefer` (default — try TLS, fall back to plaintext), `require` (TLS or fail), `verify-ca`, `verify-full`. For a private/self-signed CA, point `sslrootcert` (and optionally `sslcert` / `sslkey` for client certs) at PEM files: `?sslmode=verify-full&sslrootcert=/etc/ssl/ca.pem`. `application_name`, `connect_timeout`, and `statement_timeout` (milliseconds) are also honored when provided as URL parameters.
+Supported `sslmode` values: `disable`, `prefer` (default — try TLS, fall back to plaintext), `require` (TLS or fail), `verify-ca`, `verify-full`. For a private/self-signed CA, point `sslrootcert` (and optionally `sslcert` / `sslkey` for client certs) at PEM files: `?sslmode=verify-full&sslrootcert=/etc/ssl/ca.pem`. `application_name`, `connect_timeout` (seconds), and `statement_timeout` (milliseconds) are also honored when provided as URL parameters.
 
 ### 2. Create a migration
 
@@ -81,7 +93,7 @@ Supported `sslmode` values: `disable`, `prefer` (default — try TLS, fall back
 npx @onreza/sqlx-js migrate add init
 ```
 
-Edit the created file (`migrations/0001_init.up.sql`):
+The command creates matching `.up.sql` and `.down.sql` stubs. Edit the `.up.sql` file (`migrations/0001_init.up.sql`):
 
 ```sql
 CREATE TABLE users (
@@ -99,7 +111,7 @@ During local development, validate the migration and regenerate query artifacts
 npx @onreza/sqlx-js migrate dev
 ```
 
-`migrate dev` does not touch your application database. It creates a temporary shadow database using `DATABASE_URL` credentials, applies migrations from scratch, validates that the latest non-squash `.down.sql` restores the schema, prepares SQL queries against the resulting schema, writes `.sqlx-js/` and `sqlx-js-env.d.ts`, then drops the shadow database.
+`migrate dev` does not touch your application database. It creates a temporary shadow database using `DATABASE_URL` credentials, applies migrations from scratch, validates that the latest migration's `.down.sql` restores the previous schema (squash baselines may omit `.down.sql`), prepares SQL queries against the resulting schema, writes `.sqlx-js/` and `sqlx-js-env.d.ts`, then drops the shadow database.
 
 When you want to update your local application database, run:
 
@@ -152,7 +164,7 @@ Unknown queries, wrong parameter types, and dynamic strings are compile errors.
 
 ### `sql.file(path, ...params)`
 
-Load SQL from an external file. The path is resolved against the source file at scan time (so `prepare` can read it), and against `process.cwd()` at runtime (so the running process can read it). Both must point at the same content.
+Load SQL from an external file. At prepare time the scanner reads the path relative to the source file. The generated `KnownFileQueries` key is the resolved SQL file path relative to `--root`; at runtime `sql.file(...)` reads the string argument relative to `process.cwd()`.
 
 ```ts
 // queries/top_admins.sql
@@ -165,7 +177,7 @@ const admins = await sql.file("queries/top_admins.sql", "admin", 5);
 // admins: { id: bigint; name: string }[]
 ```
 
-File-backed queries are emitted into a separate `KnownFileQueries` interface; the path becomes the type key.
+File-backed queries are emitted into a separate `KnownFileQueries` interface. Because the type key is the root-relative resolved SQL file path, keep file-backed call sites under a convention where that key matches the runtime string literal; the example keeps those call sites at the project root. Nested source-relative file paths are a current limitation.
 
 ### `sql.one(query, ...params)` and `sql.optional(query, ...params)`
 
@@ -240,7 +252,7 @@ const orderBy = sql.id("users", "created_at");
 await unsafe(`SELECT id, email FROM ${sql.id("users")} ORDER BY ${orderBy} DESC`);
 ```
 
-The default snapshot path is `.sqlx-js/schema/schema.json`. Override it at runtime with `SQLX_JS_SCHEMA_PATH`. Pass schema-qualified identifiers as separate segments: `sql.id("public", "users")`, not `sql.id("public.users")`.
+The default snapshot path is `.sqlx-js/schema/schema.json`. Override it at runtime with `SQLX_JS_SCHEMA_PATH`. `sql.id(...)` accepts one to three identifier segments. Pass schema-qualified identifiers as separate segments: `sql.id("public", "users")`, not `sql.id("public.users")`.
 
 ### `migrate(options)`
 
@@ -286,13 +298,13 @@ setClient(createClient(process.env.DATABASE_URL, {
   statementTimeoutMs: 5000,
   // Fires after every query/transaction statement, success or failure.
   onQuery: ({ query, params, durationMs, rowCount, error }) => {
-    if (error) logger.error({ query, error });        // error is a PgError
+    if (error) logger.error({ query, error });        // database errors are PgError
     else if (durationMs > 200) logger.warn({ slow: query, durationMs, rowCount });
   },
 }));
 ```
 
-The `onQuery` hook works on any runtime (Node/Bun/Deno) and is the integration point for metrics, tracing, and slow-query logging — sqlx-js does not log queries itself. The event carries the raw `params`, which may contain personal or sensitive data — don't log them blindly; redact or omit `params` in shared sinks.
+The `onQuery` hook is the integration point for metrics, tracing, and slow-query logging — sqlx-js does not log queries itself. The event carries the raw `params`, which may contain personal or sensitive data — don't log them blindly; redact or omit `params` in shared sinks. Database errors are normalized to `PgError`; transport and non-database errors pass through unchanged.
 
 ### `clearSqlFileCache()`
 
@@ -313,7 +325,7 @@ try {
 }
 ```
 
-`sql.one` throws `NoRowsError` on 0 rows and `TooManyRowsError` (with `.actual`) on >1. Any database error raised by the runtime — whatever the adapter — is normalized into a `PgError`, so `e instanceof PgError` works the same in `prepare`, `migrate`, and ordinary `sql(...)` calls. `PgError` exposes `.code`, `.position`, `.hint`, `.detail`, `.severity`, `.schema`, `.table`, `.column`, `.constraint`, and the original driver error on `.cause`. Non-database failures (e.g. a dropped connection) are rethrown unchanged.
+`sql.one` throws `NoRowsError` on 0 rows and `TooManyRowsError` (with `.actual`) on >1. Any database error raised by the default runtime is normalized into a `PgError`, so `e instanceof PgError` works the same in `prepare`, `migrate`, and ordinary `sql(...)` calls. `PgError` exposes `.code`, `.position`, `.hint`, `.detail`, `.severity`, `.schema`, `.table`, `.column`, `.constraint`, and the original driver error on `.cause`. Non-database failures (e.g. a dropped connection) are rethrown unchanged.
 
 ### Transactions with options
 
@@ -334,18 +346,19 @@ 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>] | verify [--shadow-admin-url <url> | --shadow-url <url>] | run [--dry-run] [--json] [--lock-timeout <ms>] | info [--json] | check [--json] | revert [--dry-run] [--json] [--shadow-admin-url <url> | --shadow-url <url>] | add <name> | squash <name> [--shadow-admin-url <url> | --shadow-url <url>] [--replace] | archive list | archive restore <name> [--force] [--migrations <dir>]
+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>]
 sqlx-js --version | --help
 ```
 
-`prepare` describes queries across a small connection pool (default 8, override with `SQLX_JS_PREPARE_CONCURRENCY`) for faster cold runs on large projects.
+Regular `prepare` describes queries across a small connection pool (default 8, override with `SQLX_JS_PREPARE_CONCURRENCY`) for faster cold runs on large projects. Watch mode keeps one session warm and reuses it between debounced changes.
 
 | Flag                  | Meaning                                                                              |
 |-----------------------|--------------------------------------------------------------------------------------|
-| `--check`             | Offline: verify cache matches sources, no database required.                         |
+| `--check`             | Offline: verify every scanned query is present in cache, no database required.       |
 | `--watch`             | Persistent connection, re-prepare on file change.                                    |
 | `--root <dir>`        | Source/cache/migrations root (default: cwd).                                         |
 | `--dts <path>`        | Declarations output (default: `<root>/sqlx-js-env.d.ts`).                           |
@@ -354,7 +367,7 @@ sqlx-js --version | --help
 | `--dry-run`           | For `migrate run` / `migrate revert`: validate without applying to the target DB.   |
 | `--json`              | Machine-readable output for `migrate info/check` and migration dry-runs.            |
 | `--force`             | For `migrate archive restore`: allow overwriting existing migration files.           |
-| `--lock-timeout <ms>` | Advisory-lock acquisition timeout for `migrate run` / `migrate revert`.              |
+| `--lock-timeout <ms>` | Advisory-lock acquisition timeout for `migrate run` / `revert` / `dev` / `verify` / `squash`. |
 | `--shadow-url <url>`  | Use an existing disposable shadow DB instead of auto-creating one.                   |
 | `--shadow-admin-url <url>` | Admin/maintenance DB URL used to auto-create shadow DBs.                       |
 | `--replace`           | For `migrate squash`: archive replaced migration files after writing the baseline.   |
@@ -362,13 +375,28 @@ sqlx-js --version | --help
 | `--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`.                                |
 
-All flags accept both `--flag value` and `--flag=value` forms.
+Flags that take a value accept both `--flag value` and `--flag=value` forms.
 
-`DATABASE_URL` must be set for any command that touches the application database or auto-creates a shadow database. `SHADOW_ADMIN_DATABASE_URL` can point at a maintenance/admin database when the application user cannot `CREATE DATABASE`; `SHADOW_DATABASE_URL` can point at a pre-created disposable shadow database. Supported URL search params: `sslmode`, `application_name`, `connect_timeout`.
+`DATABASE_URL` must be set for any command that touches the application database or auto-creates a shadow database. `SHADOW_ADMIN_DATABASE_URL` can point at a maintenance/admin database when the application user cannot `CREATE DATABASE`; `SHADOW_DATABASE_URL` can point at a pre-created disposable shadow database. The internal wire client understands `sslmode`, `sslrootcert`, `sslcert`, `sslkey`, `application_name`, `connect_timeout` (seconds), and `statement_timeout` (milliseconds).
 
 ### 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
@@ -377,7 +405,9 @@ sqlx-js migrate add add_users
 sqlx-js migrate dev
 ```
 
-`migrate dev` creates a disposable shadow database, applies all migrations from scratch, validates that the latest non-squash `.down.sql` restores the schema, 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.
+`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:
 
@@ -428,7 +458,7 @@ On an empty database, the baseline runs as ordinary schema SQL. On an already-mi
 - `.sqlx-js/schema/schema.json` — machine-readable contract for runtime identifier whitelisting and CI drift checks.
 - `.sqlx-js/schema/schema.md` — compact LLM-facing manifest with tables, columns, constraints, indexes, types, and functions.
 
-`schema check` re-introspects the database and fails if the committed snapshot is stale. With `--shadow-url`, both `prepare` and `schema dump/check` first apply pending migrations to the shadow database, then use that database as the source of truth. In watch mode, pending shadow migrations are checked before every re-prepare; when a migration is applied, the prepare session is reopened so schema metadata is not reused across DDL changes.
+`schema check` re-introspects the database and fails if the committed snapshot is stale. With `--shadow-url`, both `prepare` and `schema dump/check` first apply pending migrations to the shadow database, then use that database as the source of truth. Unlike `migrate dev` / `verify` / `squash`, these commands do not clear an explicit shadow database first. In watch mode, pending shadow migrations are checked before every re-prepare; when a migration is applied, the prepare session is reopened so schema metadata is not reused across DDL changes.
 
 ### Error output
 
@@ -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
@@ -477,7 +514,7 @@ declare global {
 export {};
 ```
 
-After re-running `prepare`, every `jsonb` column or parameter declared in `jsonbTypes` is checked against the corresponding TypeScript type.
+After re-running `prepare`, every `jsonb` column or parameter declared in `jsonbTypes` is checked against the corresponding TypeScript type. Columns without a custom mapping use `JsonValue` for result rows and `JsonInput` for parameters, both exported by `@onreza/sqlx-js`, so non-JSON inputs such as `Date`, functions, and `bigint` are rejected by TypeScript while plain JSON objects, arrays, strings, numbers, booleans, and nested JSON `null` values are accepted. Top-level SQL `null` is added separately as `| null` only when the mapped database parameter is nullable.
 
 ### Extension types and `customTypes`
 
@@ -494,7 +531,7 @@ sqlx-js ships with a built-in registry that resolves popular PostgreSQL extensio
 | `lquery`          | `string`                           | ltree             |
 | `ltxtquery`       | `string`                           | ltree             |
 
-Add or override mappings via `customTypes` in `sqlx-js.config.ts`. Keys are `pg_type.typname` values (the bare type name; namespacing isn't required):
+Add or override mappings via `customTypes` in `sqlx-js.config.ts`. Keys are `pg_type.typname` values (the bare type name). The registry is global by type name, so two schemas with the same `typname` cannot be mapped differently:
 
 ```ts
 import type { SqlxJsConfig } from "@onreza/sqlx-js";
@@ -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
 
@@ -561,14 +603,16 @@ Releases are automated via `release-please`: pushes to `main` accumulate into a
 `sqlx-js` is a young library. Known gaps:
 
 - PostgreSQL only (no MySQL or SQLite).
+- The scanner only follows direct named imports and namespace imports from `@onreza/sqlx-js`; it does not follow re-exports, dynamic aliases, or tagged-template calls.
 - `INSERT INTO t VALUES (...)` without an explicit column list isn't parameter-mapped.
 - `SELECT *` falls back to conservative nullability.
+- Statements without a row description, such as `UPDATE ...` without `RETURNING`, are emitted with `row: never`, so the public return type is `Promise<never[]>`.
 - Nested CTE references (CTE-`b` referencing CTE-`a` in the same `WITH`) and `WITH RECURSIVE` are not analysed transitively — at worst this produces extra `T | null`. Use `AS "id!"` overrides if needed.
 - Column names whose **real** name (not an alias) ends with `!` or `?` are not supported — the runtime strips those suffixes assuming an override. Use `AS "alias"` if you have such a column.
 - Migrations run inside `BEGIN/COMMIT`. DDL that disallows transactions (`CREATE INDEX CONCURRENTLY`, `VACUUM`, `REINDEX CONCURRENTLY`, …) will fail; split such operations into separate migrations executed outside the runner.
 - The **internal** wire client (used by `migrate run`, `prepare`, and the runtime `migrate()` helper) reads `sslmode`, `sslrootcert`/`sslcert`/`sslkey`, `application_name`, `connect_timeout`, and `statement_timeout` from `DATABASE_URL`. The default runtime `sql()` path delegates connection handling to Postgres.js; configure TLS, pooling, and timeouts through the `DATABASE_URL` and `createClient(...)` options it understands (`statementTimeoutMs` is a convenience that maps to a per-connection `statement_timeout`).
 - `connect_timeout` bounds the entire internal-client connect, including the TLS handshake and SCRAM authentication.
-- `sql.file(path)` path is matched literally between scan time and runtime — they must agree on the working directory. Document a convention for your team (e.g. always run from the repo root).
+- `sql.file(path)` has a path-key mismatch to be aware of: prepare resolves the file relative to the source file, codegen keys it by root-relative resolved path, and runtime reads the literal path relative to `process.cwd()`. Keep a project convention and verify with `tsc` after `prepare`.
 
 See [ROADMAP.md](./ROADMAP.md) for what's planned.
 

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,28 +25,29 @@ 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>] | verify [--shadow-admin-url <url> | --shadow-url <url>] | 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] | archive list | archive restore <name> [--force]
+  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>]
   sqlx-js --version
 
 env:
-  DATABASE_URL=postgres://...  (supports ?sslmode=require|verify-ca|verify-full)
+  DATABASE_URL=postgres://...  (supports sslmode, cert paths, application_name, connect_timeout, statement_timeout)
   SHADOW_DATABASE_URL=postgres://...  (optional pre-created disposable shadow DB)
   SHADOW_ADMIN_DATABASE_URL=postgres://...  (optional admin URL for auto-created shadow DBs)
 
 flags:
   --root <dir>             scan root (default: cwd)
   --dts <path>             declarations output (default: <root>/sqlx-js-env.d.ts)
-  --check                  offline mode: validate cache vs sources, no DB
+  --check                  offline mode: verify scanned queries exist in cache, no DB
   --watch                  re-prepare on file change (persistent PG connection)
   --no-prune               keep orphaned cache entries (default: remove)
   --migrations <dir>       migrations directory (default: <root>/migrations)
   --dry-run                validate and print migrate run/revert plan without applying migrations
   --json                   machine-readable output for migrate info/check and migrate run/revert --dry-run
   --force                  allow archive restore to overwrite existing migration files
-  --lock-timeout <ms>      advisory-lock acquisition timeout for migrate run/revert
+  --lock-timeout <ms>      advisory-lock acquisition timeout for migrate run/revert/dev/verify/squash
   --shadow-url <url>       use an existing disposable shadow DB instead of auto-creating one
   --shadow-admin-url <url> admin/maintenance DB URL used to auto-create shadow DBs
   --replace                archive replaced migrations after migrate squash writes the baseline
@@ -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/cache.d.ts

@@ -7,6 +7,7 @@ export type CacheColumn = {
 };
 export type CacheEntry = {
     query: string;
+    inlineQueries?: string[];
     paramOids: number[];
     paramTsTypes: string[];
     paramNullable?: boolean[];

package/dist/src/cache.js

@@ -2,9 +2,136 @@ import { createHash, randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, renameSync } from "node:fs";
 import { join } from "node:path";
 export function fingerprint(query) {
-    const norm = query.replace(/\s+/g, " ").trim();
+    const norm = normalizeForFingerprint(query);
     return createHash("sha256").update(norm).digest("hex").slice(0, 16);
 }
+function normalizeForFingerprint(query) {
+    let out = "";
+    let pendingSpace = false;
+    let i = 0;
+    const emit = (text) => {
+        if (pendingSpace && out.length > 0)
+            out += " ";
+        out += text;
+        pendingSpace = false;
+    };
+    const markSpace = () => {
+        if (out.length > 0)
+            pendingSpace = true;
+    };
+    while (i < query.length) {
+        const ch = query[i];
+        if (/\s/.test(ch)) {
+            markSpace();
+            i++;
+            continue;
+        }
+        if (ch === "-" && query[i + 1] === "-") {
+            i = readLineComment(query, i);
+            markSpace();
+            continue;
+        }
+        if (ch === "/" && query[i + 1] === "*") {
+            i = readBlockComment(query, i);
+            markSpace();
+            continue;
+        }
+        if (ch === "'") {
+            const next = readSingleQuoted(query, i, isEscapeStringPrefix(query, i));
+            emit(query.slice(i, next));
+            i = next;
+            continue;
+        }
+        if (ch === "\"") {
+            const next = readQuotedIdentifier(query, i);
+            emit(query.slice(i, next));
+            i = next;
+            continue;
+        }
+        if (ch === "$") {
+            const next = readDollarQuoted(query, i);
+            if (next !== null) {
+                emit(query.slice(i, next));
+                i = next;
+                continue;
+            }
+        }
+        emit(ch);
+        i++;
+    }
+    return out;
+}
+function readSingleQuoted(query, start, escapeBackslash) {
+    let i = start + 1;
+    while (i < query.length) {
+        const ch = query[i];
+        if (escapeBackslash && ch === "\\") {
+            i += 2;
+            continue;
+        }
+        if (ch === "'") {
+            if (query[i + 1] === "'") {
+                i += 2;
+                continue;
+            }
+            return i + 1;
+        }
+        i++;
+    }
+    return query.length;
+}
+function readQuotedIdentifier(query, start) {
+    let i = start + 1;
+    while (i < query.length) {
+        if (query[i] === "\"") {
+            if (query[i + 1] === "\"") {
+                i += 2;
+                continue;
+            }
+            return i + 1;
+        }
+        i++;
+    }
+    return query.length;
+}
+function readDollarQuoted(query, start) {
+    let tagEnd = start + 1;
+    while (tagEnd < query.length && /[A-Za-z0-9_]/.test(query[tagEnd]))
+        tagEnd++;
+    if (query[tagEnd] !== "$")
+        return null;
+    const tag = query.slice(start, tagEnd + 1);
+    const end = query.indexOf(tag, tagEnd + 1);
+    return end === -1 ? query.length : end + tag.length;
+}
+function readLineComment(query, start) {
+    const end = query.indexOf("\n", start + 2);
+    return end === -1 ? query.length : end + 1;
+}
+function readBlockComment(query, start) {
+    let depth = 1;
+    let i = start + 2;
+    while (i < query.length && depth > 0) {
+        if (query[i] === "/" && query[i + 1] === "*") {
+            depth++;
+            i += 2;
+            continue;
+        }
+        if (query[i] === "*" && query[i + 1] === "/") {
+            depth--;
+            i += 2;
+            continue;
+        }
+        i++;
+    }
+    return i;
+}
+function isEscapeStringPrefix(query, quoteIndex) {
+    if (quoteIndex === 0 || query[quoteIndex - 1]?.toLowerCase() !== "e")
+        return false;
+    const beforePrefix = query[quoteIndex - 2];
+    return beforePrefix === undefined || !/[A-Za-z0-9_$]/.test(beforePrefix);
+}
 export function effectiveNullable(c) {
     if (c.override === "non-null")
         return false;

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;