@kequtech/tenon-orm 0.4.0 → 0.4.2

package/docs/migrations.md

@@ -0,0 +1,133 @@
+# SQL migrations
+
+Tenon's optional runner applies numbered SQL files and records their checksums in the database. It
+can be used independently of query execution and type generation. Keep an existing runner unless
+you intend to [transfer migration ownership](adoption-guide.md#transfer-migration-ownership).
+
+## Create and apply a change
+
+```sh
+npx tenon new add_user_display_name
+```
+
+`new` works offline. It creates the next numeric pair in `migrations/`, starting at `0001` in an empty
+directory. For a directory whose latest migration is `0001`:
+
+```sql
+-- migrations/0002_add_user_display_name.up.sql
+ALTER TABLE public.users ADD COLUMN display_name text;
+```
+
+```sql
+-- migrations/0002_add_user_display_name.down.sql
+ALTER TABLE public.users DROP COLUMN display_name;
+```
+
+Set `DATABASE_URL` through your environment, then run:
+
+```sh
+npx tenon status
+npx tenon migrate
+```
+
+`status` prints JSON with `applied` and `pending` ID arrays. `migrate` applies every pending up file
+in numeric order and reports completed IDs. No pending files means nothing changes. No command
+loads `.env` automatically.
+
+After migrating a development database, [generate types](schema-types.md#generate-and-check-a-file),
+review the diff, and commit migrations with generated declarations. Production applies migrations
+and deploys the already-built application. Use a dedicated migrated database for tests.
+
+## File rules and history
+
+Files use `<numeric-id>_<name>.up.sql` and optional matching `.down.sql`. Names contain letters,
+digits, underscores, or hyphens. Each ID has one name and an up file. SQL files with invalid names,
+empty contents, duplicate numeric IDs, or down files without an up file fail validation.
+
+The runner records ID, name, checksum, and application time in `<namespace>.__tenon_migrations`.
+Checksums cover both up SQL and the presence/content of down SQL. Never edit, rename, remove, or
+add a down file to an already-applied migration. Add a new forward migration instead. History must
+match the beginning of the ordered file list; inserting an older migration also causes a conflict.
+
+Migrations may contain multiple statements. Tenon owns the transaction, so authored files must not
+contain transaction-control statements. Use dollar-quoted bodies for functions and explicit `E'...'`
+for backslash escapes. A scaffold's files are empty until you fill them; both are checked even if
+only the up direction is about to run.
+
+## Transaction and failure behavior
+
+Each migration file and its history entry commit together. The whole run is not one transaction:
+if file three fails, files one and two may already have committed. Correct the cause, inspect
+`status`, and rerun. The failed file is rolled back and remains pending. Restore original applied
+files if history validation reports a conflict.
+
+SQL that cannot run in a transaction, such as `CREATE INDEX CONCURRENTLY`, needs a separate,
+application-owned procedure. Tenon has no nontransactional migration flag. It also does not infer
+schema changes or generate migration SQL from TypeScript.
+
+## Roll back
+
+```sh
+npx tenon rollback
+npx tenon rollback --steps 2
+```
+
+Rollback runs the most recent down files in reverse order and removes their history records. It
+prechecks that every selected migration has down SQL before executing any. `steps` must be a
+positive safe integer; requesting more steps than exist selects all applied migrations.
+
+For an irreversible change, omit the down file before first application. The missing file prevents
+rollback across that migration. A down migration is not a backup: dropped data and sequence changes
+may not be recoverable. Use the application's backup and recovery procedure when needed.
+
+## Directory, schema, and locking
+
+Defaults are `--directory migrations` and `--namespace public`. For a custom schema, use the same
+options consistently:
+
+```sh
+npx tenon new add_setting --directory db/migrations
+npx tenon migrate --directory db/migrations --namespace app
+npx tenon status --directory db/migrations --namespace app
+npx tenon rollback --directory db/migrations --namespace app --steps 1
+```
+
+The namespace selects history location, migration search path, and lock scope. During a file,
+`search_path` is `<namespace>, pg_catalog`; qualify cross-schema names explicitly. The runner creates
+the namespace when applying pending migrations. It does not configure runtime application queries.
+Pass the matching namespace to type generation when generating that schema.
+
+Migration and adoption operations use an exclusive session advisory lock for this database and
+namespace. Status and generation use a shared lock. Different namespaces have independent lock
+scopes. These locks do not coordinate with a legacy runner or arbitrary DDL.
+
+Use direct or session-pooled connections for these tools; transaction pooling does not preserve
+their session locks. Configure server timeouts on the tooling connection to bound waits. Migration
+commands do not accept Describe's timeout flags.
+
+Offline file creation uses `.tenon-create.lock` in the directory. Remove a stale lock only after
+confirming that the process which created it has stopped. Baseline capture uses this local lock
+and `pg_dump`; it does not take the runner's database advisory lock.
+
+## Existing databases
+
+An existing schema needs no baseline merely to execute queries or generate types. A baseline is
+needed when Tenon takes over migration history: capture one reviewed schema at the old runner's
+final checkpoint, record it on existing databases without execution, and execute it on fresh ones.
+Follow [the adoption workflow](adoption-guide.md#transfer-migration-ownership).
+
+## Programmatic API
+
+```ts
+import { migrate, migrationStatus, rollback } from '@kequtech/tenon-orm';
+
+const options = { connection, directory: 'migrations', namespace: 'public' };
+const before = await migrationStatus(options); // { applied, pending }
+const applied = await migrate(options); // readonly string[] of completed IDs
+const reverted = await rollback({ ...options, steps: 1 });
+```
+
+`connection` accepts the same URI/options/pool forms as `createTenon`. A supplied pool retains
+application ownership. `createMigration({ name, directory? })` returns `{ id, upPath, downPath }`;
+`readMigrations(directory?)` returns validated `{ id, name, up, down?, checksum }` records.
+See [the command reference](reference.md#command-reference) for all CLI forms.

package/docs/mutations.md

@@ -1,11 +1,14 @@
-# Mutation cookbook
+# Writing data
 
-Use `sql.insertValues` and `sql.assignments` for object fields while keeping SQL structure visible.
-The [reference](reference.md#object-based-mutation-fragments) defines the complete contract.
-Examples assume an existing `db` and this table, with generated `Database` from the same schema:
+Write `INSERT`, `UPDATE`, `DELETE`, and `ON CONFLICT` in SQL. Use `sql.insertValues` and
+`sql.assignments` when you have an object of field values; they return fragments for the column/value
+parts of your statement. The [API reference](reference.md#object-based-mutation-fragments) defines
+edge cases and validation rules.
+
+Examples use an existing `db`, import `sql` from Tenon, and assume this table:
 
 ```sql
-CREATE TABLE profiles (
+CREATE TABLE public.profiles (
   id integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
   name text NOT NULL UNIQUE,
   bio text DEFAULT 'unwritten',
@@ -14,23 +17,41 @@ CREATE TABLE profiles (
 );
 ```
 
-## Defaults, undefined, and null in batches
+## Insert and return a row
+
+```ts
+import { sql } from '@kequtech/tenon-orm';
+
+const profile = await db.query(
+  sql<{ id: number; name: string }>`INSERT INTO public.profiles
+    ${sql.insertValues({ name: 'Ada' })} RETURNING id, name`,
+  { returns: 'one' },
+);
+```
+
+The helper emits `("name") VALUES ($1)` and binds `'Ada'`. PostgreSQL fills defaults. You choose
+`RETURNING` and the result mode explicitly.
+
+## Defaults, undefined, and null
 
 ```ts
 await db.query(
-  sql`INSERT INTO profiles ${sql.insertValues([
-    { name: 'Ada', bio: null },
-    { name: 'Lin', score: 4, bio: undefined },
-  ])} RETURNING id`,
-  { returns: 'many' },
+  sql`INSERT INTO public.profiles ${sql.insertValues([
+    { name: 'Lin', bio: null },
+    { name: 'Jo', score: 4, bio: undefined },
+  ])}`,
 );
 ```
 
-Ada gets the score default and SQL null for bio. Lin gets score 4 and the bio default. Columns stay
-aligned across heterogeneous rows. Empty batches fail; a single default-only object emits
-`DEFAULT VALUES` and still depends on the table's required-column rules.
+Lin gets score 0 and SQL null for bio. Jo gets score 4 and the bio default. Heterogeneous rows stay
+aligned. Missing/undefined insert cells use `DEFAULT`; explicit null remains SQL NULL.
+
+A single default-only object emits `DEFAULT VALUES`, which still fails if the table has an unmet
+required column. Empty batches fail. Multiple default-only rows need an explicit column list.
+
+## Type and select accepted fields
 
-## Input types and runtime validation
+Generate `Database` from the same schema, then narrow the fields the application accepts:
 
 ```ts
 import { sql, type QueryClient } from '@kequtech/tenon-orm';
@@ -40,108 +61,124 @@ type ProfileInput = Pick<Database['profiles']['insert'], 'name' | 'score'>;
 
 function createProfile(client: QueryClient, input: ProfileInput) {
   return client.query(
-    sql<{ id: number }>`INSERT INTO profiles
-    ${sql.insertValues(input, ['name', 'score'])} RETURNING id`,
+    sql<{ id: number }>`INSERT INTO public.profiles
+      ${sql.insertValues(input, ['name', 'score'])} RETURNING id`,
     { returns: 'one' },
   );
 }
 ```
 
-Annotations, `satisfies`, or helper generic arguments apply generated input types; merely generating
-the file does not check writes. Use `Pick` to narrow accepted fields and retain runtime validation.
-Generated inputs describe defaults and driver representations, not authorization or constraints.
+The explicit column list selects and orders fields and ignores unlisted keys. Keep required insert
+fields in that list: a well-typed object can still produce an invalid insert if selection discards
+its required `name`. Helpers have no schema metadata; PostgreSQL enforces constraints.
 
-Selected columns choose and order fields, ignoring unlisted keys. They can discard a required field
-even when the original object is valid:
+Types apply through annotations, `satisfies`, or helper generic arguments. They do not validate
+external data, authorization, JSON contents, or CHECK constraints. See
+[generated inputs](schema-types.md#insert-and-update-inputs).
 
-```ts
-const input: Database['profiles']['insert'] = { name: 'Ada' };
-const query = sql`INSERT INTO profiles ${sql.insertValues(input, ['bio', 'score'])}`;
-// Executing this fails: name was discarded and has no default.
-```
+## Patch fields and use expressions
 
-## Patches mixed with expressions
+For a validated `id` and patch:
 
 ```ts
 const patch: Pick<Database['profiles']['update'], 'name' | 'bio'> = { bio: null };
-await db.query(sql`UPDATE profiles SET ${sql.assignments(patch)}, revision = revision + 1
-  WHERE id = ${id}`);
+await db.query(
+  sql`UPDATE public.profiles SET ${sql.assignments(patch)}, revision = revision + 1
+    WHERE id = ${id}`,
+  { affectedRows: { exact: 1 } },
+);
 ```
 
-Missing/undefined fields are omitted; null clears a nullable field. Put arithmetic and
-`column = DEFAULT` in SQL. Helpers accept values, not SQL expression objects.
+Assignments omit missing/undefined fields. Null clears a nullable field. Put arithmetic,
+`column = DEFAULT`, and other SQL expressions in the surrounding statement; helper cells accept
+bound values, not SQL fragments or expression objects.
 
-An empty patch fails even if the surrounding SQL has other assignments. Branch when an
-expression-only update is intended:
+`sql.assignments` throws if no defined fields remain, even if the surrounding query has another
+assignment. Skip an empty patch, or branch when an expression-only update is intended:
 
 ```ts
 if (patch.name !== undefined || patch.bio !== undefined) {
-  await db.query(sql`UPDATE profiles SET ${sql.assignments(patch)}, revision = revision + 1
-    WHERE id = ${id}`);
+  await db.query(
+    sql`UPDATE public.profiles SET ${sql.assignments(patch)}, revision = revision + 1
+    WHERE id = ${id}`,
+    { affectedRows: { exact: 1 } },
+  );
 } else {
-  await db.query(sql`UPDATE profiles SET revision = revision + 1 WHERE id = ${id}`);
+  await db.query(sql`UPDATE public.profiles SET revision = revision + 1 WHERE id = ${id}`, {
+    affectedRows: { exact: 1 },
+  });
 }
 ```
 
-## Preserve an omitted field during an upsert
+## Upsert without overwriting an omitted field
 
-Given validated `name`, `score`, and optional `bio`, choose conflict behavior explicitly:
+For validated `name`, `score`, and optional `bio`, choose conflict behavior explicitly:
 
 ```ts
 if (bio !== undefined) {
-  await db.query(sql`INSERT INTO profiles ${sql.insertValues({ name, score, bio })}
+  await db.query(sql`INSERT INTO public.profiles ${sql.insertValues({ name, score, bio })}
     ON CONFLICT (name) DO UPDATE SET score = excluded.score, bio = excluded.bio`);
 } else {
-  await db.query(sql`INSERT INTO profiles ${sql.insertValues({ name, score })}
+  await db.query(sql`INSERT INTO public.profiles ${sql.insertValues({ name, score })}
     ON CONFLICT (name) DO UPDATE SET score = excluded.score`);
 }
 ```
 
-The second query preserves an existing bio. Omitting an insert value uses its database default; that
-alone does not decide which fields a conflict update overwrites.
+The second branch preserves an existing bio. Omitting an insert field uses its database default;
+it does not decide whether an upsert overwrites that field.
+
+## Delete with a bound
+
+```ts
+await db.query(sql`DELETE FROM public.profiles WHERE id = ${id}`, {
+  affectedRows: { max: 1 },
+});
+```
+
+Zero or one deletion is allowed; more causes rollback. Use `exact: 1` when absence is also an error.
+Guards work without `RETURNING`. See [transactions and guards](reference.md#transactions-guarded-writes-and-errors).
 
 ## JSON and PostgreSQL arrays
 
-For a table with `payload jsonb` and `tags text[]`, encode JSON separately from the PostgreSQL
-array:
+For an additional table with `payload jsonb` and `tags text[]`:
 
 ```ts
 import { builtin, json, param } from '@kequtech/tenon-orm';
 
 const tags = ['ada', 'lin'];
-await db.query(
-  sql`INSERT INTO deliveries ${sql.insertValues({ payload: json(tags), tags: param(tags, builtin.textArray) })}`,
-);
+await db.query(sql`INSERT INTO public.deliveries
+  ${sql.insertValues({ payload: json(tags), tags: param(tags, builtin.textArray) })}`);
 ```
 
-Generated JSON writes accept pgclear parameters or encoded strings. `json(value)` encodes objects,
-arrays, strings, and JSON null; plain `null` means SQL NULL. Arrays need `param(value, codec)` or
-encoded PostgreSQL text. Plain arrays, objects, and undefined reject as bound values. Tenon passes
-explicit parameters unchanged to pgclear. `json()` still rejects bigint values, including bigint
-nested inside objects; bigint support for ordinary SQL parameters does not change JSON encoding.
-
-For bigint/bigserial fields, generated writes accept exact strings, bigint, or explicit parameters;
-reads remain strings by default. Use `param('9007199254740993', builtin.int8)` for an explicit int8
-parameter and `param(['9007199254740993', null], builtin.int8Array)` for an int8 array. The bigint
-output codec and matching array encoder are separate opt-in choices.
+`json(value)` encodes a JSON document; `param(value, codec)` chooses a PostgreSQL type and encoder.
+A JSON array and a PostgreSQL array are separate formats. Generated writes accept encoded strings
+or explicit parameters; plain objects/arrays reject. `json(null)` means JSON null, while plain
+`null` means SQL NULL. `json('text')` encodes a JSON string, not an already-encoded document.
+JSON encoding rejects bigint, including nested bigint values.
 
-Date and supported Temporal values can be ordinary scalar inputs, including mutation fields. Date
-encodes in UTC; Temporal calendar dates, wall times, and instants retain their distinct meanings.
-Choose the value appropriate to the PostgreSQL column and retain application validation.
+For int8, use exact strings, bigint, or `param('9007199254740993', builtin.int8)`. For an int8 array,
+use `param(['9007199254740993', null], builtin.int8Array)`. Reads remain strings by default. Plain
+Date and supported Temporal values work as scalar inputs; Date encodes in UTC. Neither input form
+changes the output decoder. See [value mappings](schema-types.md#value-mappings).
 
-## Batches in one transaction
+## Batch within one transaction
 
-For an array `rows` of generated profile inputs:
+For `rows` containing generated profile insert inputs:
 
 ```ts
 await db.transaction(async (tx) => {
   for (let offset = 0; offset < rows.length; offset += 300) {
     const batch = rows.slice(offset, offset + 300);
-    await tx.query(sql`INSERT INTO profiles ${sql.insertValues(batch, ['name', 'bio', 'score'])}`);
+    await tx.query(sql`INSERT INTO public.profiles
+      ${sql.insertValues(batch, ['name', 'bio', 'score'])}`);
   }
 });
 ```
 
-A failure rolls back all batches. Empty input makes no insert calls. Choose a batch size below the
-query-wide 65,535-parameter limit, including surrounding parameters; default cells consume none.
-Tenon does not split batches or choose transaction boundaries for you.
+A failure rolls back every batch; empty input makes no calls. Choose a batch size below the
+query-wide 65,535-parameter limit, counting surrounding interpolations too. Default cells consume
+no parameters. Tenon does not split batches or choose transaction boundaries.
+
+These helpers support optional fields at runtime. The optional source checker needs explicit shape
+types with required selected fields and fixed batch lengths; ordinary generated patch types can
+remain unchecked. See [object expansion checking](query-checking.md#object-expansion).