@tailor-platform/sdk 2.15.0 → 2.17.0

package/docs/services/tailordb-migration.md

@@ -24,7 +24,8 @@ migrations/
 ├── 0001/                    # First change
 │   ├── diff.json            # Field-level diff from 0000
 │   ├── migrate.ts           # Data migration script (auto-generated for breaking changes; can be added manually via `migration script`)
-│   └── db.ts                # Kysely types for the script (pre-migration shape)
+│   ├── db.ts                # Kysely types for the script (pre-migration shape)
+│   └── db.pglite.ts         # CREATE TABLE script of that shape, for PGlite tests
 ├── 0002/
 │   └── diff.json            # No script — non-breaking changes only
 └── ...
@@ -129,7 +130,7 @@ No `migrate.ts` is generated automatically because the schema change itself is n
 tailor tailordb migration script 0002
 ```
 
-This writes `migrations/0002/migrate.ts` and `migrations/0002/db.ts` next to the existing `diff.json` (add `--with-test` to also scaffold a `migrate.test.ts` — see [Testing Migrations Locally](#testing-migrations-locally)). The removed field stays readable inside `migrate.ts` because the pre-migration phase keeps it on the table until the script finishes (see [Per-migration phases](#per-migration-phases)). The next `tailor deploy` runs the script automatically — `migrate.ts` is executed whenever the file exists on disk, regardless of whether the diff itself required it.
+This writes `migrations/0002/migrate.ts`, `migrations/0002/db.ts`, and `migrations/0002/db.pglite.ts` next to the existing `diff.json` (add `--with-test` to also scaffold the tests — see [Testing Migrations Locally](#testing-migrations-locally)). The removed field stays readable inside `migrate.ts` because the pre-migration phase keeps it on the table until the script finishes (see [Per-migration phases](#per-migration-phases)). The next `tailor deploy` runs the script automatically — `migrate.ts` is executed whenever the file exists on disk, regardless of whether the diff itself required it.
 
 If the data loss is intentional and no script is needed, record that decision the same way as for breaking changes (see [Breaking changes without a script](#breaking-changes-without-a-script)):
 
@@ -267,13 +268,15 @@ export default defineConfig({
 
 ## Generated Files
 
-| File                   | When generated                                                                                                                            | Description                                                                                                              |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `0000/schema.json`     | First `migration generate`                                                                                                                | Full snapshot of all tables in the namespace.                                                                            |
-| `XXXX/diff.json`       | Every subsequent migration                                                                                                                | Field-level diff against the previous snapshot.                                                                          |
-| `XXXX/migrate.ts`      | Auto-generated for breaking changes and `--data-only` migrations; added manually via `tailordb migration script` for warning-tier changes | Data transformation script. The `main` export receives a Kysely `Transaction`.                                           |
-| `XXXX/db.ts`           | Generated once when `migrate.ts` is created                                                                                               | Kysely types reflecting the schema **before** this migration. Exports `Database`, `Transaction`, and `MigrationContext`. |
-| `XXXX/migrate.test.ts` | Added via `tailordb migration script --with-test`                                                                                         | Unit-test scaffold for `migrate.ts` (see [Testing Migrations Locally](#testing-migrations-locally)). Never deployed.     |
+| File                          | When generated                                                                                                                            | Description                                                                                                              |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `0000/schema.json`            | First `migration generate`                                                                                                                | Full snapshot of all tables in the namespace.                                                                            |
+| `XXXX/diff.json`              | Every subsequent migration                                                                                                                | Field-level diff against the previous snapshot.                                                                          |
+| `XXXX/migrate.ts`             | Auto-generated for breaking changes and `--data-only` migrations; added manually via `tailordb migration script` for warning-tier changes | Data transformation script. The `main` export receives a Kysely `Transaction`.                                           |
+| `XXXX/db.ts`                  | Generated once when `migrate.ts` is created                                                                                               | Kysely types reflecting the schema **before** this migration. Exports `Database`, `Transaction`, and `MigrationContext`. |
+| `XXXX/db.pglite.ts`           | Generated with `db.ts`                                                                                                                    | `CREATE TABLE` script of the same schema, for running `migrate.ts` on PGlite. Never deployed.                            |
+| `XXXX/migrate.test.ts`        | Added via `tailordb migration script --with-test`                                                                                         | Unit-test scaffold for `migrate.ts` (see [Testing Migrations Locally](#testing-migrations-locally)). Never deployed.     |
+| `XXXX/migrate.pglite.test.ts` | Added via `tailordb migration script --with-test` when `@electric-sql/pglite` is installed                                                | PGlite test scaffold for `migrate.ts`. Never deployed.                                                                   |
 
 `db.ts` reflects the pre-migration schema because the script runs after the pre-migration phase has temporarily relaxed breaking constraints (e.g., a new `required` field is added as `optional` first), so the data being read still matches the previous shape.
 
@@ -386,7 +389,7 @@ The `env` values are injected at bundle time (the same mechanism as resolvers/ex
 | Change field type (verified pair) | Yes       | Yes               | In-place for the pairs listed under [Field type changes](#field-type-changes); review the generated normalization scaffold and customize it only when existing values need transformation                                                          |
 | Change field type (other pair)    | Yes       | Yes               | Two migrations, generated together after you confirm — see [Converting a field type](#converting-a-field-type). Edit the conversion in the first; the second needs no changes.                                                                     |
 | Change array → single value       | -         | -                 | **Not supported** — see [Converting a field type](#converting-a-field-type)                                                                                                                                                                        |
-| Change single value → array       | -         | -                 | **Not supported** — see [Converting a field type](#converting-a-field-type)                                                                                                                                                                        |
+| Change single value → array       | Yes       | Yes               | Two migrations, generated together after you confirm — see [Converting a field type](#converting-a-field-type). Each stored value becomes a one-element array, so the conversion needs no edits.                                                   |
 
 ### Field type changes
 
@@ -460,7 +463,7 @@ The generated `never` annotation intentionally causes a TypeScript error until y
 
 ### Converting a field type
 
-A field type change outside the verified in-place pairs — `string` → `integer`, for example — cannot be applied in one step, because the field would have to hold both shapes at once. `migration generate` offers to carry the values through a temporary field instead:
+A field type change outside the verified in-place pairs — `string` → `integer`, for example — cannot be applied in one step, because the field would have to hold both shapes at once. The same holds when a single value becomes an array (`string` → `string[]`): the stored values must be rewritten as arrays before the field can take the new shape. `migration generate` offers to carry the values through a temporary field instead:
 
 ```
 User.price changes from string to integer, which cannot be applied in one step.
@@ -469,9 +472,11 @@ User.price changes from string to integer, which cannot be applied in one step.
 
 Confirming writes two migrations:
 
-1. **The conversion.** Adds a temporary field (`priceMigrate`), converts each stored value into it, and clears and removes the original field. Edit the conversion expression before deploying: the generated `never` annotation fails your typecheck, and `tailordb migration validate` rejects the migration while the review marker is still there.
+1. **The conversion.** Adds a temporary field (`priceMigrate`), converts each stored value into it, and clears and removes the original field. Edit the conversion expression before deploying: the generated `never` annotation fails your typecheck, and `tailordb migration validate` rejects the migration while the review marker is still there. When only the array-ness changes (`string` → `string[]`), the conversion stores each value as a one-element array and carries no review marker; when the element type changes as well (`integer` → `string[]`), you convert the element and the script wraps it.
 2. **The rename.** Renames the temporary field back to `price`. Its copy script is complete, but this migration also carries every other schema change the same run picked up, so review it as you would any generated migration.
 
+If converting to an array also reduces a decimal field's `scale` or removes enum values, the conversion keeps the review marker. Edit the element conversion to satisfy the target field before deploying.
+
 `tailor deploy` applies both. Because the conversion only touches rows whose original value is still set, a re-run resumes where it stopped rather than converting a row twice.
 
 The original field is removed in the first migration rather than the second, because the rename needs its name free. Your script can still read it while the conversion runs.
@@ -490,7 +495,7 @@ Without the flag the command fails rather than converting anything, so a scripte
 
 Some changes are still rejected and need a temporary field you add yourself — add the new field, write a script that fills it and clears the old one, then remove the old field and rename the temporary one in a later migration:
 
-- Array-to-scalar and scalar-to-array, since collapsing an array has no answer the generated script could choose for you.
+- A field that is already an array: collapsing it into a single value has no answer the generated script could choose for you, and changing its element type (`string[]` → `integer[]`) is not generated either.
 - A field that is unique, or that an index, relationship, permission, or table-level script names. Those keep pointing at the original name, which the conversion removes.
 
 ## Testing Pending Migrations
@@ -809,7 +814,7 @@ Scaffold a ready-to-fill test next to the script with:
 tailor tailordb migration script 0005 --with-test
 ```
 
-When `migrate.ts` already exists (the usual case for breaking changes, where `migration generate` creates it), the command adds only `migrate.test.ts`. Or write the test by hand:
+When `migrate.ts` already exists (the usual case for breaking changes, where `migration generate` creates it), the command adds only the tests that do not exist yet, plus a missing `db.pglite.ts`. Or write the test by hand:
 
 ```typescript
 // migrations/0005/migrate.test.ts
@@ -843,30 +848,24 @@ A statement-level test verifies what the script issues, not what it does to data
 npm install -D @electric-sql/pglite
 ```
 
-Create the tables the script touches (matching the shape in the generated `db.ts`), stage rows, then run the script in a transaction. Type the instance with `Unmigrated<Database>` rather than `Database`: `db.ts` types a column the migration makes required as `T | null` on read but `T` on write (and an enum it narrows as the old values on read but the new ones on write), so that `migrate.ts` cannot write what the migration is removing — which would also stop the test from staging the rows the script has to convert. `Unmigrated` lets every column be written with whatever it can still be read as; `main` still receives a `Transaction<Database>`.
+The generated `db.pglite.ts` exports the `CREATE TABLE` script for the same schema `db.ts` types — the tables as the pre-migration phase leaves them while `migrate.ts` runs, including relaxed constraints, renamed fields under both names, and retained removed fields. Run it once on the PGlite instance, stage rows, then run the script in a transaction. `tailor tailordb migration script <N> --with-test` scaffolds this test too when `@electric-sql/pglite` is installed. Type the instance with `Unmigrated<Database>` rather than `Database`: `db.ts` types a column the migration makes required as `T | null` on read but `T` on write (and an enum it narrows as the old values on read but the new ones on write), so that `migrate.ts` cannot write what the migration is removing — which would also stop the test from staging the rows the script has to convert. `Unmigrated` lets every column be written with whatever it can still be read as; `main` still receives a `Transaction<Database>`.
 
 ```typescript
 // migrations/0005/migrate.pglite.test.ts
 import { PGlite } from "@electric-sql/pglite";
-import { sql } from "@tailor-platform/sdk/kysely";
 import { createKyselyPGlite, type Unmigrated } from "@tailor-platform/sdk/vitest";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import type { Database } from "./db";
+import { pgliteSchema } from "./db.pglite";
 import { main } from "./migrate";
 
-const db = createKyselyPGlite<Unmigrated<Database>>(new PGlite());
+const pglite = new PGlite();
+const db = createKyselyPGlite<Unmigrated<Database>>(pglite);
 
+// PGlite loads Postgres on first use, which can take longer than the default hook timeout.
 beforeAll(async () => {
-  await sql`
-    CREATE TABLE "User" (
-      "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-      "name" text NOT NULL,
-      "email" text,
-      "createdAt" timestamptz NOT NULL,
-      "updatedAt" timestamptz NOT NULL
-    )
-  `.execute(db);
-});
+  await pglite.exec(pgliteSchema.tailordb);
+}, 60_000);
 
 afterAll(async () => {
   await db.destroy();
@@ -894,10 +893,14 @@ describe("0005 add required email", () => {
 });
 ```
 
+Pass nested field values as JavaScript objects or arrays of objects, without `JSON.stringify`.
+Generated migration types use `Record<string, unknown>` for each nested object so scripts can
+work with both old and new members during a migration; narrow member values before using them.
+
 Two caveats keep this from replacing a scratch workspace:
 
 - PGlite runs full PostgreSQL, while TailorDB supports [a subset of it](https://docs.tailor.tech/guides/function/accessing-tailordb#supported-sql-queries) — a statement that passes here can still be rejected on deploy.
-- The `CREATE TABLE` statements are yours, so they can drift from the schema the platform actually has.
+- `db.pglite.ts` mirrors the column shape, not the platform: hooks, validations, and permissions do not run, and the limits listed under [Real SQL execution with PGlite](../testing.md#real-sql-execution-with-pglite-mocktailordbwithpglite) apply.
 
 ### Beyond unit tests
 

package/docs/testing.md

@@ -149,26 +149,30 @@ Pass `{ onUnhandled: "error" }` to make an unmatched query fail instead of retur
 
 Instead of staging responses, back TailorDB with [`@electric-sql/pglite`](https://pglite.dev/) — an in-memory PostgreSQL (install it as a devDependency) — so the queries a resolver, executor, or workflow job issues through `getDB()` execute against real data. `getDB(namespace)` needs no test-side swap: acquire the mock, and each namespace you list resolves to its PGlite instance.
 
-Create the tables the test touches with `CREATE TABLE` statements matching the generated Kysely types — `text` for string and enum fields, `timestamptz` for date/datetime, `jsonb` for nested objects. The schema only has to match what your code reads and writes, not TailorDB's storage; relations are not enforced.
+Let `kyselyTypePlugin` generate the `CREATE TABLE` script for you: set `pgliteSchemaPath` next to `distPath`, and `tailor generate` writes a module exporting one script per namespace, derived from the same table definitions as the Kysely types.
+
+```typescript
+// tailor.config.ts
+kyselyTypePlugin({
+  distPath: "./generated/db.ts",
+  pgliteSchemaPath: "./generated/db.pglite.ts",
+});
+```
+
+Run the namespace's script once per PGlite instance. Every statement is `IF NOT EXISTS`, so applying it again to an instance that already has the tables is harmless.
 
 ```typescript
 import { PGlite } from "@electric-sql/pglite";
 import { mockTailordbWithPGlite } from "@tailor-platform/sdk/vitest";
 import { afterAll, beforeAll, expect, test } from "vitest";
 import { getDB } from "../generated/db";
+import { pgliteSchema } from "../generated/db.pglite";
 import resolver from "./upsertUsers";
 
 const pglite = new PGlite();
 
 beforeAll(async () => {
-  await pglite.exec(`
-    CREATE TABLE "User" (
-      "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-      "name" text NOT NULL,
-      "email" text NOT NULL,
-      "age" integer NOT NULL
-    );
-  `);
+  await pglite.exec(pgliteSchema["main-db"]);
 });
 
 afterAll(async () => {
@@ -201,21 +205,19 @@ test("upserts against real rows", async () => {
 });
 ```
 
-A `.serial()` field is omitted from generated `getDB()` inserts, so its PGlite column must generate a value. Use an identity for an integer serial. For a formatted string serial, create a sequence and reproduce the format in its `DEFAULT` expression:
+The generated columns follow the Kysely types, not TailorDB's storage: `text` for string and enum fields, `timestamptz` for datetime, `date` and `time` for date and time, `numeric` for decimal, rounded to the configured scale and read back with exactly that many fractional digits, `jsonb` for nested objects (and arrays of them), Postgres arrays for other array fields. `id` is a generated `uuid` primary key, `.unique()` fields and unique `.indexes()` are enforced, so `ON CONFLICT` upserts behave, and `.default()` values become column defaults (`"now"` becomes the current time). `.serial()` fields are assigned by the database from the configured `start`, `maxValue`, and format. Relations are not enforced.
 
-```sql
-CREATE SEQUENCE "invoiceNumberSequence" START WITH 1000;
-CREATE TABLE "Invoice" (
-  "sequentialId" integer GENERATED BY DEFAULT AS IDENTITY (START WITH 1),
-  "invoiceNumber" text NOT NULL
-    DEFAULT ('INV-' || lpad(nextval('"invoiceNumberSequence"')::text, 5, '0'))
-);
-```
+What the script cannot reproduce:
+
+- Hooks, validations, and permissions do not run. A required field whose value only its own field-level create hook supplies is created nullable, so inserts that omit it succeed; give it a `.default()` if the test reads it back. A field filled by a table-level hook stays `NOT NULL`, as its Kysely type still requires it on insert.
+- Serial formats are reproduced for a single `%d`, `%x`, or `%X` specifier with an optional zero-padded width; an octal `%o` format fails generation with an error naming the field.
+- A datetime inside a nested object reads back as a string from `jsonb`, not a `Date`.
+- On a persistent PGlite (`dataDir`), tables created by an earlier run are kept as they were; drop them or start from an empty directory after changing a table definition.
 
-PGlite does not apply the TailorDB `.serial()` configuration itself. Match the `start`, `format`, and any limit that the behavior under test relies on.
+To hand-write DDL instead — for a table not in the schema, or to add a constraint — run your own statements after the script, or without it.
 
 - The PGlite instance is yours: the mock never closes it, so close it in `afterAll`. Reuse one instance across a suite — creating one per test is slow.
-- Pass the same instance under several namespaces to drive them against one shared database.
+- Pass the same instance under several namespaces to drive them against one shared database. Two namespaces with a same-named table cannot share one instance, because the second script leaves the first table as it is.
 - Seed through `getDB` itself. When a column type rejects a value that only the test must stage, use `createKyselyPGlite<Unmigrated<...>>(pglite)` instead — see [Testing Migrations Locally](./services/tailordb-migration.md#testing-migrations-locally). This only affects test setup; it cannot supply a `.serial()` value for an insert issued by the code under test.
 - Transactions on a shared instance are serialized: while one is open, queries from other `getDB` instances wait. Do not use `test.concurrent` with a shared instance, and do not query the same instance through a second `getDB` from inside a transaction — that waits on itself.
 - PGlite runs full PostgreSQL while TailorDB supports a subset of it, and TailorDB hooks, validations, and permissions do not run here — a test passing on PGlite can still behave differently on the platform. Keep [`mockTailordb`](#tailordb-mock) or [`createKyselyMock`](#kysely-layer-mock-createkyselymock) tests for query shape and error paths, and E2E tests for platform behavior.
@@ -666,7 +668,7 @@ describe("upsertUsers resolver", () => {
 
 Reach for [`mockTailordb`](#mocking-the-tailordb-client) instead when you want to drive the raw query sequence at the `tailordb.Client` level rather than at the Kysely layer, or [`mockTailordbWithPGlite`](#real-sql-execution-with-pglite-mocktailordbwithpglite) to execute the queries against a real in-memory Postgres.
 
-TailorDB migration scripts (`migrate.ts`) are unit-tested the same way: the generated `db.ts` exports the `Database` interface to type the mock, and `tailor tailordb migration script <N> --with-test` scaffolds a ready-to-fill test. To execute a migration script against real rows in an in-memory Postgres, use `createKyselyPGlite` with `@electric-sql/pglite`. See [Testing Migrations Locally](./services/tailordb-migration.md#testing-migrations-locally).
+TailorDB migration scripts (`migrate.ts`) are unit-tested the same way: the generated `db.ts` exports the `Database` interface to type the mock, and `tailor tailordb migration script <N> --with-test` scaffolds a ready-to-fill test. To execute a migration script against real rows in an in-memory Postgres, use `createKyselyPGlite` with `@electric-sql/pglite` and the generated `db.pglite.ts` schema. See [Testing Migrations Locally](./services/tailordb-migration.md#testing-migrations-locally).
 
 #### Resolvers that resume a workflow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -153,10 +153,10 @@
     "@badgateway/oauth2-client": "3.3.1",
     "@bufbuild/protobuf": "2.14.1",
     "@bufbuild/protovalidate": "1.2.0",
-    "@connectrpc/connect": "2.1.2",
-    "@connectrpc/connect-node": "2.1.2",
-    "@inquirer/core": "12.0.2",
-    "@inquirer/prompts": "8.7.1",
+    "@connectrpc/connect": "2.2.0",
+    "@connectrpc/connect-node": "2.2.0",
+    "@inquirer/core": "12.0.3",
+    "@inquirer/prompts": "8.7.2",
     "@jridgewell/trace-mapping": "0.3.31",
     "@napi-rs/keyring": "2.0.0",
     "@opentelemetry/api": "1.9.1",
@@ -170,7 +170,7 @@
     "@secretlint/secretlint-rule-preset-recommend": "13.0.5",
     "@standard-schema/spec": "1.1.0",
     "@tailor-platform/function-kysely-tailordb": "0.1.3",
-    "@toiroakr/lines-db": "0.12.6",
+    "@toiroakr/lines-db": "0.12.7",
     "@toiroakr/read-multiline": "0.4.1",
     "@urql/core": "6.0.3",
     "amaro": "1.1.11",
@@ -190,7 +190,7 @@
     "p-limit": "7.3.2",
     "pathe": "2.0.3",
     "pgsql-ast-parser": "12.0.2",
-    "pkg-types": "2.3.2",
+    "pkg-types": "2.3.3",
     "rolldown": "1.2.7",
     "semver": "7.8.5",
     "sql-highlight": "6.1.0",
@@ -201,15 +201,16 @@
     "zod": "4.5.4"
   },
   "devDependencies": {
+    "@electric-sql/pglite": "0.5.8",
     "@opentelemetry/sdk-trace-base": "2.11.0",
     "@tailor-platform/shared": "^0.0.0",
     "@tailor-platform/tailor-proto": "^0.0.1",
     "@types/mime-types": "3.0.1",
-    "@types/node": "24.13.3",
+    "@types/node": "24.13.4",
     "@types/semver": "7.8.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@vitest/coverage-v8": "5.0.0",
-    "eslint-plugin-zod": "4.12.0",
+    "eslint-plugin-zod": "4.12.1",
     "oxfmt": "0.66.0",
     "oxlint": "1.81.0",
     "oxlint-tsgolint": "7.0.2001",
@@ -217,7 +218,7 @@
     "tsdown": "0.23.0",
     "typescript": "6.0.3",
     "vitest": "5.0.0",
-    "zinfer": "0.4.5"
+    "zinfer": "0.4.6"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.2.0",