Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions content/stack/cipherstash/cli/impl.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -121,10 +121,10 @@ No plan at `.cipherstash/plan.md`. Run `stash plan` first, or pass --continue-wi
When the agent handoff completes, `stash impl` prints:

```
Implementation handoff complete. Run `stash db status` to verify state.
Implementation handoff complete. Run `stash eql status` to verify state.
```

Run `stash db status` to check EQL installation and `stash encrypt status` for per-column migration state.
Run `stash eql status` to check EQL installation and `stash encrypt status` for per-column migration state.

## Next steps

Expand Down
8 changes: 4 additions & 4 deletions content/stack/cipherstash/cli/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ The setup lifecycle has three explicit save-points. Each command can be run stan

### Manual setup

If you prefer to configure things yourself rather than running `stash init`, you can scaffold the config file manually and run `stash db install` directly.
If you prefer to configure things yourself rather than running `stash init`, you can scaffold the config file manually and run `stash eql install` directly.

<Steps>
<Step>
Expand Down Expand Up @@ -95,7 +95,7 @@ If you prefer to configure things yourself rather than running `stash init`, you
### Install EQL

```bash
npx stash db install
npx stash eql install
```
</Step>
</Steps>
Expand Down Expand Up @@ -148,7 +148,7 @@ yarn dlx @cipherstash/wizard # yarn
Before running the wizard, your project should have:

- An authenticated CipherStash session (`npx stash auth login`)
- A `stash.config.ts` (run `npx stash init` or `npx stash db install` to scaffold one)
- A `stash.config.ts` (run `npx stash init` or `npx stash eql install` to scaffold one)
- A reachable database via `DATABASE_URL`

### What the wizard does
Expand All @@ -157,7 +157,7 @@ Before running the wizard, your project should have:
2. Runs health checks against the CipherStash gateway and your database.
3. Prompts you to pick the tables and columns to encrypt.
4. Sends a prompt to the Claude Agent SDK, which edits your schema and call sites to use `@cipherstash/stack`'s encryption APIs. The agent runs against a CipherStash-hosted LLM gateway. No Anthropic API key is required.
5. Runs post-agent steps: package install, `db install`, `db push`, and framework-specific migrations.
5. Runs post-agent steps: package install, `eql install`, `db push`, and framework-specific migrations.
6. Scans for remaining call sites that need `encryptModel`/`decryptModel` wiring and prints a summary. These locations are not edited automatically.
7. Offers to install integration-appropriate [agent skills](/stack/reference/agent-skills) into `./.claude/skills/`.

Expand Down
12 changes: 6 additions & 6 deletions content/stack/cipherstash/cli/init.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Init runs six steps with minimal prompts:
2. **Resolves the database**: Reads your `DATABASE_URL` and verifies a connection can be made. Detects your Postgres provider (Supabase from the URL host, or generic Postgres).
3. **Generates the encryption client file**: Auto-detects your integration (Drizzle from `drizzle.config.*` or `drizzle-orm`/`drizzle-kit` in `package.json`, Supabase from the `DATABASE_URL` host, or generic Postgres). Writes a placeholder client to `./src/encryption/index.ts` silently. If that file already exists, it prompts you to keep it or overwrite it.
4. **Installs dependencies**: Checks whether `@cipherstash/stack` and `stash` are already in `node_modules`. If both are present, skips silently. If either is missing, shows a single combined install prompt. Detects your package manager (npm, pnpm, yarn, bun) automatically.
5. **Installs EQL**: Runs the same logic as `stash db install`. Scaffolds `stash.config.ts` if missing, detects your provider, and installs the EQL extension into your database. You do not need to run `stash db install` separately after init.
5. **Installs EQL**: Runs the same logic as `stash eql install`. Scaffolds `stash.config.ts` if missing, detects your provider, and installs the EQL extension into your database. You do not need to run `stash eql install` separately after init.
6. **Gathers context**: Writes `.cipherstash/context.json` with the detected integration, package manager, schemas, environment keys, and available agents. This file is required by `stash plan` and `stash impl`.

Best case: 0 prompts (already authenticated, both packages installed, no existing client file, database reachable). Worst case: 2 prompts (region selection for first-time login, install confirmation for missing packages).
Expand Down Expand Up @@ -73,14 +73,14 @@ Answering yes launches `stash plan` immediately. Answering no (or running non-in
Next: run `stash plan` to draft your encryption plan.
```

## db install flags
## eql install flags

If you need to run EQL installation with specific flags (for example, writing a Supabase migration file), use `stash db install` directly after init:
If you need to run EQL installation with specific flags (for example, writing a Supabase migration file), use `stash eql install` directly after init:

```bash
npx stash db install --supabase --migration
npx stash db install --drizzle
npx stash db install --drizzle --supabase
npx stash eql install --supabase --migration
npx stash eql install --drizzle
npx stash eql install --drizzle --supabase
```

> **Good to know**: You can pass `--drizzle` and `--supabase` together. The CLI combines both behaviors: Supabase-compatible SQL output as a Drizzle migration.
Expand Down
36 changes: 19 additions & 17 deletions content/stack/cipherstash/cli/install.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,12 @@ description: Install or upgrade EQL extensions in Postgres with the stash CLI, c
Install the CipherStash EQL extensions into your database. Uses bundled SQL by default for offline, deterministic installs.

```bash
npx stash db install [options]
npx stash eql install [options]
```

`db install` scaffolds `stash.config.ts` if it is missing. The command:
`stash db install` is a deprecated alias for `stash eql install` — it still works, but prints a deprecation warning. Use `eql install` going forward.

`eql install` scaffolds `stash.config.ts` if it is missing. The command:

1. **Scaffolds `stash.config.ts`** with the database URL and client path (if the file does not already exist).
2. **Scaffolds the encryption client file** at the path referenced in `stash.config.ts` if the file does not exist. Uses the same auto-detected integration template as `init` (Drizzle, Supabase, or generic Postgres). Silent, no prompt.
Expand All @@ -37,36 +39,36 @@ After a successful install, the CLI prints a summary of what was installed. If y
Standard install:

```bash
npx stash db install
npx stash eql install
```

Dry run to preview changes:

```bash
npx stash db install --dry-run
npx stash eql install --dry-run
```

Fetch the latest EQL from GitHub:

```bash
npx stash db install --latest
npx stash eql install --latest
```

### Auto-detection

`db install` auto-detects two things before prompting you:
`eql install` auto-detects two things before prompting you:

- **Supabase**: If `DATABASE_URL` contains a `*.supabase.co`, `*.supabase.com`, or `*.pooler.supabase.com` host, the CLI uses the Supabase-compatible install automatically. You can still pass `--supabase` explicitly to override.
- **Drizzle**: If a `drizzle.config.*` file exists or `drizzle-orm`/`drizzle-kit` appears in `package.json`, the CLI generates a Drizzle migration automatically. You can still pass `--drizzle` explicitly.

### Automatic OPE fallback

On managed databases (Supabase, Neon, RDS), the connected role is often not a superuser. `db install` detects this and automatically uses the no-operator-family (OPE) install variant, logging a line to inform you. You do not need to pass `--exclude-operator-family` manually on these hosts.
On managed databases (Supabase, Neon, RDS), the connected role is often not a superuser. `eql install` detects this and automatically uses the no-operator-family (OPE) install variant, logging a line to inform you. You do not need to pass `--exclude-operator-family` manually on these hosts.

### Supabase install

```bash
npx stash db install --supabase
npx stash eql install --supabase
```

The `--supabase` flag uses the Supabase-specific SQL variant. It omits `CREATE OPERATOR FAMILY` and grants `USAGE`, table, routine, and sequence permissions on the `eql_v2` schema to `anon`, `authenticated`, and `service_role`.
Expand All @@ -83,13 +85,13 @@ The migration-file path writes EQL SQL into `supabase/migrations/00000000000000_

```bash
# Write EQL as a migration file
npx stash db install --supabase --migration
npx stash eql install --supabase --migration

# Push EQL directly to the database
npx stash db install --supabase --direct
npx stash eql install --supabase --direct

# Override the migrations directory
npx stash db install --supabase --migration --migrations-dir ./db/migrations
npx stash eql install --supabase --migration --migrations-dir ./db/migrations
```

<Callout type="info">
Expand All @@ -109,7 +111,7 @@ npx stash db install --supabase --migration --migrations-dir ./db/migrations
If you use Drizzle ORM and want EQL installation as part of your migration history, use `--drizzle`:

```bash
npx stash db install --drizzle
npx stash eql install --drizzle
npx drizzle-kit migrate
```

Expand All @@ -122,15 +124,15 @@ This process:
To customize the migration name and output directory:

```bash
npx stash db install --drizzle --name setup-eql --out ./migrations
npx stash eql install --drizzle --name setup-eql --out ./migrations
```

`drizzle-kit` must be installed. The `--out` value must match your Drizzle config.

You can combine `--drizzle` and `--supabase`:

```bash
npx stash db install --drizzle --supabase
npx stash eql install --drizzle --supabase
```

This generates a Supabase-compatible EQL migration file.
Expand All @@ -139,7 +141,7 @@ This generates a Supabase-compatible EQL migration file.

When you add `encryptedType` to a Drizzle column that already has data, `drizzle-kit generate` emits an `ALTER TABLE ... ALTER COLUMN ... SET DATA TYPE eql_v2_encrypted` statement. Postgres cannot cast existing data to `eql_v2_encrypted` implicitly, so this migration would fail.

`db install --drizzle` automatically rewrites those statements into a safe `ADD COLUMN / DROP COLUMN / RENAME COLUMN` sequence. The rewrite adds a comment in the migration to remind you to backfill the new column with `encryptModel` before dropping the old one. You are responsible for writing and running that backfill in your application code before applying the DROP step.
`eql install --drizzle` automatically rewrites those statements into a safe `ADD COLUMN / DROP COLUMN / RENAME COLUMN` sequence. The rewrite adds a comment in the migration to remind you to backfill the new column with `encryptModel` before dropping the old one. You are responsible for writing and running that backfill in your application code before applying the DROP step.

### Permission pre-checks

Expand All @@ -158,7 +160,7 @@ If the role is not a superuser, the CLI falls back automatically to the OPE (no-
Upgrade an existing EQL installation to the version bundled with the package, or to the latest version from GitHub.

```bash
npx stash db upgrade [options]
npx stash eql upgrade [options]
```

| Option | Description |
Expand All @@ -168,7 +170,7 @@ npx stash db upgrade [options]
| `--exclude-operator-family` | Skip operator family creation |
| `--latest` | Fetch the latest EQL from GitHub instead of using the bundled version |

The EQL install SQL is idempotent and safe to re-run. The CLI checks the current version, re-runs the install SQL, and reports the new version. If EQL is not installed, the CLI suggests running `npx stash db install` instead.
The EQL install SQL is idempotent and safe to re-run. The CLI checks the current version, re-runs the install SQL, and reports the new version. If EQL is not installed, the CLI suggests running `npx stash eql install` instead.

## Bundled EQL SQL

Expand Down
4 changes: 2 additions & 2 deletions content/stack/cipherstash/cli/push.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Push and status
description: Push your CipherStash encryption schema to PostgreSQL and use db status and test-connection to check EQL installation and database connectivity.
description: Push your CipherStash encryption schema to PostgreSQL and use eql status and test-connection to check EQL installation and database connectivity.
---

## push
Expand Down Expand Up @@ -48,7 +48,7 @@ The SDK uses developer-friendly type names, but EQL expects PostgreSQL-aligned t
Show the current state of EQL in your database.

```bash
npx stash db status
npx stash eql status
```

Reports:
Expand Down
4 changes: 2 additions & 2 deletions content/stack/cipherstash/cli/status.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Lifecycle
◯ Implementation waiting on plan

Deeper inspection
Database state: `stash db status`
Database state: `stash eql status`
Per-column state: `stash encrypt status`

Next: run `stash plan` to draft your encryption plan.
Expand All @@ -61,7 +61,7 @@ Next: run `stash plan` to draft your encryption plan.

| Command | What it shows |
|---|---|
| `stash db status` | EQL installation state, database permissions, active encrypt config |
| `stash eql status` | EQL installation state, database permissions, active encrypt config |
| `stash encrypt status` | Per-column migration state: phase, progress, and drift |

## When to use stash status
Expand Down
12 changes: 6 additions & 6 deletions content/stack/cipherstash/cli/troubleshooting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,14 @@ description: Fix common CipherStash CLI errors covering config files, database p

| Error | Cause | Fix |
|---|---|---|
| `Could not find stash.config.ts` | No config file in cwd or parent dirs | Run `npx stash init` (which runs `db install` automatically), or run `npx stash db install` directly, or create `stash.config.ts` manually |
| `Could not find stash.config.ts` | No config file in cwd or parent dirs | Run `npx stash init` (which runs `eql install` automatically), or run `npx stash eql install` directly, or create `stash.config.ts` manually |
| `databaseUrl is required` | Config missing `databaseUrl` | Add `databaseUrl` to config and check `.env` is loaded |
| `must be superuser to create an operator family` | Standard SQL requires superuser | The CLI falls back to OPE mode automatically on managed databases. Pass `--exclude-operator-family` if you see this on self-hosted Postgres. |
| `Insufficient database permissions` | Role lacks `CREATE` privileges | Connect as superuser or grant permissions |
| `EQL is already installed` | `eql_v2` schema exists | Use `--force` to reinstall |
| `Encrypt client file not found` | `push`/`validate` can't find the file at `config.client` | Set `client` in `stash.config.ts` to the correct path |
| `drizzle-kit generate failed` | drizzle-kit not installed or wrong output dir | Install `drizzle-kit` and set `--out` to match your Drizzle config |
| EQL missing after `supabase db reset` | EQL was installed via direct push, not as a migration | Re-run `db install --supabase --migration` to add EQL to `supabase/migrations/`. See [below](#supabase-db-reset). |
| EQL missing after `supabase db reset` | EQL was installed via direct push, not as a migration | Re-run `eql install --supabase --migration` to add EQL to `supabase/migrations/`. See [below](#supabase-db-reset). |

## Permission issues

Expand All @@ -23,7 +23,7 @@ The `install` command checks database permissions before running. On managed dat
If you still see permission errors:

1. Run `npx stash db test-connection` to verify your database URL is correct.
2. Run `npx stash db status` to check the current EQL state.
2. Run `npx stash eql status` to check the current EQL state.
3. Ensure the connected role has `CREATE` privileges on the database and `public` schema.
4. For the `pgcrypto` extension, the role needs `SUPERUSER` or extension owner privileges.

Expand Down Expand Up @@ -54,10 +54,10 @@ When adding `encryptedType` to a column that already has data, the CLI rewrites

### Fix for new installs

Re-run `db install` and choose the migration-file path:
Re-run `eql install` and choose the migration-file path:

```bash
npx stash db install --supabase --migration
npx stash eql install --supabase --migration
```

The CLI writes EQL SQL to `supabase/migrations/00000000000000_cipherstash_eql.sql`. The all-zero timestamp prefix ensures it runs before any user migrations that reference `eql_v2_encrypted`. After the file is created, `supabase db reset` will reinstall EQL automatically on every reset.
Expand All @@ -67,7 +67,7 @@ The CLI writes EQL SQL to `supabase/migrations/00000000000000_cipherstash_eql.sq
If you already ran a direct-push install and your live database is working, your existing install is not broken. To get a migration file going forward without disrupting the live database, run:

```bash
npx stash db install --supabase --migration --force
npx stash eql install --supabase --migration --force
```

The EQL SQL is idempotent. The `--force` flag regenerates the install even though EQL is already present. Your live install is unaffected. After this, `supabase db reset` reinstalls EQL from the migration file.
2 changes: 1 addition & 1 deletion content/stack/cipherstash/encryption/drizzle.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ The Drizzle integration is included in `@cipherstash/stack` and imports from `@c
Use the [CipherStash CLI](/stack/cipherstash/cli) to generate a Drizzle migration that installs the [EQL](/stack/reference/eql-guide) extension:

```bash
npx stash db install --drizzle
npx stash eql install --drizzle
npx drizzle-kit migrate
```

Expand Down
2 changes: 1 addition & 1 deletion content/stack/cipherstash/encryption/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ npx stash init # Interactive project setup (auth, EQL install, clien
npx stash plan # Draft a reviewable encryption plan
npx stash impl # Execute the plan with a coding agent
npx stash db validate # Check schema for misconfigurations
npx stash db status # Show EQL installation state
npx stash eql status # Show EQL installation state
```

<Cards>
Expand Down
2 changes: 1 addition & 1 deletion content/stack/cipherstash/encryption/prisma-next.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: Searchable field-level encryption for Postgres with Prisma Next, th

CipherStash provides first-class [Prisma Next](https://www.npmjs.com/package/@prisma-next/cli) integration through [`@cipherstash/prisma-next`](https://www.npmjs.com/package/@cipherstash/prisma-next). Declare encrypted columns directly in `schema.prisma` with `cipherstash.Encrypted*()` constructors, and use auto-encrypting query operators that make encrypted queries look like standard Prisma Next code.

The Prisma Next integration has a meaningfully shorter onboarding path than the [Drizzle](/stack/cipherstash/encryption/drizzle) or [Supabase](/stack/cipherstash/encryption/supabase) integrations because the framework's migration system absorbs the database-side install. **You do not run `stash db install` for the EQL bundle** — `prisma-next migration apply` installs the EQL extension in the same control-plane sweep that creates your application tables.
The Prisma Next integration has a meaningfully shorter onboarding path than the [Drizzle](/stack/cipherstash/encryption/drizzle) or [Supabase](/stack/cipherstash/encryption/supabase) integrations because the framework's migration system absorbs the database-side install. **You do not run `stash eql install` for the EQL bundle** — `prisma-next migration apply` installs the EQL extension in the same control-plane sweep that creates your application tables.

## Installation

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ The result: your data is encrypted at rest, in transit, and during query evaluat

1. Install [EQL](/stack/reference/eql-guide) in your PostgreSQL database using the [CipherStash CLI](/stack/cipherstash/cli):
```bash
npx stash db install
npx stash eql install
```
2. Define your encryption schema with the appropriate search indexes
3. Create PostgreSQL indexes on your encrypted columns. See [Setting up indexes](/stack/cipherstash/encryption/indexes) for the correct `CREATE INDEX` syntax for your deployment (self-hosted vs Supabase).
Expand Down
2 changes: 1 addition & 1 deletion content/stack/cipherstash/encryption/storing-data.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ The Encryption SDK works with any database that supports JSON or JSONB column ty
To enable searchable encryption in PostgreSQL, install [EQL](/stack/reference/eql-guide) using the [CipherStash CLI](/stack/cipherstash/cli) so you can use the `eql_v2_encrypted` data type. If you don't need searchable encryption, use `jsonb` instead (you can migrate to EQL later).

```bash
npx stash db install
npx stash eql install
```

<Callout type="info" title="Choosing the column type">
Expand Down
Loading