Programmatic API

Import the stash package programmatically to install EQL, load and validate stash.config.ts, and build custom CipherStash tooling or CI scripts.

Import stash directly for custom tooling or CI scripts.

EQLInstaller

import { EQLInstaller, loadStashConfig } from 'stash'

const config = await loadStashConfig()

const installer = new EQLInstaller({
  databaseUrl: config.databaseUrl,
})

const permissions = await installer.checkPermissions()
if (!permissions.ok) {
  console.error('Missing permissions:', permissions.missing)
  process.exit(1)
}

if (await installer.isInstalled()) {
  console.log('EQL is already installed')
} else {
  await installer.install()
}

Methods

Method	Returns	Description
`checkPermissions()`	`Promise<PermissionCheckResult>`	Check if the database role has required permissions
`isInstalled()`	`Promise<boolean>`	Check if the `eql_v2` schema exists
`getInstalledVersion()`	`Promise<string \| null>`	Get the installed EQL version (or `null`)
`install(options?)`	`Promise<void>`	Execute the EQL install SQL in a transaction

Install options

await installer.install({
  excludeOperatorFamily: true, // Skip CREATE OPERATOR FAMILY
  supabase: true,              // Supabase mode (implies excludeOperatorFamily + grants roles)
  latest: true,                // Fetch latest from GitHub instead of bundled
})

PermissionCheckResult

interface PermissionCheckResult {
  ok: boolean
  missing: string[]  // Human-readable descriptions of missing permissions
}

loadBundledEqlSql

Load the bundled EQL install SQL as a string for custom install workflows:

import { loadBundledEqlSql } from 'stash'

const sql = loadBundledEqlSql()                                // standard
const sql = loadBundledEqlSql({ supabase: true })              // supabase variant
const sql = loadBundledEqlSql({ excludeOperatorFamily: true }) // no operator family

downloadEqlSql

Download the latest EQL install SQL from GitHub:

import { downloadEqlSql } from 'stash'

const sql = await downloadEqlSql()       // standard
const sql = await downloadEqlSql(true)   // no operator family variant

defineConfig

Type-safe identity function for stash.config.ts. Provides autocompletion and type checking without runtime overhead:

import { defineConfig } from 'stash'

export default defineConfig({
  databaseUrl: process.env.DATABASE_URL!,
})

loadStashConfig

Finds and loads the nearest stash.config.ts, validates it with Zod, applies defaults, and returns the typed config:

import { loadStashConfig } from 'stash'

const config = await loadStashConfig()
// config.databaseUrl — guaranteed to be a non-empty string
// config.client — path to encryption client (default: './src/encryption/index.ts')

Exits with a helpful error if the config file is not found or fails validation.

Programmatic API

On this page