@onreza/sqlx-js 0.4.0 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@ Compile-time-checked raw SQL for TypeScript + PostgreSQL. Inspired by Rust's [sq
 
 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) 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.
+The runtime uses [Postgres.js](https://github.com/porsager/postgres) through a single adapter instead of a Bun-specific client. The published CLI requires **Node ≥ 24** (`#!/usr/bin/env node`) and can also run through **Bun ≥ 1.3**.
 
 ```ts
 import { sql } from "@onreza/sqlx-js";
@@ -30,21 +30,22 @@ const rows = await sql(
 - **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", ...)` — 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.
+- **Unambiguous JSON and PostgreSQL array params** through `sql.json(...)` and `sql.array(...)`. Primitive JSON arrays cannot be silently encoded as PostgreSQL array literals.
 - **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.
 - **Sourcemap-accurate error reporting**: every prepare failure points to `file:line:column` of the originating `sql(...)` call site, with PG error code, position, and hint.
 - **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.
+- **Versioned offline cache** committed to your repo. `prepare --check` validates fingerprints, generator revision, and type-affecting config without a database; `prepare --verify` compares fresh live/shadow artifacts without writing.
 - **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.
-- **Watch mode**: debounced re-prepare with a warm `PgClient` + `SchemaCache` on `.ts` / `.tsx` / `.mts` / `.cts` / `.sql` changes.
+- **Watch mode**: debounced re-prepare with a warm `PgClient` + `SchemaCache` on source/SQL changes and scanner/config graph updates.
 - **Cache pruning** removes orphaned entries automatically (toggleable with `--no-prune`).
+- **Environment doctor** checks runtime versions, config loading, `.env`, database connectivity/permissions, cache metadata, tsconfig inclusion, and pgschema availability.
 
 ## Install
 
@@ -54,6 +55,8 @@ npm install @onreza/sqlx-js
 bun add @onreza/sqlx-js
 ```
 
+Node.js 24 or newer is required. Bun users need Bun 1.3 or newer.
+
 The package installs a `sqlx-js` binary. The CLI examples below use `npx @onreza/sqlx-js`; `bunx @onreza/sqlx-js ...` works the same if your project uses Bun.
 
 ## Setup
@@ -87,6 +90,8 @@ DATABASE_URL=postgres://user:password@localhost:5432/your_db
 
 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.
 
+CLI commands load `<root>/.env` before reading connection settings. Variables already present in the process environment take precedence. Application runtime configuration remains owned by your application/framework.
+
 ### 2. Create a migration
 
 ```bash
@@ -164,7 +169,7 @@ Unknown queries, wrong parameter types, and dynamic strings are compile errors.
 
 ### `sql.file(path, ...params)`
 
-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()`.
+Load SQL from an external file. The path is root-relative everywhere: prepare resolves it against `--root`, codegen keeps the exact string literal as the `KnownFileQueries` key, and runtime resolves it against `fileRoot` (default: `process.cwd()`). Absolute paths and paths escaping the root are rejected.
 
 ```ts
 // queries/top_admins.sql
@@ -177,7 +182,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. 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.
+File-backed queries are emitted into a separate `KnownFileQueries` interface. A call from any nested source directory still uses the same project-root-relative literal.
 
 ### `sql.one(query, ...params)` and `sql.optional(query, ...params)`
 
@@ -193,18 +198,46 @@ const maybe = await sql.optional(`SELECT id FROM users WHERE email = $1`, "x@y")
 
 Both forms also exist on `sql.file` (`sql.file.one("queries/by_id.sql", ...)`) and inside transactions (`tx.one(...)`, `tx.optional(...)`, `tx.file.one(...)`, `tx.file.optional(...)`). The scanner recognizes every chain — these call sites are added to `KnownQueries` / `KnownFileQueries` just like a plain `sql(...)`.
 
-### Array parameters
+### `sql.execute(query, ...params)`
 
-JavaScript arrays passed to `text[]`, `int[]`, `uuid[]`, etc. are auto-encoded as PostgreSQL array literals before being sent. Strings containing commas, braces, quotes, or backslashes are escaped; `null` elements emit SQL `NULL`.
+Execute a typed statement when rows are not the result contract. It preserves parameter checking and returns Postgres command metadata:
 
 ```ts
-await sql("SELECT $1::text[] AS tags", ["alpha", "beta,gamma", "with \"quote\""]);
-// → $1 sent as {alpha,"beta,gamma","with \"quote\""}
+const result = await sql.execute(
+  `UPDATE jobs SET claimed_at = now() WHERE id = $1 AND claimed_at IS NULL`,
+  jobId,
+);
+
+if (result.rowCount !== 1) throw new Error("job was already claimed");
+// result: { rowCount: number; command: string }
 ```
 
-Encoding only kicks in when every element is a primitive (`string` / `number` / `bigint` / `boolean` / `null`). Arrays containing objects pass through unchanged — that's the path for `jsonb` columns whose value is a JSON array (`attachments: SqlxJsJson.Attachment[]`). If you need to store a primitive JS array as `jsonb` (rare), pass `JSON.stringify(arr)` explicitly. `encodePgArrayLiteral(arr)` is exported if you need the literal yourself for `unsafe(...)`.
+`sql.file.execute(...)` and `tx.execute(...)` use the same contract. Query hooks receive the affected-row count rather than `0` for DML without `RETURNING`.
 
-Empty arrays (`[]`) are passed straight through to the active driver. If you need the literal `"{}"` instead (e.g. when concatenating into raw SQL), call `encodePgArrayLiteral([])`.
+### JSON and PostgreSQL array parameters
+
+Parameter wrappers make the wire representation explicit. Use `sql.array(...)` for PostgreSQL arrays and `sql.json(...)` for `json`/`jsonb` values:
+
+```ts
+await sql(
+  "SELECT $1::text[] AS tags",
+  sql.array(["alpha", "beta,gamma", "with \"quote\""]),
+);
+
+await sql(
+  "INSERT INTO events (payload) VALUES ($1)",
+  sql.json([1, 2, 3]),
+);
+
+await sql(
+  "SELECT $1::jsonb[] AS payloads",
+  sql.array([sql.json({ kind: "created" }), sql.json([1, 2, 3]), null]),
+);
+```
+
+Generated parameter types require `PgArrayParameter<T>` or `JsonParameter<T>`, so mixing the two representations is a TypeScript error. A PostgreSQL `json[]` / `jsonb[]` composes both wrappers: the outer `sql.array(...)` selects the PostgreSQL array representation and each non-SQL-NULL element uses `sql.json(...)`. `sql.json(null)` represents JSON `null`; a bare `null` remains SQL `NULL` when the database parameter is nullable.
+
+Both helpers also work with `unsafe(...)`. `encodePgArrayLiteral(arr)` remains exported for code that explicitly needs a PostgreSQL array literal string.
 
 ### Parameter nullability
 
@@ -289,13 +322,18 @@ import { createClient, setClient } from "@onreza/sqlx-js";
 setClient(createClient(process.env.DATABASE_URL));
 ```
 
-`createClient(url, options)` accepts every Postgres.js option plus two sqlx-js extras for observability and reliability:
+`createClient(url, options)` accepts every Postgres.js option plus sqlx-js runtime options:
 
 ```ts
 setClient(createClient(process.env.DATABASE_URL, {
   // Server-side per-connection statement timeout (ms). Also settable via
   // ?statement_timeout=5000 in DATABASE_URL.
   statementTimeoutMs: 5000,
+  // Base directory for root-relative sql.file(...) calls.
+  fileRoot: import.meta.dirname,
+  // Honored for every unsafe call. Set false for PgBouncer transaction mode
+  // unless protocol-level prepared statements are configured there.
+  prepare: false,
   // Fires after every query/transaction statement, success or failure.
   onQuery: ({ query, params, durationMs, rowCount, error }) => {
     if (error) logger.error({ query, error });        // database errors are PgError
@@ -347,8 +385,9 @@ In addition to `import { sql } from "@onreza/sqlx-js"`, the scanner recognises `
 
 ```
 sqlx-js init [--root <dir>] [--schema-provider builtin|pgschema]
+sqlx-js doctor [--root <dir>] [--json]
 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 prepare [--check | --verify | --watch] [--json] [--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>]
 sqlx-js --version | --help
@@ -359,13 +398,14 @@ Regular `prepare` describes queries across a small connection pool (default 8, o
 | Flag                  | Meaning                                                                              |
 |-----------------------|--------------------------------------------------------------------------------------|
 | `--check`             | Offline: verify every scanned query is present in cache, no database required.       |
+| `--verify`            | Prepare against the live/shadow schema and compare generated artifacts without writing. |
 | `--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`).                           |
 | `--no-prune`          | Keep orphaned cache entries instead of removing them.                                |
 | `--migrations <dir>`  | Migrations directory (default: `<root>/migrations`).                                 |
 | `--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.            |
+| `--json`              | Machine-readable prepare diagnostics, doctor output, migration inspection and dry-runs. |
 | `--force`             | For `migrate archive restore`: allow overwriting existing migration files.           |
 | `--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.                   |
@@ -379,6 +419,8 @@ Regular `prepare` describes queries across a small connection pool (default 8, o
 
 Flags that take a value accept both `--flag value` and `--flag=value` forms.
 
+Prepare and doctor JSON use `formatVersion: 1`. Prepare diagnostics include a stable phase plus root-relative file, 1-based line/column, PostgreSQL code/position/hint when available, and the query text. This is intended for CI annotations and editor integrations; stdout contains one JSON document and human progress is suppressed.
+
 `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
@@ -414,10 +456,11 @@ Use `migrate verify` in PR/CI before merge:
 ```bash
 sqlx-js migrate verify
 sqlx-js prepare --check
+sqlx-js doctor --json
 tsc --noEmit
 ```
 
-`migrate verify` runs the same shadow-database migration/down/SQL validation as `migrate dev`, but writes prepare output to temporary files instead of modifying `.sqlx-js/` or `sqlx-js-env.d.ts`.
+`migrate verify` runs the same shadow-database migration/down/SQL validation as `migrate dev`, generates prepare output in a temporary directory, and fails when the committed `.sqlx-js/` or `sqlx-js-env.d.ts` differs. It never modifies those artifacts.
 
 Use `migrate run` in production/staging:
 
@@ -475,10 +518,16 @@ Phases reported separately: `describe failed`, `analyze failed`, `paramMap faile
 
 `sqlx-js.config.ts` at the project root is optional.
 
+Under Node.js, TypeScript config is loaded through Node 24's native type stripping, so keep it to erasable TypeScript syntax. The generated `defineConfig(...)` form works on both Node and Bun; use `.mjs` if the config needs runtime constructs that Node cannot strip.
+
 ```ts
-import type { SqlxJsConfig } from "@onreza/sqlx-js";
+import { defineConfig } from "@onreza/sqlx-js";
 
-const config: SqlxJsConfig = {
+export default defineConfig({
+  scan: {
+    include: ["apps/*/src/**/*", "packages/*/src/**/*"],
+    exclude: ["**/*.generated.ts"],
+  },
   schema: {
     provider: "pgschema",
     file: "schema.sql",
@@ -489,11 +538,11 @@ const config: SqlxJsConfig = {
     "posts.meta":         "SqlxJsJson.PostMeta",
     "posts.attachments":  "SqlxJsJson.Attachment",
   },
-};
-
-export default config;
+});
 ```
 
+By default the scanner uses the root `tsconfig.json` file list and follows TypeScript project references, so a referenced monorepo is scanned without walking unrelated folders. `scan.include` replaces that source-file universe with TypeScript glob patterns; `scan.exclude` is added to the built-in dependency/build exclusions. If there is no root `tsconfig.json`, the fallback is a recursive TypeScript scan.
+
 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):
@@ -514,7 +563,7 @@ declare global {
 export {};
 ```
 
-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.
+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` inside `JsonParameter` for parameters, both exported by `@onreza/sqlx-js`. Pass JSON parameters through `sql.json(value)`: 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. A bare top-level `null` remains SQL `NULL` and is allowed only when the mapped database parameter is nullable; use `sql.json(null)` for JSON `null`.
 
 ### Extension types and `customTypes`
 
@@ -534,16 +583,15 @@ sqlx-js ships with a built-in registry that resolves popular PostgreSQL extensio
 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";
+import { defineConfig } from "@onreza/sqlx-js";
 
-const config: SqlxJsConfig = {
+export default defineConfig({
   customTypes: {
     vector: "Float32Array",         // override pgvector default
     geometry: "GeoJSON.Geometry",   // postgis (not built-in by design)
     myapp_color: "`#${string}`",    // your own CREATE TYPE base/domain
   },
-};
-export default config;
+});
 ```
 
 Domains resolve to their base type through `pg_type.typbasetype`. `CREATE DOMAIN positive_int AS integer CHECK (VALUE > 0)` → `number`, `CREATE DOMAIN tagged AS hstore` → `Record<string, string | null>`. Array variants of any registered scalar are also wired up automatically — `vector[]` → `(number[])[]`.
@@ -576,14 +624,16 @@ Commit the generated `sqlx-js-env.d.ts` and the `.sqlx-js/` cache directory to y
 # 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 prepare --verify  # live/shadow comparison of every generated artifact
+- run: sqlx-js prepare --check   # offline cache/version/config consistency
+- run: sqlx-js doctor --json     # runtime/config/DB/cache/tsconfig preflight
 - run: sqlx-js schema check      # fails if the committed schema snapshot is stale
 - run: tsc --noEmit               # fails if types are stale
-- run: bun test
+- run: bun test --timeout 120000
 - 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`. 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 `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. Add `prepare --verify` when CI has a canonical database/shadow schema and must prove byte-for-byte artifact freshness. `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.
 
@@ -604,23 +654,24 @@ Releases are automated via `release-please`: pushes to `main` accumulate into a
 
 - 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[]>`.
+- Plain `sql(...)` keeps returning rows, so statements without `RETURNING` produce an empty typed array. Use `sql.execute(...)` when affected-row count and command metadata matter.
 - 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)` 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`.
+- Runtime `sql.file(path)` resolves against `fileRoot` while prepare resolves against `--root`. They are both root-relative, but applications started outside the project root must set `fileRoot` explicitly.
 
 See [ROADMAP.md](./ROADMAP.md) for what's planned.
 
 ## Upgrading
 
-### Cache schema change (pre-1.0)
+### Cache and parameter contract change (pre-1.0)
+
+Generated cache now includes `.sqlx-js/cache-manifest.json` with an explicit cache format, generator revision, and hash of `jsonbTypes` / `customTypes`. Cache without this manifest is rejected. Delete `.sqlx-js/` and re-run `sqlx-js prepare` against your database — there is no data loss because the cache is generated.
 
-The `.sqlx-js/<fingerprint>.json` entries dropped `forceNonNull`/`forceNullable` in favour of a single `override?: "non-null" | "nullable"` field. Cache files from the previous schema are rejected with a clear error pointing at the offending file. Delete `.sqlx-js/` and re-run `sqlx-js prepare` against your database — there's no data loss, the cache is regenerated.
+Generated JSON and PostgreSQL array parameters now require `sql.json(...)` and `sql.array(...)`. This removes the ambiguous runtime guess where a JavaScript array could mean either a PostgreSQL array or a JSON array. Replace raw array JSON params with `sql.json(value)` and PostgreSQL arrays with `sql.array(value)` before regenerating declarations.
 
 CI (`prepare --check`) will also fail loudly until the cache is regenerated; this is intentional so a stale schema can't silently emit incorrect `.d.ts`.
 

package/ROADMAP.md

@@ -10,15 +10,13 @@ Items already shipped live in the [README](./README.md) feature list; this file
 | 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. |
 | Tagged-template literal API (`` sql`SELECT ${x}` ``) | 8 | Restoring sqlx's inline-SQL aesthetic requires either a TS compiler plugin (`ts-patch`) or a Bun preload-time AST rewriter. TS itself hardcodes the first tag argument as `TemplateStringsArray` and refuses to narrow to literal tuples. Significant effort, large UX win. |
-| LSP server | 6 | Realtime diagnostics, hover with column types, autocomplete on schema names. Two-to-four weeks for beta, separate VS Code / Neovim extensions. Watch mode covers ~85% of the value today. |
+| LSP server | 6 | Realtime diagnostics, hover with column types, autocomplete on schema names. Versioned `prepare --json` diagnostics now provide the cheaper CI/editor integration foundation; a full server still needs separate VS Code / Neovim clients. |
 | Schema-aware `jsonb` runtime validation | 5 | Optional opt-in: pass a Zod / Valibot / ArkType schema, validate rows on read. Currently we are compile-time-only by design. |
 | MySQL backend | 5 | Some runtime clients support it, but MySQL has no `Describe Statement` equivalent. Would need a real SQL parser pass + `INFORMATION_SCHEMA` introspection. |
 | SQLite backend | 4 | SQLite's column types are dynamic. Would require running `EXPLAIN` and a heuristic mapper, or schema-driven inference per-statement. |
 | `EXPLAIN`-based performance hints | 6 | `prepare` could optionally run `EXPLAIN` per query and surface seq-scan / missing-index warnings. Independent feature; pairs well with CI. |
 | Multi-statement queries | 2 | One SQL string with multiple statements separated by `;`. PG's `Parse` is single-statement; this would require client-side splitting. |
-| Stored procedure / function typing | 3 | `CALL proc(...)` and `SELECT func(...)` with parameter and return-type binding from `pg_proc`. |
 | Streaming / cursor / COPY typing | 3 | Surface Postgres.js cursor / COPY APIs with proper row types. |
 
 ## Long-term

package/dist/bin/sqlx-js.js

@@ -2,13 +2,14 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { runPrepare } from "../src/commands/prepare.js";
+import { PrepareFatalError, runPrepare, } from "../src/commands/prepare.js";
 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";
+import { runDoctor } from "../src/commands/doctor.js";
+import { assertSupportedRuntime, loadConfig, loadRootEnv } 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")]) {
@@ -26,8 +27,9 @@ function help() {
 
 usage:
   sqlx-js init [--root <dir>] [--schema-provider builtin|pgschema]
+  sqlx-js doctor [--root <dir>] [--json]
   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 prepare [--check | --verify | --watch] [--json] [--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>]
   sqlx-js --version
@@ -41,11 +43,12 @@ flags:
   --root <dir>             scan root (default: cwd)
   --dts <path>             declarations output (default: <root>/sqlx-js-env.d.ts)
   --check                  offline mode: verify scanned queries exist in cache, no DB
+  --verify                 prepare against DB/shadow and compare committed generated artifacts
   --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
+  --json                   machine-readable output for prepare and migration inspection/dry-run commands
   --force                  allow archive restore to overwrite existing migration files
   --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
@@ -89,6 +92,26 @@ if (cmd === "--help" || cmd === "-h" || !cmd) {
     help();
 }
 const root = resolve(arg("--root", process.cwd()));
+if (cmd !== "doctor") {
+    try {
+        assertSupportedRuntime();
+    }
+    catch (e) {
+        console.error(e.message);
+        process.exit(2);
+    }
+}
+let envError;
+try {
+    loadRootEnv(root);
+}
+catch (e) {
+    envError = e.message;
+    if (cmd !== "doctor") {
+        console.error(envError);
+        process.exit(2);
+    }
+}
 const databaseUrl = process.env.DATABASE_URL ?? "";
 const shadowUrlArg = arg("--shadow-url");
 const shadowUrl = shadowUrlArg ?? process.env.SHADOW_DATABASE_URL;
@@ -109,6 +132,9 @@ if (cmd === "init") {
     }
     runInit({ root, schemaProvider: provider });
 }
+else if (cmd === "doctor") {
+    await runDoctor({ root, databaseUrl, cacheDir, dtsPath, json: flag("--json"), envError });
+}
 else if (cmd === "db") {
     const sub = process.argv[3];
     if (sub === "install") {
@@ -139,29 +165,55 @@ else if (cmd === "db") {
     }
 }
 else if (cmd === "prepare") {
-    if (flag("--check") && shadowUrlArg) {
-        console.error("--shadow-url cannot be used with prepare --check; use live prepare or schema check --shadow-url");
-        process.exit(2);
+    const prepareCheck = flag("--check");
+    const prepareVerify = flag("--verify");
+    const prepareWatch = flag("--watch");
+    const prepareJson = flag("--json");
+    const prepareMode = prepareVerify ? "verify" : prepareCheck ? "check" : "prepare";
+    const failPrepare = (message, phase, exitCode = 2, location = {}) => {
+        if (prepareJson) {
+            console.log(JSON.stringify({
+                formatVersion: 1,
+                ok: false,
+                mode: prepareMode,
+                sites: 0,
+                entries: 0,
+                failures: 1,
+                pruned: 0,
+                functions: 0,
+                diagnostics: [{ severity: "error", phase, message, ...location }],
+            }, null, 2));
+        }
+        else {
+            console.error(message);
+        }
+        process.exit(exitCode);
+    };
+    if ([prepareCheck, prepareVerify, prepareWatch].filter(Boolean).length > 1) {
+        failPrepare("--check, --verify, and --watch are mutually exclusive", "config");
     }
-    const prepareShadowUrl = flag("--check") ? undefined : shadowUrl;
+    if (prepareCheck && shadowUrlArg) {
+        failPrepare("--shadow-url cannot be used with prepare --check; use live prepare or schema check --shadow-url", "config");
+    }
+    if (prepareWatch && prepareJson) {
+        failPrepare("--watch and --json are mutually exclusive", "config");
+    }
+    const prepareShadowUrl = prepareCheck ? undefined : shadowUrl;
     const prepareDatabaseUrl = prepareShadowUrl ?? databaseUrl;
-    if (!flag("--check") && !prepareDatabaseUrl) {
-        console.error("DATABASE_URL is required for prepare (use --check for offline)");
-        process.exit(2);
+    if (!prepareCheck && !prepareDatabaseUrl) {
+        failPrepare("DATABASE_URL is required for prepare (use --check for offline)", "connect");
     }
     const opts = {
         root,
         databaseUrl: prepareDatabaseUrl,
         cacheDir,
         dtsPath,
-        check: flag("--check"),
+        check: prepareCheck,
+        verify: prepareVerify,
+        json: prepareJson,
         prune: !flag("--no-prune"),
     };
-    if (flag("--watch")) {
-        if (flag("--check")) {
-            console.error("--watch and --check are mutually exclusive");
-            process.exit(2);
-        }
+    if (prepareWatch) {
         await runWatch({
             ...opts,
             ...(prepareShadowUrl
@@ -175,9 +227,28 @@ else if (cmd === "prepare") {
         });
     }
     else {
-        if (prepareShadowUrl)
-            await applyShadowMigrations(prepareShadowUrl, migrationsDir);
-        await runPrepare(opts);
+        if (prepareShadowUrl) {
+            try {
+                await applyShadowMigrations(prepareShadowUrl, migrationsDir, prepareJson ? () => { } : console.log);
+            }
+            catch (e) {
+                failPrepare(e.message, "shadow", 1);
+            }
+        }
+        try {
+            await runPrepare(opts);
+        }
+        catch (e) {
+            const message = e.message;
+            const phase = e instanceof PrepareFatalError
+                ? e.phase
+                : prepareVerify
+                    ? "verify"
+                    : "scan";
+            failPrepare(message, phase, 1, e instanceof PrepareFatalError
+                ? { file: e.file, line: e.line, column: e.column }
+                : {});
+        }
     }
 }
 else if (cmd === "schema") {

package/dist/src/artifacts.d.ts

@@ -0,0 +1,9 @@
+export type ArtifactSet = {
+    cacheDir: string;
+    dtsPath: string;
+};
+export type ArtifactComparison = {
+    ok: boolean;
+    changed: string[];
+};
+export declare function compareArtifacts(expected: ArtifactSet, actual: ArtifactSet): ArtifactComparison;

package/dist/src/artifacts.js

@@ -0,0 +1,26 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { CACHE_MANIFEST_FILE } from "./cache.js";
+function readGeneratedFiles(set) {
+    const files = new Map();
+    if (existsSync(set.cacheDir)) {
+        for (const name of readdirSync(set.cacheDir).sort()) {
+            if (name !== CACHE_MANIFEST_FILE && !/^[0-9a-f]{16}\.json$/.test(name))
+                continue;
+            files.set(`cache/${name}`, readFileSync(join(set.cacheDir, name), "utf8"));
+        }
+        const functions = join(set.cacheDir, "functions/functions.json");
+        if (existsSync(functions))
+            files.set("cache/functions/functions.json", readFileSync(functions, "utf8"));
+    }
+    if (existsSync(set.dtsPath))
+        files.set("sqlx-js-env.d.ts", readFileSync(set.dtsPath, "utf8"));
+    return files;
+}
+export function compareArtifacts(expected, actual) {
+    const left = readGeneratedFiles(expected);
+    const right = readGeneratedFiles(actual);
+    const names = new Set([...left.keys(), ...right.keys()]);
+    const changed = [...names].filter((name) => left.get(name) !== right.get(name)).sort();
+    return { ok: changed.length === 0, changed };
+}

package/dist/src/cache.d.ts

@@ -1,3 +1,11 @@
+export declare const CACHE_FORMAT_VERSION = 2;
+export declare const GENERATOR_REVISION = 3;
+export declare const CACHE_MANIFEST_FILE = "cache-manifest.json";
+export type CacheManifest = {
+    cacheFormat: typeof CACHE_FORMAT_VERSION;
+    generatorRevision: typeof GENERATOR_REVISION;
+    configHash: string;
+};
 export type CacheColumn = {
     name: string;
     typeOid: number;
@@ -19,6 +27,7 @@ export type CacheEntry = {
         reason: string;
     };
 };
+export declare function portableCacheOid(oid: number): number;
 export declare function fingerprint(query: string): string;
 export declare function effectiveNullable(c: CacheColumn): boolean;
 export declare class Cache {
@@ -28,6 +37,10 @@ export declare class Cache {
     has(fp: string): boolean;
     read(fp: string): CacheEntry | null;
     write(fp: string, entry: CacheEntry): void;
+    replaceAll(entries: Iterable<{
+        fp: string;
+        entry: CacheEntry;
+    }>, prune?: boolean): string[];
     list(): {
         fp: string;
         entry: CacheEntry;
@@ -35,3 +48,7 @@ export declare class Cache {
     remove(fp: string): void;
     prune(keep: Iterable<string>): string[];
 }
+export declare function cacheManifestPath(cacheDir: string): string;
+export declare function writeCacheManifest(cacheDir: string, configHash: string): void;
+export declare function readCacheManifest(cacheDir: string): CacheManifest | null;
+export declare function assertCacheManifest(cacheDir: string, configHash: string): CacheManifest;