Stash Deployment

Encrypting a column that already holds live data is a deployment problem, not a schema problem. The schema change is trivial; the danger is the window between "the database can hold ciphertext" and "the application reads ciphertext". Getting that window wrong loses data silently — rows written during the gap keep only plaintext, or keep only ciphertext nobody can decrypt, and nothing errors until a user reads the row.

This skill covers how to sequence that across deploys. For the API and the lifecycle model see stash-encryption; for the commands see stash-cli; for framework specifics see stash-drizzle / stash-supabase / stash-prisma.

Everything here describes EQL v3, the only authoring generation. The EQL v2 rollout commands were removed — stash encrypt cutover (the old v2 rename swap) now exits with an error on every project. A column that started under v2 finishes the same way as v3: complete the backfill, switch reads to the encrypted column by name, then stash encrypt drop. Legacy v2 payloads remain readable; stash-encryption covers that.

Runner note. stash init adds stash to the project as a dev dependency, so the bare stash <command> form used below runs through whichever package manager the project uses. Before init has run, prefix with your package manager's one-shot runner (bunx, pnpm dlx, yarn dlx, npx). The same substitution applies to the prisma-next and @prisma/cli invocations in the Prisma section.

When to Use This Skill

• Planning the PR / deploy sequence for encrypting an existing column
• Shipping an encryption rollout to staging or production
• Running a backfill against a hosted (not local) database
• Getting CS_* credentials into a build pipeline and a deployed runtime
• Deploying a CipherStash app to Prisma Postgres / Prisma Compute
• Diagnosing a failed deploy, a failed migration, or rows that won't decrypt

The rule

A column goes from plaintext to encrypted across at least four deploys, never one.

Not a style preference. There is no atomic operation that replaces a populated plaintext column with an encrypted one, because ciphertext can only be produced by the application, client-side, holding your keys. No UPDATE, no migration, no database-side function can encrypt an existing row. So the plaintext column must stay authoritative — and stay populated — until every row has a ciphertext twin and the deployed code is reading it.

Any plan that adds an encrypted column and drops the plaintext one in the same deploy loses data. Any plan that backfills before dual-writes are live in production loses the rows written during the backfill. The ladder below is the minimum safe shape.

The deployment ladder

 DEPLOY 1     rollout           + encrypted twin (nullable) + dual-write
                                everywhere; reads unchanged

   ⛔ GATE 1  dual-writes live in the environment that owns the database

 out-of-band  BACKFILL          encrypt historical rows, against the prod DB
 migration    indexes           eql_v3.* extractor indexes + ANALYZE, shipped
                                through the integration's migration flow

 DEPLOY 2     read cutover      reads → encrypted column, decrypt at the
                                boundary; dual-writes stay

   ⛔ GATE 2  soak — real traffic reads decrypt correctly

 DEPLOY 3     stop dual-write   writes → encrypted column only; plaintext
                                column stays, now unwritten

   ⛔ GATE 3  Deploy 3 live everywhere; coverage re-checked

 DEPLOY 4     drop plaintext    drop the plaintext column (+ NOT NULL on
                                encrypted), guarded by an apply-time
                                coverage re-check

Four deploys, with the backfill and index build between the first two. Each gate is a human decision, not a pipeline step.

Deploy 0 — prepare the environment (optional, do it early)

Before any application change, make sure the target environment can encrypt at all:

• EQL installed in the target database. Direct install is stash eql install; Drizzle generates an install migration instead (apply it with drizzle-kit migrate), and Prisma Next installs it through the migration graph (prisma-next migrate).
• CS_* credentials present in the environment, minted with stash env --name <app>-<env>. On most platforms these are needed at build time as well as run time (see Credentials).
• Bundling handled. The default @cipherstash/stack entry wraps a native FFI module — exclude it from bundling (serverExternalPackages, esbuild external, …). On runtimes that cannot load native modules at all (Cloudflare Workers, Deno, Supabase Edge Functions), bundle @cipherstash/stack/wasm-inline instead — it inlines the WASM build, no externalization needed. See stash-edge.

Shipping this as its own deploy is cheap and de-risks Deploy 1: a credential or bundling problem surfaces while nothing depends on encryption yet.

Deploy 1 — rollout: encrypted twin + dual-write

One PR, one deploy. It changes what the app writes, never what it reads.

"Dual-write" means every path. Not the ORM model, not the main service — every site. A CSV importer, an admin action, a background job, a webhook handler, a raw SQL fixup script: one missed branch means rows created in production after this deploy have no ciphertext, and the backfill (which ran earlier) will not catch them. Grep for every writer of the plaintext column before merging.

After this deploy the system is in a safe steady state and can stay there indefinitely. New rows are fully encrypted; old rows are not; reads work either way.

⛔ Gate 1 — dual-writes must be live in the environment that owns the database

Not on a laptop. Not in CI. In the deployed environment whose traffic writes to the database you are about to backfill. Verify with stash status before continuing; stash impl will refuse a cutover plan whose columns have no dual_writing event in cs_migrations, and stash encrypt backfill prompts for the same confirmation (--confirm-dual-writes-deployed in CI).

Out-of-band — backfill

Not a deploy. A one-off job run against the production database, encrypting the historical rows that predate Deploy 1.

stash encrypt backfill --table users --column email

Paginated by primary key, one transactional UPDATE per chunk plus a checkpoint, SIGINT-safe, idempotent on re-run. Concurrent production writes are safe because dual-writes are live — that is the entire reason for Gate 1.

Two hard requirements:

• Encrypt under the same keyset the deployed app uses. The credentials do not have to be identical — any client bound to that keyset works; a mere grant is not enough, because encrypt always lands under the client's bound keyset — but the ciphertext must land under the keyset the app resolves. Nothing fails at write time; what breaks at read time depends on grants: with no grant the app cannot decrypt those rows, and if the app is granted the stray keyset it decrypts them fine while its encrypted searches silently miss them (the routing asymmetry stash-zerokms documents). The trap: CS_* env vars beat the local ~/.cipherstash profile, so a backfill that silently authenticates as your laptop profile can resolve a different keyset. Exporting the app's own CS_* vars for the run is the simplest way to guarantee a match. Keysets and grants: stash-zerokms; credential resolution order: stash-auth.
• Verify coverage before moving on. Count rows where the plaintext column is non-null and the encrypted column is null. It must be zero.

Then build the eql_v3.* extractor indexes for every capability you query and ANALYZE — after backfill, before the read switch. One bulk build instead of per-row index maintenance during the backfill, and the switched reads engage an index from the first query. Ship the DDL through whatever migration flow owns the schema — a Drizzle or Supabase migration, an index migration in the Prisma Next graph (never out-of-band there — see stash-prisma), or your SQL migration tool. Never ad-hoc against production. Recipes in stash-indexing.

Deploy 2 — read cutover

Reads move to the encrypted column; writes still go to both.

There is no rename and no CLI step here — this deploy is application code only. (There is no cutover command: stash encrypt cutover was the EQL v2 rename swap and has been removed — running it exits with an error pointing at this manual path.)

Keeping dual-writes through this deploy is what makes it reversible: if reads misbehave, Deploy 2 reverts to plaintext reads and every row is still correct in both columns.

⛔ Gate 2 — soak

Let real traffic read the encrypted column. Confirm results are correct — not just non-empty: check ordering, range filters, and free-text matches against known rows. Re-check coverage (still zero plaintext-only rows; new writes are covered by dual-writes). Only then ship Deploy 3.

Deploy 3 — stop writing the plaintext column

Remove the dual-write logic: writes now target only the encrypted column. The plaintext column stays in place, unwritten. If the original column is NOT NULL, this deploy's migration must relax that (DROP NOT NULL) — otherwise inserts fail the moment dual-writes stop.

This is the deploy that ends easy reversibility: rows written after it have no plaintext value, so reverting reads back to the plaintext column is no longer safe. That is why Gate 2's soak comes first.

Do not fold the drop into this deploy. Most pipelines apply migrations before the new code is live — a drop migration riding alongside the dual-write removal executes while the previous deploy's still-dual-writing code is serving traffic, and every insert and update fails against a column that no longer exists.

⛔ Gate 3 — nothing writes plaintext anymore

Deploy 3 must be live on every instance (rolling deploys included), and coverage re-checked one last time: zero rows with plaintext and no ciphertext. Only then is the drop safe.

Deploy 4 — drop the plaintext column

Irreversible — every earlier stage can be walked back (see Rollback per stage). This deploy is migration-only: the application stopped touching the column in Deploy 3.

Generate the drop rather than hand-writing it where the tooling can: stash encrypt drop --table users --column email emits a migration whose SQL takes ACCESS EXCLUSIVE on the table, re-counts uncovered rows at apply time, and raises instead of dropping if any remain. That re-check matters: the coverage you verified at planning time is not the coverage at apply time.

If you author the drop by hand (some integrations require it — see the Prisma Next notes below), reproduce that property: the drop and the coverage check must be in one transaction, so a failed check rolls the drop back.

Why the boundaries are non-negotiable

Rollback per stage

Credentials in a deployed environment

Mint per-environment credentials from your device session:

stash env --name my-app-prod            # prints the four CS_* vars to stdout
stash env --name my-app-prod --json     # NDJSON, no prompts, for CI

CS_WORKSPACE_CRN=crn:<region>:<workspace-id>
CS_CLIENT_ID=<uuid>
CS_CLIENT_KEY=<hex>
CS_CLIENT_ACCESS_KEY=CSAK…

Rules that bite in practice:

• The access key is shown exactly once. Pipe it straight into the platform's secret store; it cannot be re-revealed. Stdout is pipe-clean (progress goes to stderr), so stash env --name x | <secret-store-cli> is safe.
• Mint one credential per environment. Preview and production are separate --name values. Each run mints a new credential; duplicate names are rejected.
• Credentials are often needed at BUILD time, not just run time. If the encryption client is constructed at module load — and it usually is, in a db.ts-style singleton — then any build step that imports that module authenticates during the build. Static-generation and page-data collection do exactly this. A build without CS_* fails with Not authenticated. Local builds mask it, because the ~/.cipherstash device profile authenticates silently.
• Keyset consistency governs decryptability and searchability. Everything that writes ciphertext for an environment — the app, the backfill, one-off scripts — must resolve to the same keyset; the credentials themselves may differ, provided each client is bound to that keyset (a grant alone routes only decrypt). Mismatches are silent at write time. The model lives in stash-zerokms.
• Never print or log the values. They are secrets, and so is any one-time database connection URL used alongside them.

Running one-off jobs against a hosted database

Backfills, coverage checks, and manual migrations need a plain Postgres connection to the exact database the deployed app uses. Two things go wrong here:

1. Targeting the wrong database. Preview/branch environments usually have their own databases with confusingly similar names. Confirm the identity of the target before running anything — a job that succeeds against the wrong database looks like success and fixes nothing.
2. Targeting the right database with the wrong keys. See the keyset note above.

Run these as explicit, reviewed steps. Do not wire them into the deploy pipeline: they are one-shot, they need production credentials, and they must not re-run on every deploy.

Prisma Postgres and Prisma Compute

Observed on Prisma Compute (Public Beta) and Prisma Next Early Access, July 2026. Both move quickly — verify against the current CLI help before relying on a detail.

Prisma Next is contract-first: contract.prisma is emitted to contract.json / contract.d.ts, and the database is advanced along a migration graph. CipherStash integrates through @cipherstash/stack-prisma, which contributes its own contract space, so EQL installs as part of your migration graph — prisma-next migrate (the top-level apply verb) installs the bundle alongside your schema. Never stash eql install, which refuses on a Prisma Next project.

The deploy pipeline runs db init

A Compute deploy (including every GitHub push-to-deploy build) runs prisma-next contract emit followed by prisma-next db init against the target branch database. Three consequences:

1. Additive migrations deploy themselves. The EQL bundle install and the encrypted-twin columns of Deploy 1 apply during the build. No manual migrate step.

2. Destructive migrations cannot ship through a deploy. db init is additive-only by policy. A merge carrying dropColumn or setNotNull fails the build:

PN-CLI-4020: Migration planning failed
Operation "Set NOT NULL on "transaction"."amountEncrypted"" requires class
"destructive", but policy allows only: additive

This happens even when the PR contains a hand-authored migration covering exactly that change — db init reconciles live schema against the contract and does not consult the authored edge. The failed build itself causes no outage: the previous deployment keeps serving and the database is untouched.

The sequence that works for the drop (Deploy 4) — run it only after the Deploy 3 merge (dual-write removal) is live, so nothing still writes the plaintext column when it disappears:

# 1. Mint a one-time connection URL for the PRODUCTION database
npx @prisma/cli database list                       # identify the target — see below
npx @prisma/cli database connection create <db_id>

# 2. Apply the authored migration out-of-band, BEFORE merging the Deploy 4 PR
npx prisma-next db update --db "<one-time-url>"

# 3. Remove the connection, then merge. `db init` sees no drift and passes.
npx @prisma/cli database connection remove <connection_id>

Applying before the merge is strictly better than merging and recovering: the build passes on the first try. The deploy ordering is what makes the window safe — with dual-writes already removed in Deploy 3, nothing running touches the column between the out-of-band apply and the merge going live.

3. Preview branches get their own databases. Each preview branch database is created fresh, so db init reconciles it from empty and never walks the destructive migration history. A destructive PR's preview deploy can pass while its production deploy fails. Do not read a green preview as proof the production deploy will work.

Identifying the production database

database list shows one database per branch, and branch metadata is not a reliable discriminator — entries can all report the same branch scope. Production is identified by its name (the primary/production database), not by list order and not by the entry named after your git branch. Confirm with npx @prisma/cli database show <database> --json before minting a connection.

Getting this wrong is quiet: applying a migration to a preview database succeeds, and the production deploy then fails with the identical error it failed with before.

One merge deploys the whole merge

Merging to the default branch deploys everything in that merge. So the ladder above maps to separate PRs merged in sequence, with the out-of-band steps run between merges:

Never combine two stages into one PR to save a review cycle. The gates are the safety mechanism.

CS_* and NEXT_PUBLIC_* are build-time inputs

Set both before the build, for both roles (preview and production):

• NEXT_PUBLIC_* values are inlined at build time.
• CS_* are needed at build time because cipherstashFromStack authenticates while constructing the client, and db.ts constructs it at module load.

Next.js on Compute

• Exclude the native packages from bundling: serverExternalPackages: ["@cipherstash/stack", "@cipherstash/protect-ffi", "@cipherstash/auth"].
• Do not depend on middleware for authorization. The bundled server has been observed not executing Next.js middleware on some deploys. Keep authorization checks in the page / server-action / route handler itself.
• Scale-to-zero: the first request after idle may cold-start or 404. Retry before diagnosing.

Authoring the Deploy 4 migration on Prisma Next

prisma-next migration plan scaffolds dropColumn + setNotNull from the contract diff, but the resulting migration has no coverage guard — and the usual remedy (a dataTransform that fills the nulls in SQL) is impossible here, because ciphertext cannot be produced in SQL and the plaintext source is dropped by the same migration.

Until the extension pack ships a factory for this, add the guard by hand: a dataTransform whose check selects rows still missing ciphertext acts as a pre/post condition around a no-op run, so a single uncovered row rolls back the whole transaction — the drop included. Order the operations so each setNotNull is preceded by its gate. Re-run the migration file after editing so its migration.json is re-emitted and the hashes match.

Logs

app logs is runtime output; build logs <build-id> is CI output. Different identifiers — the id in a check run's console URL is not the build id; the build id is printed in the check output itself.

Troubleshooting

Related skills

• stash-encryption — the encryption API and the canonical rollout/cutover model
• stash-cli — stash status / plan / impl / encrypt * / env command surface
• stash-indexing — the eql_v3.* extractor indexes to build between backfill and cutover
• stash-zerokms — the keyset/grant model that governs who can decrypt what
• stash-auth — auth strategies, the CS_* variables, and credential resolution order
• stash-edge — edge/serverless runtimes and the @cipherstash/stack/wasm-inline entry
• stash-prisma / stash-drizzle / stash-supabase — integration specifics