Stash Deployment

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