@tailor-platform/sdk 2.37.0 → 2.38.0

package/docs/github-actions.md

@@ -173,8 +173,8 @@ and file blobs are not copied.
 
 Two setups are supported:
 
-- **Source is the plan/deploy workspace (default).** The job uses the same GitHub
-  Environment as the plan and deploy jobs, so it reads the same
+- **Source is the deploy workspace (default).** The job uses the same GitHub
+  Environment as the deploy job, so it reads the same
   `TAILOR_PLATFORM_WORKSPACE_ID` variable and machine-user secrets. Nothing
   extra to configure. If that workspace holds too little data to be a useful
   test, point the job at a workspace that does with the next setup.
@@ -204,6 +204,51 @@ the source workspace holds production data.
 Fork pull requests cannot read secrets, so the job is skipped for them.
 `--migration-test` is not available together with several `--dir` values.
 
+#### Running the plan job in its own environment
+
+The plan job runs on pull requests, and a pull request from a branch of the same
+repository can change the workflow it runs, so its code can read every secret
+and variable of the environment the plan job enters. When plan and deploy share
+one environment, that includes the deploy machine user. Pass
+`--split-plan-environment` on a branch target to run the plan job in an
+environment of its own:
+
+```bash
+tailor setup ci branch --name my-app-stg --split-plan-environment
+```
+
+The plan job then enters an environment named after the deploy environment with
+`-plan` appended (`my-app-stg-plan` here). The deploy job, and the migration test job unless you
+pass `--migration-test-environment`, stay in the deploy environment. Set these
+on the plan environment:
+
+- `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID` and
+  `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` of a machine user of its own. The
+  plan only reads, so a viewer role on the organization or folder that holds the
+  workspace is enough. Set them on the plan environment itself: otherwise the job
+  reads the ones set on the repository or organization, and
+  `tailor setup ci env --check` reports them as missing.
+- `TAILOR_PLATFORM_WORKSPACE_ID`, the same workspace the deploy environment
+  deploys to.
+
+Keep the deploy machine user off the plan environment. `tailor setup ci env`
+lists what each of the two environments needs.
+
+The flag alone does not keep the deploy credentials from a pull request, which
+can point the plan job back at the deploy environment. Under **Settings →
+Environments**, limit the deploy environment's **Deployment branches and tags**
+to the target branch, so that GitHub refuses a pull request job in it. With that
+limit in place:
+
+- The migration test job also runs on pull requests, so give it its own
+  environment with `--migration-test-environment` (see
+  [Choosing the source workspace](#choosing-the-source-workspace)).
+- The jobs of a preview target run on pull requests too, so pass
+  `setup ci preview` an `--environment` other than the limited one.
+
+`setup update` keeps the flag, but re-running `setup ci branch` does not carry it
+over: pass it each time, or the plan job moves back into the deploy environment.
+
 ### Tag target (recommended for production)
 
 The tag target fires when a tag matching `--tag-pattern` (default `v*`) is
@@ -259,6 +304,35 @@ that workspace when the pull request is closed:
 tailor setup ci preview --name my-app --region asia-northeast
 ```
 
+It writes two workflows. `tailor-my-app-preview.yml` deploys the pull request
+when it is opened or pushed to, and `tailor-my-app-preview-cleanup.yml` deletes
+the workspace when the pull request is closed. The cleanup workflow starts on
+`pull_request_target`, which GitHub also triggers for a pull request with merge
+conflicts, where workflows on `pull_request` do not start. A
+`pull_request_target` workflow can read the repository's secrets whoever opened
+the pull request, so GitHub runs it from the default branch: the workflow file
+and the code it checks out are the default branch's, never the pull request's.
+Therefore:
+
+- The cleanup workflow runs only once it is on the default branch, and it
+  installs dependencies and runs `tailor` from the default branch's checkout.
+  If the preview target deploys pull requests into another branch
+  (`--branch`), commit the cleanup workflow, the lockfile, and the app's
+  `tailor.config.ts` to the default branch too.
+- If the target's GitHub Environment restricts which branches can deploy,
+  allow the default branch: GitHub checks the cleanup job against it, and the
+  deploy job against the pull request's merge ref.
+
+When `tailor setup update` regenerates a preview workflow generated before the
+cleanup workflow existed, it moves the `tailor-preview-cleanup` job into the
+cleanup workflow, together with the steps and settings you added to it, and
+copies the top-level `env`, `defaults`, and `concurrency` of the preview
+workflow into the cleanup workflow. Your steps then run from the default branch
+as described above. A job of yours in the preview workflow that runs when the
+pull request is closed no longer runs, because that workflow no longer starts
+then; move it into the cleanup workflow. `setup` warns about each job of yours
+in the preview workflow whose `if` contains an `== 'closed'` comparison.
+
 Fork pull requests are skipped. Every other pull request gets a preview, draft
 pull requests included. `--require` narrows that to one of:
 
@@ -349,7 +423,9 @@ environment before the first deploy.
 
 Because the variable is scoped to a GitHub Environment, both the `plan` and
 `deploy` jobs declare `environment:` so the value resolves. When you omit
-`--environment`, the environment name defaults to the workspace name.
+`--environment`, the environment name defaults to the workspace name. With
+`--split-plan-environment`, set the variable on the plan environment as well (see
+[Running the plan job in its own environment](#running-the-plan-job-in-its-own-environment)).
 
 1. Provision the workspace (once per environment) and obtain its id. For now
    this is a manual step:
@@ -374,8 +450,9 @@ provisioned yet instead of running a dry-run.
 
 If the target environment has required reviewers, that approval gate applies to
 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.)
+read the variable, unless a branch target runs `plan` in its own environment with
+`--split-plan-environment`. (A token-based read that lets `plan` run without
+entering the environment is planned.)
 
 ## Package manager
 
@@ -437,9 +514,9 @@ Everything else is yours, and re-running `setup` keeps it:
   (such as `playwright install`) _after_ it. A job of your own can depend on a
   managed job with `needs: tailor-deploy`.
 - **Your own top-level keys**, such as a workflow-level `env:` or `defaults:`.
-- **The top-level `concurrency:` of a preview workflow.** The SDK writes a
-  default, and re-running `setup` keeps your edits to it. If you delete it,
-  re-running `setup` adds the default back.
+- **The top-level `concurrency:` of the preview and cleanup workflows.** The
+  SDK writes a default, and re-running `setup` keeps your edits to it. If you
+  delete it, re-running `setup` adds the default back.
 - **Runtime settings of managed jobs:** `runs-on`, `timeout-minutes`,
   `container`, and `env`. If every managed job that re-running `setup` keeps
   uses the same `runs-on` you set, such as self-hosted runners, a managed job
@@ -481,9 +558,9 @@ A job that runs `tailor` against the workspace needs the machine-user
 (the `--environment` value, or the workspace name when omitted) as above. A job
 that only uses `app-url`, such as end-to-end tests, does not.
 
-The job is skipped whenever `tailor-preview-deploy` is skipped: when a pull
-request is closed, for fork pull requests, for draft pull requests with
-`--require ready`, and for unlabeled ones with `--require label`.
+The job is skipped whenever `tailor-preview-deploy` is skipped: for fork pull
+requests, for draft pull requests with `--require ready`, and for unlabeled
+ones with `--require 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,
@@ -496,13 +573,32 @@ 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
-may redeploy or delete. Events on a pull request that stays closed, such as a
-label added after merging, do not cancel anything. A job with `if: always()`
-still runs when its run is cancelled, and the new run waits for it to finish;
-use `if: ${{ !cancelled() }}` instead so it stops with the run.
+A preview workspace last deployed before `ttl` was added to its workflow records
+no expiry, so this sweep never deletes it. To find such leftovers, list the
+preview workspaces created more than 7 days ago:
+
+```bash
+tailor workspace prune --name 'my-app-pr-[0-9]+' --older-than 7d \
+  --folder-id <folder id> --limit 0 --dry-run
+```
+
+Pass `--organization-root <organization id>` instead of `--folder-id` when
+`TAILOR_PLATFORM_FOLDER_ID` is unset. The list can include the previews of pull
+requests that are still open: keep each of them with
+`--exclude my-app-pr-<number>`, then run the command again without `--dry-run`.
+
+Each new preview workflow run for a pull request, such as after a push, cancels
+the run still in progress for it, including your jobs, so they do not keep
+running against a workspace that the new run may redeploy. Closing the pull
+request cancels it too, because the cleanup workflow runs in the same
+concurrency group. If you change the group in one of the two workflows, change
+it in the other, and build it only from values that are the same in both, such
+as `github.event.pull_request.number`: `github.ref`, `github.workflow`, and
+`github.event_name` differ between them, and `github.ref` is the default branch
+for every pull request in the cleanup workflow. Events on a pull request that
+stays closed, such as a label added after merging, do not cancel anything. A job with `if: always()` still
+runs when its run is cancelled, and the new run waits for it to finish; use
+`if: ${{ !cancelled() }}` instead so it stops with the run.
 
 Likewise, the `tailor-deploy` job of a branch or tag workflow exposes the
 deployed workspace as the outputs `workspace-id` and `app-url` to a job with
@@ -528,7 +624,9 @@ job back. To start over from a clean template, delete the file and re-run
 When a template update removes a managed job that contains steps of yours, or
 a job of yours `needs` a removed job, `setup` stops and names them. Move those
 steps into a job of your own (or update the `needs`) and re-run. `--force` drops
-steps left inside a removed job.
+steps left inside a removed job. The `tailor-preview-cleanup` job, which moved
+into its own workflow, keeps your steps instead (see
+[Preview target](#preview-target-per-pull-request-workspace)).
 
 `setup check` reports a job or step of yours whose `id` starts with `tailor-`,
 and re-running `setup` stops on it, naming the id. Rename it; `--force` does
@@ -562,7 +660,6 @@ tailor-preview-result:
   name: tailor-preview-result (my-app)
   needs:
     - tailor-preview-deploy
-    - tailor-preview-cleanup
     - seed
     - e2e
 ```
@@ -660,7 +757,13 @@ keeps them alongside that environment's `TAILOR_PLATFORM_WORKSPACE_ID`
 variable. You can also set the client secret as a repository-level secret and the
 client ID as a repository-level variable if every target shares one machine user,
 but then any workflow on any branch can read them, so the environment's
-protection rules no longer guard your deploys.
+protection rules no longer guard your deploys, and `tailor setup ci env --check`
+warns about the client secret (see
+[Checking what is registered](#checking-what-is-registered)). To share one machine
+user and keep that protection, set the same client secret on each environment
+instead. The plan environment of `--split-plan-environment` is the exception: give
+it a machine user of its own (see
+[Running the plan job in its own environment](#running-the-plan-job-in-its-own-environment)).
 
 ### Setting secrets and variables
 
@@ -704,6 +807,16 @@ The autofix workflow uses no GitHub Environment, so its two entries are set on
 the repository; the output lists them under the repository instead of an
 environment.
 
+A branch target generated with `--split-plan-environment` reads from two
+environments. The plan environment needs its own
+`TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID` and
+`TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET`, for which a viewer role is enough,
+and `TAILOR_PLATFORM_WORKSPACE_ID`; of the optional entries, only the plan job's
+`TAILOR_PLATFORM_FAIL_ON_DRIFT` and `SEED_USER_PASSWORD` apply to it. A manual dry
+run reads `SEED_USER_PASSWORD` from there, and pull requests can read it too, like
+everything on that environment. The deploy environment needs the rest, without
+`TAILOR_PLATFORM_FAIL_ON_DRIFT`.
+
 See [Account management](https://docs.tailor.tech/administration/account-management)
 for how organizations, folders, workspaces, and machine users relate.
 
@@ -735,13 +848,29 @@ to manage those settings in Terraform instead.
 environment and for the repository entries of the autofix workflow, 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.
+the `gh` commands that set the missing entries, with where each value comes
+from, and that move the client secret onto its environment (see below). 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.
+- `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` set on the repository or the
+  organization is reported with ⚠, even when the environment also sets it: any
+  workflow on any branch can read it there, so the environment's protection rules
+  do not guard it. The check still passes. The printed commands set it on the
+  environment, with the value you set on the repository or organization, and list
+  a commented-out `gh secret delete` for the repository copy: run it once every
+  environment and workflow that reads that secret has its own. An organization
+  owner has to stop sharing an organization secret with the repository. The
+  warning stops once the client secret is set only on the environments; when
+  every target shares one machine user, set the same client secret on each of
+  them.
+- On the plan environment of `--split-plan-environment`, the machine user's
+  client ID and client secret count only when set on that environment, since
+  the plan job would otherwise sign in as the machine user set on the repository
+  or organization.
 - 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
@@ -773,7 +902,10 @@ environment-scoped secrets there.
 
 Required reviewers gate the `plan` job as well, because `plan` must enter the
 environment to read `TAILOR_PLATFORM_WORKSPACE_ID`. (A token-based read that
-lets `plan` run without entering the environment is planned.)
+lets `plan` run without entering the environment is planned.) On a branch target,
+`--split-plan-environment` moves `plan` into an environment of its own, whose
+settings then apply to it instead (see
+[Running the plan job in its own environment](#running-the-plan-job-in-its-own-environment)).
 
 ## Manual runs and dry-run
 
@@ -808,7 +940,11 @@ can deploy, configure **Deployment branches and tags** on the target's GitHub
 Environment and keep the machine-user secrets on that environment. Because the
 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.
+rejected too. On a branch target, `--split-plan-environment` moves the plan job,
+dry runs included, into an environment of its own instead, so the deploy
+environment can allow the target branch alone once the migration test job, if
+any, has its own environment as well (see
+[Running the plan job in its own environment](#running-the-plan-job-in-its-own-environment)).
 
 ## Seeding the workspace after deploy
 

package/docs/services/tailordb/index.md

@@ -226,7 +226,9 @@ const user = db.table("User", {
 });
 ```
 
-A relation can also be set on a field inside `db.object()`. The inner field gets the foreign key constraint only: no index, no unique constraint, and no forward or backward relationship, as with `type: "keyOnly"`.
+A `keyOnly` relation does not make the field unique; add `.unique()` to the field to make it unique.
+
+A relation can also be set on a field inside `db.object()`, where it adds only the foreign key constraint to the inner field, and `.unique()` and `.index()` set on that field work as described in [Index / Unique](#index--unique).
 
 ```typescript
 const order = db.table("Order", {
@@ -477,6 +479,8 @@ db.string().serial({
 });
 ```
 
+`format` holds exactly one of `%d` (decimal), `%o` (octal), `%x` (lowercase hexadecimal), or `%X` (uppercase hexadecimal), optionally with a width: `%5d` pads with spaces and `%05d` with zeros, to at least 5 characters. Write a literal `%` as `%%`. The format is at most 32 characters.
+
 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.
@@ -571,7 +575,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 with [maintenance mode](./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
+- While a `deploy` applies pending migrations with [maintenance mode](./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 also listed: when it still has the migration's pre-migration schema, deploying again runs the migration again; otherwise 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, and the deploy does not list it by name; the next deploy deletes it
 
 **Use cases:**