@tailor-platform/sdk 2.27.0 → 2.29.0

package/docs/github-actions.md

@@ -35,7 +35,8 @@ tailor setup ci tag --name my-app-prod \
 
 After running the command, follow the **Next steps** printed to the terminal:
 run `tailor setup ci env` to get the commands that set the secrets and
-variables each GitHub Environment needs (see
+variables each GitHub Environment needs, and `tailor setup ci env --check` to
+confirm none is missing (see
 [Setting secrets and variables](#setting-secrets-and-variables)), then commit
 the generated files.
 
@@ -98,7 +99,8 @@ The generated workflow builds one self-contained ERD viewer HTML file for each
 owned TailorDB namespace in `tailor.config.ts`. The viewer compares the pull
 request merge result with the base branch, can switch between the current schema
 and highlighted diff, uploads the HTML files as unarchived Actions artifacts,
-and upserts a PR comment with artifact links.
+and upserts a PR comment with artifact links. On GitHub Enterprise Server, also
+pass `--ghes` (see [GitHub Enterprise Server](#github-enterprise-server)).
 
 ERD preview does not use Tailor Platform credentials. Fork pull requests still
 build artifacts, but the comment step is skipped because fork tokens cannot
@@ -194,6 +196,26 @@ the `plan` job as well as `deploy`, because `plan` must enter the environment to
 read the variable. (A token-based read that lets `plan` run without entering the
 environment is planned.)
 
+## Package manager
+
+The generated workflow sets up your package manager, installs dependencies with
+it, and runs `tailor` through it. `setup ci` detects the package manager from the
+lockfile at the repository root (`pnpm-lock.yaml`, `yarn.lock`, `bun.lock`,
+`bun.lockb`, `package-lock.json`, or `npm-shrinkwrap.json`), or, when there is
+none, from the `packageManager` or `devEngines.packageManager` field of the root
+`package.json`. When neither names one, `setup ci` stops instead of guessing.
+
+Pass `--package-manager` (`pnpm`, `npm`, `yarn`, or `bun`) to choose it
+yourself, for example to generate the workflow before the lockfile exists:
+
+```bash
+tailor setup ci branch --name my-app-stg --package-manager pnpm
+```
+
+The workflow installs dependencies at the repository root, so commit the
+lockfile there before it runs. `tailor setup update` keeps a package manager
+chosen with `--package-manager` and detects it again otherwise.
+
 ## Generated files
 
 Running a workflow setup subcommand creates or updates:
@@ -244,8 +266,8 @@ Everything else is yours, and re-running `setup` keeps it:
 - **These inputs of managed steps:** `ignore` on `tailor-generate-check` and
   `tailor-drift-check`, `fail-on-drift` on `tailor-drift-check`,
   `install-command` on `tailor-install`, `node-version-file` on
-  `tailor-setup`, `label` on `tailor-plan`, and `user-mapping` on
-  `tailor-notify`.
+  `tailor-setup`, `label` on `tailor-plan`, `ttl` on `tailor-preview-deploy`,
+  and `user-mapping` on `tailor-notify`.
 - **Your own jobs in the `needs` of `tailor-result` and
   `tailor-preview-result`**, so they count toward the workflow's result (see
   [Requiring the workflow in branch protection](#requiring-the-workflow-in-branch-protection)).
@@ -276,6 +298,17 @@ The job is skipped whenever `tailor-preview-deploy` is skipped: when a pull
 request is closed, for draft and fork pull requests, and for unlabeled ones with
 `--require-preview-label`.
 
+A preview workspace expires 7 days (`ttl: 7d` on `tailor-preview-deploy`) after
+the last push to its pull request. When a pull request is closed,
+`tailor-preview-cleanup` deletes its workspace and also deletes the other
+expired preview workspaces of the same workspace name in the folder
+(`TAILOR_PLATFORM_FOLDER_ID`, or directly under the organization when unset), so
+a workspace whose own cleanup never ran does not stay forever. A pull request
+that stays idle past the `ttl` can have its workspace deleted while it is still
+open; the next push creates a fresh one. Change `ttl` to keep previews longer or
+shorter. Workflows generated before this was added get these settings the next
+time you run `tailor setup update`.
+
 Each new preview workflow run for a pull request, such as after a push or when
 the pull request is closed, cancels the run still in progress for it, including
 your jobs, so they do not keep running against a workspace that the new run
@@ -448,14 +481,18 @@ protection rules no longer guard your deploys.
 Environment the generated workflows use, the commands that create the
 environment (only when it does not exist yet) and set its secrets and
 variables. It is read-only, so re-run it whenever you add a target. When the
-`origin` remote points at github.com, the output names that repository, so the
-commands work from any directory; otherwise `gh` resolves the repository from
-the current directory and the Terraform output leaves it as a placeholder.
+`origin` remote points at github.com, the output names that repository;
+otherwise it names the repository `gh repo view` reports for the current
+directory, with its host on GitHub Enterprise Server. Either way the commands
+work from any directory. When neither names a repository, `gh` resolves it from
+the current directory when you run the commands, and the Terraform output leaves
+it as a placeholder.
 
 ```bash
 tailor setup ci env                          # gh CLI commands (default)
 tailor setup ci env --format terraform       # Terraform for the integrations/github provider
 tailor setup ci env --environment my-app-stg # only one environment (repeat for several)
+tailor setup ci env --check                  # check what is registered in GitHub (see below)
 ```
 
 The list follows what each generated workflow actually reads:
@@ -497,6 +534,30 @@ protection settings (reviewers, wait timer, branch policy), so importing an
 environment keeps the approval gate you configured; remove the `lifecycle` block
 to manage those settings in Terraform instead.
 
+### Checking what is registered
+
+`tailor setup ci env --check` reads GitHub with `gh` and reports, for each
+environment, which of these entries are registered. It fails when a required
+entry is missing, reports missing optional entries without failing, and prints
+the `gh` commands that set only the missing entries, with where each value comes
+from. It changes nothing, and it checks names only, since GitHub never returns
+secret values.
+
+- An entry set on the repository, or on the organization and shared with the
+  repository, counts as registered, because the workflow reads it from there when
+  the environment does not set it. The report says where each entry was found.
+- An entry registered as the other kind, such as `TAILOR_PLATFORM_WORKSPACE_ID`
+  set as a secret, is reported as missing, because the workflow does not read it.
+  `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID` set as a secret still counts, with a
+  reminder to move it to a variable.
+- `gh` must be installed and logged in (`gh auth login`) as an account with write
+  access to the repository, which listing secrets and variables requires. GitHub
+  answers 404 for a private repository the account cannot see, so the check
+  reports that as an access problem, not as missing entries.
+
+`--environment` narrows the check the same way. `--check` cannot be combined with
+`--format terraform`.
+
 ## GitHub Environments (approval gate)
 
 Both the `plan` and `deploy` jobs are associated with a GitHub Environment — the
@@ -553,6 +614,67 @@ plan job also enters the environment, allow `refs/pull/*/merge` as well so pull
 request plans keep running, and note that dry runs from other branches are then
 rejected too.
 
+## Seeding the workspace after deploy
+
+Pass `--seed` to `setup ci branch`, `setup ci tag`, or `setup ci preview` to seed
+the workspace with `tailor seed apply` right after each deploy. Add
+`--seed-dataset <name>` (repeatable, implies `--seed`) to apply
+[datasets](https://github.com/tailor-platform/sdk/tree/main/packages/sdk-plugin-seed#datasets)
+on top of the base seed data:
+
+```bash
+tailor setup ci branch --seed-dataset stg
+tailor setup ci preview --region us-west --seed-dataset preview
+```
+
+The deploy job gains a `tailor-seed` step after the deploy step. Branch targets
+validate seed data before deploy and also in the PR or dry-run plan job; tag
+targets validate it in the plan job before deploy. Both use
+`tailor seed validate --upsert` with the selected datasets to check the `id`
+and required fields that `seed apply --upsert` needs. Preview targets validate
+and apply the data after deploy.
+
+| Target      | Seeds with                           | Effect                                                                        |
+| ----------- | ------------------------------------ | ----------------------------------------------------------------------------- |
+| branch, tag | `tailor seed apply --upsert`         | The fields of each committed seed row are written; other rows are kept        |
+| preview     | `tailor seed apply --truncate --yes` | The preview workspace is emptied, IdP users included, and seeded from scratch |
+
+Setup stops unless the config uses `seedPlugin` with `machineUserName`, which
+names the machine user that seeds, and an existing `<distPath>/data/` directory.
+Every `--seed-dataset` must name an entry of
+the `seedPlugin` `datasets` option or a directory under `<distPath>/data/`.
+Commit the dataset directories the workflow seeds: a gitignored dataset such as
+a per-developer `local/` is not in the CI checkout.
+Install `@tailor-platform/sdk-plugin-seed` so the `tailor seed` commands resolve
+in CI. For branch and tag targets, use a version that supports
+`tailor seed validate --upsert`; update the setup and seed plugins together.
+Give every TailorDB seed row an `id` and
+every field its table requires: `--upsert` matches rows by id, so run
+`tailor seed fill` and commit the result.
+Seeding is available for a target that deploys one app.
+
+Before enabling it, note that:
+
+- Every branch or tag deploy writes the fields of the committed seed rows over
+  the workspace, `_User` rows and their passwords included, so an edit to one of
+  those fields in the workspace is undone. Each row is updated like any other update: update hooks
+  and validation run, `updatedAt` changes, and executors with
+  `recordUpdatedTrigger` fire once per seeded row on every deploy.
+- Every preview deploy deletes the data reviewers added to the preview
+  workspace. That is every push, and with `--require-preview-label` also every
+  label added to the pull request, since each one redeploys the preview.
+- A seed failure fails the deploy job and its notification, although the deploy
+  itself went through.
+- The step shares the deploy job's timeout. IdP users take about a second each.
+- Steps you added after the deploy step stay right after it, so they run before
+  `tailor-seed`. Move a step below `tailor-seed` when it needs the seeded data,
+  and move it again if you regenerate without `--seed` and then with it.
+- `tailor-seed` is an SDK-managed step. To seed another way (a different mode,
+  `--skip-idp`, a condition), leave `--seed` off and add your own step.
+
+Re-run `setup ci` with the flags each time you regenerate the workflow; `setup
+update` keeps them.
+
 ## Monorepo setup
 
 For a monorepo where your SDK app lives in a subdirectory, pass `--dir`:
@@ -673,8 +795,9 @@ a branch target deploys only its target branch, so use Option 1 there.
 - **Schema and data are not rolled back.** If the older config expects a schema
   state that no longer exists, the plan may show errors. In that case, review
   the diff carefully before proceeding.
-- **Seed data** is not part of the deployment pipeline and is unaffected by
-  rollbacks.
+- **Seed data** is not rolled back. Without `--seed`, the pipeline does not
+  touch it; with `--seed`, deploying an older commit seeds the rows committed
+  there on top of the current data.
 - **Static websites** are not yet integrated into the generated pipeline.
   Static asset rollbacks must be performed manually.
 
@@ -702,6 +825,48 @@ tailor setup ci env
 
 Commit both workflow files and `.github/tailor.lock`.
 
+## GitHub Enterprise Server
+
+The generated workflows also run on GitHub Enterprise Server. Prepare the
+server and its runners first:
+
+- **Runners:** GitHub Enterprise Server has no GitHub-hosted runners. Change
+  `runs-on` on the managed jobs to the labels of your self-hosted runners;
+  re-running `setup` keeps it (see
+  [Customizing the generated workflow](#customizing-the-generated-workflow)).
+  The runners need Actions runner 2.327.1 or later, which runs the Node 24
+  actions the workflows use, and `gh` and `jq` on `PATH` (plus `node` with
+  `--erd-preview`).
+- **Actions from github.com:** the workflows use `tailor-platform/actions`,
+  `actions/checkout`, `actions/setup-node`, `pnpm/action-setup`, and
+  `oven-sh/setup-bun` (and `actions/upload-artifact` with `--erd-preview`).
+  Make them available on the server with GitHub Connect or `actions-sync`. The
+  server ships its own copies of the `actions/*` ones, which may not include
+  the pinned versions: update them with `actions-sync`, or, with GitHub
+  Connect, delete them from the server's `actions` organization (see GitHub's
+  [Using the latest version of the official bundled actions](https://docs.github.com/en/enterprise-server@latest/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/using-the-latest-version-of-the-official-bundled-actions)).
+- **Environment settings:** sign `gh` in to the server
+  (`gh auth login --hostname <host>`) before you run `tailor setup ci env` in a
+  clone of the repository, so that the `gh` commands it prints and its Terraform
+  output target the server. When `gh` cannot tell the repository, the output
+  says to export `GH_HOST=<host>` before running the `gh` commands, or
+  `GITHUB_BASE_URL=https://<host>/` before running Terraform, so that they
+  call the server instead of github.com.
+
+With `--erd-preview`, also pass `--ghes`:
+
+```bash
+tailor setup ci branch --name my-app-stg --erd-preview --ghes
+```
+
+GitHub Enterprise Server does not support `actions/upload-artifact` v4 or
+later, which the workflow uses to upload each ERD viewer unzipped. With
+`--ghes`, the workflow uploads it with v3 instead, so each viewer is a zip
+file, and the PR comment links to the workflow run, which lists the artifacts.
+`setup update` keeps `--ghes`; pass it again whenever you re-run
+`setup ci branch`, or the workflow switches back to the upload that GitHub
+Enterprise Server does not support.
+
 ## Keeping dependencies and actions updated
 
 Run this command once from the repository root to add Renovate configuration:
@@ -781,10 +946,11 @@ It regenerates every workflow recorded in
 have to re-type `setup ci branch`, `setup ci tag`, and the rest one by one.
 Your own jobs, steps, and settings are kept (see
 [Customizing the generated workflow](#customizing-the-generated-workflow)). A
-branch that was detected from the repository default branch is detected again,
-and the parts that follow your config — the migration drift check, seed
-validation, and ERD preview namespaces — are derived
-from the current `tailor.config.ts`.
+branch that was detected from the repository default branch and a
+[package manager](#package-manager) that was detected from the repository root
+are detected again, and the parts that follow your config — the migration drift
+check, seed validation, and ERD preview namespaces — are derived from the
+current `tailor.config.ts`.
 
 A target that cannot be regenerated, for example because you edited a managed
 part, does not stop the others: `update` regenerates the rest, then lists the

package/docs/multi-environment.md

@@ -96,3 +96,27 @@ defineStaticWebSite("my-website", {
   customDomains: process.env.APP_ENV === "production" ? ["app.example.com"] : undefined,
 });
 ```
+
+## Seed data per environment and per scenario
+
+`seedPlugin` seeds every environment from the JSONL files in `<distPath>/data/`. Rows that only some environments or scenarios need go into **datasets** — directories under `<distPath>/data/` that hold JSONL files for some of the tables — and are applied on top of the base seed data with `tailor seed apply --dataset <name>`:
+
+```
+seed/data/
+  *.schema.ts, *.jsonl     # base seed data, applied everywhere
+  cogs/Item.jsonl          # scenario: rows only a costing demo needs
+  dev/Account.jsonl        # environment: the dev variant of a table
+  stg/Account.jsonl        # environment: the staging variant of the same table
+  local/_User.jsonl        # per developer, gitignored
+```
+
+A table whose rows differ per environment lives only in the per-environment datasets, since a row may be defined in only one of the selected files. Name the combinations each environment uses in the `datasets` option of `seedPlugin`, so a deploy pipeline runs `tailor seed apply --dataset preview` instead of repeating the list:
+
+```typescript
+seedPlugin({
+  distPath: "./seed",
+  datasets: { preview: ["cogs", "dev"] },
+});
+```
+
+The `tailor seed` commands come from the `@tailor-platform/sdk-plugin-seed` CLI plugin; see its [Datasets](https://github.com/tailor-platform/sdk/tree/main/packages/sdk-plugin-seed#datasets) guide for validating, filling, and dumping datasets.

package/docs/plugin/custom.md

@@ -516,9 +516,9 @@ export default createSoftDeletePlugin();
 ```typescript
 // plugins/soft-delete/executors/on-delete.ts
 import { createExecutor, recordDeletedTrigger } from "@tailor-platform/sdk";
-import type { TailorAnyDBType } from "@tailor-platform/sdk";
 import { withPluginContext } from "@tailor-platform/sdk/plugin";
 import { getDB } from "generated/tailordb";
+import type { TailorAnyDBType } from "@tailor-platform/sdk";
 
 interface SoftDeleteContext {
   sourceTable: TailorAnyDBType;

package/docs/services/idp.md

@@ -106,7 +106,7 @@ defineIdp("my-idp", {
 **Operators:** `"="`, `"!="`, `"in"`, `"not in"`
 
 > [!WARNING]
-> A policy of `[{ user: "_loggedIn" }, "=", true]` permits every authenticated user to run the operation against any IdP user. For `read` and `update` this exposes and lets them change other users' login information (such as email addresses), and for `sendPasswordResetEmail` it lets them send reset emails to anyone. Use it only when every user who can sign in to the project is trusted. For an IdP used by external users (such as business partners), restrict each operation to an administrator role as shown above.
+> A policy of `[{ user: "_loggedIn" }, "=", true]` permits every authenticated user to run the operation against any IdP user. For `read` and `update` this exposes and lets them change other users' login information (such as email addresses), and for `sendPasswordResetEmail` it lets them send reset emails to anyone. Use it only when every user who can sign in to the project is trusted. For an IdP used by external users (such as business partners), restrict each operation to an administrator role as shown above. `tailor deploy` warns about each rule whose only condition is `_loggedIn`.
 
 **Helper:** `unsafeAllowAllIdPPermission` grants full access without conditions. Intended only for development and testing.
 

package/docs/services/resolver.md

@@ -11,64 +11,7 @@ Resolvers provide:
 - Access to TailorDB via Kysely query builder
 - User context for authentication/authorization
 
-## Comparison with Tailor Platform Pipeline Resolver
-
-The SDK's Resolver is a simplified version of Tailor Platform's [Pipeline Resolver](https://docs.tailor.tech/guides/resolver).
-
-| Pipeline Resolver                        | SDK Resolver                      |
-| ---------------------------------------- | --------------------------------- |
-| Multiple steps with different operations | Single `body` function            |
-| Declarative step configuration           | Imperative TypeScript code        |
-| Built-in TailorDB/GraphQL steps          | Direct database access via Kysely |
-| CEL expressions for data transformation  | Native TypeScript transformations |
-
-### Example Comparison
-
-**Pipeline Resolver (Tailor Platform native):**
-
-```yaml
-steps:
-  - name: getUser
-    operation: tailordb.query
-    params:
-      type: User
-      filter:
-        email: { eq: "{{ input.email }}" }
-  - name: updateAge
-    operation: tailordb.mutation
-    params:
-      type: User
-      id: "{{ steps.getUser.id }}"
-      input:
-        age: "{{ steps.getUser.age + 1 }}"
-```
-
-**Resolver (SDK):**
-
-```typescript
-createResolver({
-  name: "incrementUserAge",
-  operation: "mutation",
-  input: { email: t.string() },
-  body: async (context) => {
-    const db = getDB("tailordb");
-    const user = await db
-      .selectFrom("User")
-      .selectAll()
-      .where("email", "=", context.input.email)
-      .executeTakeFirstOrThrow();
-
-    await db
-      .updateTable("User")
-      .set({ age: user.age + 1 })
-      .where("id", "=", user.id)
-      .execute();
-
-    return { oldAge: user.age, newAge: user.age + 1 };
-  },
-  output: t.object({ oldAge: t.int(), newAge: t.int() }),
-});
-```
+For the official Tailor Platform documentation, see [Resolver Guide](https://docs.tailor.tech/guides/resolver).
 
 ## Creating a Resolver
 

package/docs/services/tailordb-migration.md

@@ -419,13 +419,13 @@ A script with a single step runs like a `main` script: one job and one transacti
 Because steps commit separately, a failure does not undo the steps that already completed:
 
 - If the first step fails before any other step has completed, the migration fails like a `main` script: the pre-migration schema changes are rolled back.
-- If a step fails after another step has completed, `tailor deploy` stops and leaves the migration **in progress**. The pre-migration schema stays in place, the checkpoint is not advanced, and the namespace's tables stay in maintenance mode, as while the migration runs: GraphQL create, update, and delete operations, bulk upsert, and record events remain disabled, while `read` keeps its setting. `tailor tailordb migration status` reports the migration as in progress.
+- If a step fails after another step has completed, `tailor deploy` stops and leaves the migration **in progress**. The pre-migration schema stays in place and the checkpoint is not advanced. With [maintenance mode](#maintenance-mode) on, the namespace's tables stay in it, as while the migration runs: GraphQL create, update, and delete operations, bulk upsert, and record events remain disabled, while `read` keeps its setting. `tailor tailordb migration status` reports the migration as in progress.
 - If `tailor deploy` cannot confirm whether the steps started, for example because the connection dropped while starting them, the migration also stays in progress. Run `tailor deploy` again; it checks whether the steps ran before continuing.
 - Fix the failing step and run `tailor deploy` again. The deploy resumes the migration: completed steps do not run again, and the failed step and the steps after it run with the updated script. A completed step is treated like an applied migration — editing it afterwards does not run it again.
 - If the steps changed since the earlier run, or that run is no longer available, every step runs again from the beginning. See [Editing steps of a migration in progress](#editing-steps-of-a-migration-in-progress).
 - If every step completed but the post-migration schema changes fail (for example, a field the migration makes required still has empty values), the migration also stays in progress with its pre-migration schema, and the next deploy retries those schema changes without running the steps again.
 - To run a completed step again (because it had a bug, or to fix rows the post-migration schema changes reject), change the steps: rename that step and update the `dependsOn` lists that name it, or add a step that fixes the rows. Every step then runs again from the beginning, so this relies on every step being safe to run again; to keep the other completed steps from running again, skip them as described below.
-- While a migration is in progress, `migration set`, `migration sync`, and `migration rebaseline` refuse to run, and `migration test` refuses to use that workspace as its source. Finish the migration with `tailor deploy` first. The one exception is `migration set <N>` with the in-progress migration's own number: it marks that migration as completed and clears its in-progress record. Use it only when the migration's schema changes are already applied, for example after the deploy reported that the checkpoint write could not be confirmed.
+- While a migration is in progress, `migration set`, `migration sync`, and `migration rebaseline` refuse to run, and `migration test` refuses to use that workspace as its source. Finish the migration with `tailor deploy` first, or settle it with `migration resolve` (see [Settling a migration that stays in progress](#settling-a-migration-that-stays-in-progress)). The one exception is `migration set <N>` with the in-progress migration's own number: it marks that migration as completed and clears its in-progress record. Use it only when the migration's schema changes are already applied, for example after the deploy reported that the checkpoint write could not be confirmed.
 
 #### Editing steps of a migration in progress
 
@@ -448,7 +448,16 @@ tailor deploy --migration-skip-steps main-db/backfillUser,main-db/backfillInvoic
 - The option applies to the migration an earlier deploy left in progress. Deploy fails before changing anything when an entry names a step that did not succeed, a step the migration does not define, a namespace without a migration in progress, or a namespace that no deployed config defines. It also fails when the earlier run's step results cannot be read, because then it cannot confirm which steps succeeded; deploy again to retry.
 - It takes effect for the deploy you pass it to. If that run fails, the next `tailor deploy` resumes it as usual, and the skipped steps stay completed without passing the option again.
 
-Write every step so that running it again is safe: besides the cases above, a step can run a second time when a deploy is interrupted right after it commits. Use `where` clauses that skip rows a step already migrated, as in the example. Maintenance mode blocks GraphQL writes, not the writes your resolvers, executors, or workflows make through Kysely; rows they write while a migration is in progress are not seen by steps that already completed, so stop such writers until the migration finishes or write steps that tolerate them.
+Write every step so that running it again is safe: besides the cases above, a step can run a second time when a deploy is interrupted right after it commits. Use `where` clauses that skip rows a step already migrated, as in the example. Rows written while a migration is in progress are not seen by steps that already completed. [Maintenance mode](#maintenance-mode) blocks GraphQL writes but not the writes your resolvers, executors, or workflows make through Kysely, and without it GraphQL clients can write too, so stop such writers until the migration finishes or write steps that tolerate them.
+
+### Settling a migration that stays in progress
+
+When you do not want to resume the migration with another deploy — you abandoned it, or you repaired the data by hand — settle it with `tailor tailordb migration resolve`. Pass exactly one of two options:
+
+- `--rollback` sends the schema of the migration before the failed one, clears the in-progress record, and leaves the checkpoint where it was. The next `tailor deploy` runs the failed migration again from its first step, so every step must be safe to run again. Data changes made by steps that already completed are not undone, and tables that exist only in the failed migration's schema are deleted with their data.
+- `--complete` sends the schema of the failed migration itself, clears the in-progress record, and moves the checkpoint to that migration, without running its `migrate.ts` again. Repair the data first, for example with `tailor query`, and make sure no record lacks a value for a field the migration makes required: the update is rejected while such a record exists, and the migration stays in progress.
+
+Tables that the failed migration removes are deleted with their data under `--complete`. The command refuses to run while an execution of the failed migration is still running; wait for it to finish first. Both options take the namespace's tables out of [maintenance mode](#maintenance-mode) and remove the temporary resources of the failed run. The command shows what it will change and asks for confirmation (`--yes` skips it). As with `migration sync`, the local migration history must reproduce the current table definitions, so settle the migration before you change the tables. If sending the schema stops partway, run the same command again.
 
 ## Supported Schema Changes
 
@@ -677,6 +686,65 @@ For each pending migration:
 
 This split is what allows existing rows to be backfilled before the database starts rejecting nulls, and what lets `migrate.ts` traverse foreign-key fields that the same migration removes.
 
+### Maintenance mode
+
+`maintenanceMode` in `defineConfig` decides whether `tailor deploy` puts each namespace with pending migrations into maintenance mode while it applies them. A table in maintenance mode accepts no GraphQL `create`, `update`, `delete`, or bulk upsert operation and publishes no record events; its `read` setting is left as it is.
+
+| Value                   | Maintenance mode                                                                                                                                                                       |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `false`                 | None. Nothing is restricted while migrations run.                                                                                                                                      |
+| `"migration"` (default) | From before the first pending migration runs until the last one completes.                                                                                                             |
+| `"deploy"`              | From before the first pending migration runs until the deploy has applied every other change, including resolvers, executors, and workflows, and has removed the resources it deletes. |
+
+A deploy without pending migrations never enters maintenance mode. When `maintenanceMode` is unset, it behaves as `"migration"`, preserving the existing deployment behavior. The value is read from the config like any other, so it can differ per environment (see [Multi-Environment Configuration](../multi-environment.md#varying-config-values-per-environment)):
+
+```typescript
+export default defineConfig({
+  name: "my-app",
+  maintenanceMode: process.env.APP_ENV === "production" ? "deploy" : false,
+});
+```
+
+**Without maintenance mode**, the SDK does not guarantee what requests that run during the migration observe. A table can still have its [pre-migration shape](#per-migration-phases), with new required fields optional and removed fields present; a client can write rows after `migrate.ts` has already read the table; and the records `migrate.ts` writes publish events to the executors of the previous deploy, which were written for the old shape. Use it only where clients and executors tolerate that.
+
+**`"migration"` vs `"deploy"`**: the new resolvers and executors are deployed after the migrations. With `"migration"`, the migrated tables accept requests and publish events again while the resolvers and executors of the previous deploy are still in place. `"deploy"` keeps the tables in maintenance mode until they are replaced.
+
+Maintenance mode restricts GraphQL writes and record events only. Resolvers, executors (including scheduled and webhook triggers), and workflows keep running, and the writes they make through Kysely are not blocked.
+
+**When a deploy stops early:**
+
+- If a migration fails, the tables leave maintenance mode before the error is reported: they return to the settings of the last checkpoint that completed. A migration that did not reach its checkpoint returns existing tables to their previous settings and keeps the tables it created in maintenance mode until a later deploy applies it. The settings are not restored if the checkpoint number or migration history changed concurrently, or if checkpoint ownership cannot be verified. A table left behind by a failed post-checkpoint deletion also stays in maintenance mode for manual recovery.
+- A [multi-step migration](#splitting-a-migration-into-steps) left in progress keeps its tables in maintenance mode until a deploy completes it.
+- With `"deploy"`, if a later part of the deploy fails, the tables leave maintenance mode before the error is reported. When the deploy ends maintenance mode, it leaves the tables of a namespace unchanged if that namespace's checkpoint number or migration history changed concurrently, or if checkpoint ownership cannot be verified, and reports it.
+- If the deploy process is interrupted after a namespace's migrations completed but before maintenance mode ended, that namespace's tables stay in maintenance mode until a later `tailor deploy` releases them when it applies its TailorDB changes, before it replaces resolvers and executors. A namespace whose migrations had not all completed is not released this way: the next deploy resumes a multi-step migration left in progress, and otherwise reports remote schema drift (see [Failure Recovery](#failure-recovery)).
+
+#### Keeping maintenance mode short
+
+Maintenance mode lasts for the whole migration job, including the time the platform takes to start it, which can far exceed the time `migrate.ts` itself needs. Keep in `migrate.ts` only the work that must be done before the post-migration schema is applied, and move the rest into a workflow that you start after the deploy (for example with [`tailor workflow start`](../cli/workflow.md#workflow-start)).
+
+- **Must stay in `migrate.ts`**: anything the post-migration schema enforces or removes — filling a field that becomes required, resolving duplicates before a unique index, converting values for a field type change, and copying data out of a field or table that the migration renames or removes.
+- **Can move to a workflow**: work the post-migration schema does not depend on, such as filling an optional field, recomputing derived values, or cleaning up rows. Requests that run before the workflow finishes see the data in its unfixed state.
+
+### Time spent in maintenance mode
+
+When [maintenance mode](#maintenance-mode) is on, `tailor deploy` reports how long the migrating namespaces' tables were restricted, split into phases. With `"deploy"`, the window also includes the remaining deployment changes and ends when their restrictions are lifted. No maintenance report is emitted with `maintenanceMode: false`.
+
+| Phase              | Covers                                                                                   |
+| ------------------ | ---------------------------------------------------------------------------------------- |
+| `restrict`         | Putting the tables into maintenance mode                                                 |
+| `pre-migration`    | Pre-migration schema changes                                                             |
+| `job setup`        | Bundling `migrate.ts` and registering it as a job                                        |
+| `waiting to start` | Time when the platform has accepted the job but none of its code runs yet                |
+| `running`          | Time when the script runs                                                                |
+| `job cleanup`      | Collecting the script's logs and removing its job, unless its steps run as separate jobs |
+| `post-migration`   | Post-migration schema changes, the checkpoint update, and cleanup                        |
+| `remaining deploy` | With `"deploy"`, applying the remaining deployment changes while tables stay restricted  |
+| `restore`          | Taking the tables out of maintenance mode                                                |
+
+Phases that repeat across several migrations are added up. The report is printed only after the migrations succeed and the tables leave maintenance mode; when a migration fails, deploy reports the error instead (see [Failure Recovery](#failure-recovery)). When deploy resumes a migration that an earlier deploy left in progress, the tables were already in maintenance mode before it started, and the report covers only this deploy. A job can be reported as started on the platform well before its code runs, so deploy tells waiting from running by a line every job of a migration logs before your script: `[tailor-sdk] migration script started`. You may see that line in function execution logs; deploy leaves it out of the logs it prints. A script that exports [`steps`](#splitting-a-migration-into-steps) waits for each step's job to start, and that time counts as `waiting to start` too. Time when deploy cannot tell whether the script is running — because the run or a running job's logs could not be read, or because an older SDK version started the run and it never logs the line — is reported as `waiting to start or running` instead.
+
+Deploy checks the run every few seconds, so a boundary between `waiting to start` and `running` can be off by that much. With `--json`, the same breakdown is in `tailordbMaintenance` (see [Deploy JSON result](../cli/application.md#deploy)). Add `--verbose` to also print how long each phase took and every change in the job's status.
+
 ### Schema verification
 
 Before running migrations, `apply` performs two checks:
@@ -716,14 +784,14 @@ tailor deploy --no-schema-check
 ### Example output
 
 ```
-ℹ Found 2 pending migration(s) to execute.
-ℹ Executing 2 pending migration(s)...
-ℹ Using machine user: admin-machine-user for namespace 'tailordb'
+ℹ Executing 1 data migration(s)...
 
-✔ Migration tailordb/0002 completed successfully
-✔ Migration tailordb/0003 completed successfully
+ℹ Using machine user: admin-machine-user for namespace 'tailordb'
+10:42:31 AM ℹ Migration tailordb/0002 started running after waiting 15m02s for its job to start.
+✓ Migration tailordb/0002 completed successfully (waiting to start 15m02s, running 1m41s)
 
-✔ All migrations completed successfully.
+✔ All data migrations completed successfully.
+ℹ Tables of namespace tailordb were in maintenance mode for 16m56s (restrict 1.2s, pre-migration 3.4s, job setup 2.1s, waiting to start 15m02s, running 1m41s, job cleanup 0.8s, post-migration 4.0s, restore 1.1s).
 ✔ Successfully applied changes.
 ```
 
@@ -825,7 +893,7 @@ A script that exports `steps` follows different rules once one of its steps has
 
 The rollback is best-effort per table; if reverting a table fails, a warning is logged and the original migration error is still reported. The next deploy then stops with remote schema drift on that table. Run `tailor tailordb migration validate` to see which tables differ, return the namespace to its checkpoint with `tailor tailordb migration sync <N>`, where `<N>` is the checkpoint `tailor tailordb migration status` reports, and deploy again. `sync` deletes the tables and fields that are not in that migration's snapshot, together with any rows the failed migration wrote to them; the next deploy runs the failed migration again.
 
-If `tailor deploy` cannot tell whether a `main` script ran, for example because the connection dropped while it started or waited for the script, it does not roll anything back: the pre-migration schema changes stay, the namespace's tables stay in maintenance mode, and the deploy reports that it could not confirm the outcome. A later deploy refuses to run the migration while that run is still executing. Run `tailor workflow executions --workflow-name <name>` with the workflow name the error reports until the execution has finished or none is listed. If it succeeded, run `tailor tailordb migration sync <N>` with the migration's own number; otherwise run `tailor tailordb migration sync <N-1>`. Then deploy again. Do not deploy before running sync, even with `--no-schema-check` to skip the drift check: the deploy may run the `main` script again even if the execution succeeded.
+If `tailor deploy` cannot tell whether a `main` script ran, for example because the connection dropped while it started or waited for the script, it does not roll anything back: the pre-migration schema changes stay, the namespace's tables stay in [maintenance mode](#maintenance-mode) if it is on, and the deploy reports that it could not confirm the outcome. A later deploy refuses to run the migration while that run is still executing. Run `tailor workflow executions --workflow-name <name>` with the workflow name the error reports until the execution has finished or none is listed. If it succeeded, run `tailor tailordb migration sync <N>` with the migration's own number; otherwise run `tailor tailordb migration sync <N-1>`. Then deploy again. Do not deploy before running sync, even with `--no-schema-check` to skip the drift check: the deploy may run the `main` script again even if the execution succeeded.
 
 `migration sync` refuses to run while a migration is in progress. When a steps migration's post-migration schema changes fail and the deploy cannot return its tables to the pre-migration schema, it logs a warning, and the next deploy stops with remote schema drift on those tables. Run `tailor tailordb migration validate` from a checkout of the deployed migration history. If the only issue it reports is that drift, run `tailor deploy --no-schema-check`: the deploy applies the pre-migration schema again, skips the completed steps unless the steps changed, and retries the post-migration schema changes. `--no-schema-check` skips the schema checks of every namespace, so do not use it while `validate` reports any other issue.
 
@@ -917,8 +985,8 @@ When `migrate.ts` already exists (the usual case for breaking changes, where `mi
 // migrations/0005/migrate.test.ts
 import { createKyselyMock } from "@tailor-platform/sdk/vitest";
 import { describe, expect, test } from "vitest";
-import type { Database } from "./db";
 import { main } from "./migrate";
+import type { Database } from "./db";
 
 describe("0005 add required email", () => {
   test("backfills null emails", async () => {
@@ -954,9 +1022,9 @@ The generated `db.pglite.ts` exports the `CREATE TABLE` script for the same sche
 import { PGlite } from "@electric-sql/pglite";
 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";
+import type { Database } from "./db";
 
 const pglite = new PGlite();
 const db = createKyselyPGlite<Unmigrated<Database>>(pglite);

package/docs/services/tailordb.md

@@ -431,16 +431,29 @@ db.string().vector();
 
 ```typescript
 db.int().serial({
-  start: 0,
+  start: 1,
   maxValue: 100,
 });
 
 db.string().serial({
-  start: 0,
+  start: 1,
   format: "CUST_%d",
 });
 ```
 
+A serial field cannot be used inside a `db.object()` field.
+
+> **Preview:** The `gapless` option is a preview feature. Its behavior and configuration may change before general availability.
+
+Set `gapless: true` to number records without gaps. A number is used only by a create that commits, so a create that fails leaves no hole. Numbered creates of the table run one at a time, so use it only when contiguous numbering is required. See the [TailorDB Serial documentation](https://docs.tailor.tech/guides/tailordb/fields#serial) for what the gapless guarantee covers.
+
+```typescript
+db.int().serial({
+  start: 1,
+  gapless: true,
+});
+```
+
 ### Common Fields
 
 ```typescript
@@ -522,7 +535,7 @@ db.table("User", {
 - When not specified, `deploy` sets it from the executors taking part in the same run: `true` while one of them uses this table with `recordCreatedTrigger`, `recordUpdatedTrigger`, or `recordDeletedTrigger`, and `false` once none does. Removing the last such trigger turns publishing back off on the next `deploy`
 - When explicitly set to `false` while an executor taking part in the same run uses this table, `deploy` fails
 - An executor declared with `disabled: true` never runs, so it does not count as using the table
-- While a `deploy` applies pending migrations, every table in the migrating namespace is restricted: the GraphQL create, update, and delete operations and bulk upsert are disabled, and the table's `read` setting is not switched off for the migration (a table the migration creates uses its configured setting), so nothing writes an intermediate schema and readable tables are not shut down. Record event publishing is also switched off so a migration script's writes do not reach executors from the previous deploy. After success, the configured settings take effect. If a later migration fails, settings from the last confirmed checkpoint are restored; an uncommitted migration restores existing tables' prior settings and leaves its newly created tables restricted until a successful retry. A table that already refuses create, update, delete, and bulk upsert and publishes no record events is left as it is. Restoration is skipped if the checkpoint number or migration history changed concurrently, or if checkpoint ownership cannot be verified; the deploy then reports the namespace whose tables stay restricted and points to `tailor tailordb migration status --namespace <namespace>`. When a failed migration or a failed restoration leaves tables restricted, the deploy lists their names, and deploying again releases them once the migration completes. A table that a failed rollback could not delete or revert is the exception: the deploy also lists it, but the next deploy stops with remote schema drift until you delete or repair that table by hand. A table left behind by a failed post-checkpoint deletion also remains read-only for manual recovery, and the deploy does not list it by name
+- While a `deploy` applies pending migrations with [maintenance mode](./tailordb-migration.md#maintenance-mode) on, every table in the migrating namespace is restricted: the GraphQL create, update, and delete operations and bulk upsert are disabled, and the table's `read` setting is not switched off for the migration (a table the migration creates uses its configured setting), so nothing writes an intermediate schema and readable tables are not shut down. Record event publishing is also switched off so a migration script's writes do not reach executors from the previous deploy. With `maintenanceMode: false`, these restrictions are not applied. After success, the configured settings take effect. If a later migration fails, settings from the last confirmed checkpoint are restored; an uncommitted migration restores existing tables' prior settings and leaves its newly created tables restricted until a successful retry. A table that already refuses create, update, delete, and bulk upsert and publishes no record events is left as it is. Restoration is skipped if the checkpoint number or migration history changed concurrently, or if checkpoint ownership cannot be verified; the deploy then reports the namespace whose tables stay restricted and points to `tailor tailordb migration status --namespace <namespace>`. When a failed migration or a failed restoration leaves tables restricted, the deploy lists their names, and deploying again releases them once the migration completes. A table that a failed rollback could not delete or revert is the exception: the deploy also lists it, but the next deploy stops with remote schema drift until you delete or repair that table by hand. A table left behind by a failed post-checkpoint deletion also remains read-only for manual recovery, and the deploy does not list it by name
 
 **Use cases:**
 
@@ -567,7 +580,7 @@ db.table("User", {
 
 Control which GraphQL operations (`create`, `update`, `delete`, `read`) are exposed for a table. All operations are enabled by default.
 
-While a `deploy` applies pending migrations, the GraphQL `create`, `update`, and `delete` operations and bulk upsert are switched off across the migrating namespace, so nothing writes an intermediate schema. The `read` operation is not switched off: it keeps the setting the table has when the restrictions begin. A table that a migration touches then follows that migration's schema from its first phase on, so a migration that changes `read` changes it before its script runs; a table no migration touches keeps its setting. A table the migration creates uses its configured `read` setting from the start. After success, the configured operations take effect. If a later migration fails, operations from the last confirmed checkpoint are restored; an uncommitted migration restores existing tables' prior operations and leaves its newly created tables restricted until a successful retry. A table that already refuses create, update, delete, and bulk upsert and publishes no record events is left as it is. Restoration is skipped if the checkpoint number or migration history changed concurrently; the deploy then reports the namespace whose tables stay restricted, and deploying again releases them once the migration completes.
+While a `deploy` applies pending migrations with [maintenance mode](./tailordb-migration.md#maintenance-mode) on, the GraphQL `create`, `update`, and `delete` operations and bulk upsert are switched off across the migrating namespace, so nothing writes an intermediate schema. The `read` operation is not switched off: it keeps the setting the table has when the restrictions begin. With or without maintenance mode, a table that a migration touches follows that migration's schema from its first phase on, so a migration that changes `read` changes it before its script runs; a table no migration touches keeps its setting. A table the migration creates uses its configured `read` setting from the start. After success, the configured operations take effect. If a later migration fails while maintenance mode is on, operations from the last confirmed checkpoint are restored; an uncommitted migration restores existing tables' prior operations and leaves its newly created tables restricted until a successful retry. A table that already refuses create, update, delete, and bulk upsert and publishes no record events is left as it is. Restoration is skipped if the checkpoint number or migration history changed concurrently; the deploy then reports the namespace whose tables stay restricted, and deploying again releases them once the migration completes.
 
 ```typescript
 db.table("Order", {

package/docs/services/workflow.md

@@ -488,9 +488,9 @@ Pass the runtime key through the `executionPolicyKey` option on `job.start()`. F
 
 ```typescript
 import { createWorkflowJob } from "@tailor-platform/sdk";
-import { executionPolicies } from "./policies";
-import { sendNotification } from "./jobs/send-notification";
 import { fetchTenant } from "./jobs/fetch-tenant";
+import { sendNotification } from "./jobs/send-notification";
+import { executionPolicies } from "./policies";
 
 export const mainJob = createWorkflowJob({
   name: "main-job",