SQLite Encryption in Production: Key Management, Migration, and Real-World Use Cases

This is Part 3 of a three-part series on SQLite encryption. Part 1 covers the SQLite encryption options and how AEAD page-level encryption works. Part 2 covers Turso's two encryption models, working code, and benchmark numbers.

A developer spends a week building a well-architected encrypted database. Strong cipher. Properly generated 256-bit key. AEAD authentication on every page. The encryption is correct. Then the key ends up in a .env file that gets committed to a public GitHub repository. Or it shows up in plaintext in a Sentry exception log because the connection string includes it as a query parameter. Or it's hardcoded in a Docker image that gets pushed to a shared registry.

The encryption is technically perfect and operationally worthless.

This is the gap most encryption tutorials leave open. They show you how to generate a key and create an encrypted database, and then they stop. The hard part of encryption in production is not the cipher. It's the discipline around the key, the migration plan, the compliance story, and a clear understanding of what encryption actually protects.

#Key Management That Won't Get You Fired

#Generating keys

Use a cryptographically secure random source. Nothing else.

For Turso Database (local/edge), keys are hex-encoded:

openssl rand -hex 32    # 256-bit key
openssl rand -hex 16    # 128-bit key

For Turso Cloud, keys are base64-encoded:

openssl rand -base64 32  # 256-bit key
openssl rand -base64 16  # 128-bit key

In application code:

# Python
import secrets
key_hex = secrets.token_hex(32)    # 256-bit, hex (local)

// Node.js
const crypto = require("crypto");
const keyHex = crypto.randomBytes(32).toString("hex");      // local
const keyBase64 = crypto.randomBytes(32).toString("base64"); // cloud

The hex vs. base64 distinction between Turso Database and Turso Cloud is a real gotcha. If you generate a hex key and pass it to Turso Cloud (or vice versa), you'll get an error that doesn't immediately explain what went wrong. Local uses hex. Cloud uses base64. Tattoo it on your forearm if that helps.

Do not use Math.random(), Date.now(), UUIDs, or any deterministic source for key generation. These are not cryptographically secure. A key generated from Math.random() can be reproduced by anyone who knows the seed state, which defeats the entire purpose of encryption.

#Storing keys

The right places:

Dedicated secret managers: HashiCorp Vault, AWS KMS, Azure Key Vault, GCP Secret Manager. These tools exist specifically for this problem. They handle access controls, audit logging, and rotation workflows.
Platform keystores (for mobile): iOS Keychain, Android Keystore. Hardware-backed where available.
.env files for local development only: Listed in .gitignore, never committed, never shared over Slack or email.

The wrong places:

Hardcoded in source code
Committed to version control (even private repos)
In plaintext configuration files deployed alongside the application
In application logs or error messages
In database records (encrypting the key with the key it protects is not a security strategy)
In Docker images or container environment definitions checked into a repository

If you're using environment variables in production, make sure they're injected at runtime from a secret manager, not baked into the deployment artifact.

#Rotating keys

Native rekeying is on the roadmap for both Turso Database and Turso Cloud but is not yet available. The current workaround is export and reimport:

# Export with old key
turso db shell my-db \
  --remote-encryption-key "${OLD_KEY}" .dump > export.sql

# Create new database with new key
turso db create my-db-rotated \
  --remote-encryption-key "${NEW_KEY}" \
  --remote-encryption-cipher aegis256

# Import into new database
turso db shell my-db-rotated \
  --remote-encryption-key "${NEW_KEY}" < export.sql

# Validate, then cut over application traffic

This requires downtime. Know that before you design your rotation schedule. For most workloads, the downtime window is small (minutes for databases under a few gigabytes), but it's not zero. Plan accordingly.

When to rotate:

On a schedule: Annually at minimum. Quarterly for high-sensitivity workloads.
After a suspected compromise: Immediately. Don't wait for confirmation.
After personnel changes: If someone who had key access leaves the team, rotate.
When compliance requires it: Some frameworks specify rotation frequency. Check yours.

#Multi-tenant key management

For SaaS applications with per-customer encryption, the pattern is:

Generate a unique key per tenant at onboarding.
Store the tenant-to-key mapping in your secret manager. Not in the database. Not in a config file.
Retrieve the correct key at runtime based on the authenticated tenant context.
Document which tenant maps to which database and key for disaster recovery purposes.

This architecture means a single key compromise affects exactly one tenant. You can rotate individual tenant keys independently. And the mapping between tenants and keys lives in infrastructure designed for secret storage, not in your application's data layer.

#Migration Paths

#From SQLCipher

Reasons to consider it: you're hitting the v3/v4 migration problem (different encryption parameters across major versions, databases that can't be opened after an upgrade), you want modern ciphers like AEGIS, you need cloud BYOK, or you're starting a new project and want to avoid version lock-in.

The migration is a decrypt-then-re-encrypt cycle:

# 1. Decrypt and export from SQLCipher
sqlcipher encrypted.db "PRAGMA key='YOUR_SQLCIPHER_KEY';" \
  ".output export.sql" ".dump"

# 2. Generate a new key
openssl rand -hex 32 > new_key.txt

# 3. Create encrypted Turso Database (local)
tursodb --experimental-encryption \
  "file:migrated.db?cipher=aegis256&hexkey=$(cat new_key.txt)" < export.sql

(The .output step matters: PRAGMA key prints ok on success, and if you redirect stdout to the dump file instead, that ok lands at the top of your SQL and breaks the import.)

For Turso Cloud:

# Generate a base64 key for cloud
export NEW_KEY=$(openssl rand -base64 32)

# Create encrypted cloud database
turso db create migrated-db \
  --remote-encryption-key "${NEW_KEY}" \
  --remote-encryption-cipher aegis256

# Import
turso db shell migrated-db \
  --remote-encryption-key "${NEW_KEY}" < export.sql

Test on a copy. Never run the migration against your production database directly. Keep the original SQLCipher database intact until you've fully validated the migration on production traffic.

#From unencrypted SQLite

The simpler case. Same pattern, fewer steps:

# Export
sqlite3 plaintext.db .dump > export.sql

# Create encrypted database (local)
tursodb --experimental-encryption \
  "file:encrypted.db?cipher=aegis256&hexkey=YOUR_HEX_KEY" < export.sql

# Or create encrypted database (cloud)
turso db create encrypted-db \
  --remote-encryption-key "YOUR_BASE64_KEY" \
  --remote-encryption-cipher aegis256

turso db shell encrypted-db \
  --remote-encryption-key "YOUR_BASE64_KEY" < export.sql

#From SEE

SEE databases use the standard SQLite file format when decrypted, so once you've decrypted with your SEE key active, the migration is identical to the unencrypted SQLite path. Export with your SEE CLI, then import into an encrypted Turso database.

One thing to factor into your testing: SEE is proprietary. You can't audit the decryption implementation without a license. Verify the exported data thoroughly before trusting it as your migration source.

#Migration checklist

Before cutting over production traffic:

Keep the original database intact. Don't delete or modify it until the migration is fully validated in production.
Validate schema completeness. All tables, indexes, triggers, and views should be present in the new database. Compare counts.
Run your full application test suite against the encrypted database. Not a subset. The full suite.
Benchmark your specific query patterns with encryption enabled. The published overhead numbers (0.5% to 2.8% on mixed workloads) are a good baseline, but your workload is your workload.
Confirm key management end-to-end. The key is in your secret manager, your application retrieves it at runtime, connections work, and you've tested what happens when the key is wrong or missing.

#Compliance Documentation

#SOC2

We are SOC2 Type II certified. All Turso Cloud databases are encrypted at the volume level as part of that certification. BYOK is an additional layer on top: the customer generates and controls the encryption key, and Turso never stores it.

For your SOC2 audit, document:

Key generation procedure (algorithm, entropy source, who generates)
Key storage location (which secret manager, access controls)
Key rotation schedule and evidence of execution
Access controls on key retrieval (who can access, audit trail)
Incident response procedure for suspected key compromise

The combination of Turso's SOC2 Type II infrastructure and customer-controlled BYOK keys gives you a layered story: the provider meets SOC2 standards, and the customer retains cryptographic control over their data.

#HIPAA

The HIPAA Security Rule requires encryption of Protected Health Information (PHI) at rest. AEAD encryption satisfies this requirement, and the authentication component (the auth tag on every page) also provides integrity verification, which HIPAA requires separately.

Use AES-256-GCM for HIPAA workloads. Auditors know it. It's NIST-approved. AEGIS is a strong cipher with excellent performance properties, and it's in active IRTF review at the RFC Editor, but it is not yet a finalized standard and is not NIST-approved. Explaining AEGIS to a HIPAA auditor adds friction with no benefit. AES-256-GCM checks every box without a conversation.

With Turso Cloud BYOK, the covered entity controls the encryption keys. Turso operates as a business associate that never has access to PHI encryption keys. The key exists in Turso's infrastructure only in memory during query processing. This separation simplifies your Business Associate Agreement: include provisions covering Turso's SOC2 certification, the BYOK architecture, and the fact that the business associate never stores or has access to PHI encryption keys.

#PCI-DSS

PCI-DSS requires NIST-approved encryption algorithms for cardholder data at rest. Same recommendation: use AES-256-GCM.

Document the full key management chain for your auditor:

Who generates encryption keys
Where keys are stored (secret manager, not source control)
Who has access to keys (named roles, not "the team")
How rotation is handled (current process and schedule)
Incident response procedure if a key is compromised

BYOK means the payment processor or fintech platform retains control of cardholder data encryption keys. Turso never has access to the plaintext.

#What auditors actually want to see

Across SOC2, HIPAA, and PCI-DSS, the documentation requirements converge on the same set of artifacts:

A written key management policy
Evidence of secure key storage (screenshots or configuration showing a secret manager, not keys in source control)
A rotation schedule with evidence of execution (logs showing rotation happened when it was supposed to)
Access controls on key retrieval (who can pull keys, and audit logs proving it)
An incident response procedure for key compromise (what happens, who gets notified, what's the timeline)

Build these artifacts before the audit, not during it.

#Real-World Use Cases

#AI agents managing personal data

AI agent architectures typically deploy fleets of agents, each handling private user data. Per-user encrypted databases give you cryptographic isolation: if one user's data is compromised, it's isolated from every other user's data by a different encryption key.

import { connect } from "@tursodatabase/database";

async function initializeAgent(userId: string, vault: SecretManager) {
  const hexkey = await vault.getSecret(`encryption-key-${userId}`);

  return connect(`agent-${userId}.db`, {
    encryption: {
      cipher: "aegis256",
      hexkey,
    },
  });
}

The key comes from a vault lookup at runtime, not from an environment variable or config file. Each user's agent gets its own encrypted database in Turso Cloud. The encrypted database syncs to local embedded replicas for offline-capable agents. If the agent running for User A is compromised, User B's data is encrypted with a completely different key.

#Fintech (PCI-DSS, SOC2)

Use aes256gcm explicitly. BYOK means the payment processor never has access to cardholder data encryption keys. Turso never sees the plaintext.

turso db create payments-db \
  --remote-encryption-key "${PAYMENT_KEY}" \
  --remote-encryption-cipher aes256gcm

For auditors: we are SOC2 Type II certified, the customer controls the encryption key via BYOK, the key is never stored on our infrastructure, and AES-256-GCM is a NIST-approved cipher.

#Healthcare (HIPAA)

Same cipher recommendation: aes256gcm. The covered entity controls the keys. Turso as a business associate never sees PHI. AEAD provides both encryption (confidentiality) and integrity verification (the auth tag detects tampering), satisfying two HIPAA Security Rule requirements with one mechanism.

import { connect } from "@tursodatabase/database";

const patientDB = await connect("patient-records.db", {
  encryption: {
    cipher: "aes256gcm",
    hexkey: process.env.PHI_ENCRYPTION_KEY,
  },
});

For your Business Associate Agreement with Turso: include provisions covering the BYOK architecture, the fact that encryption keys are never stored by the business associate, and Turso's SOC2 Type II certification.

#Mobile and edge

On a mobile device or edge node, encryption at rest protects data if the physical device is lost, stolen, or forensically analyzed. The overhead needs to be low enough that users don't notice it.

Turso Database encryption with AEGIS on ARM processors with AES extensions adds minimal overhead. The published benchmarks show 0.2% to 5.5% read overhead and around 13% write overhead with AEGIS-256. On modern iPhones and current Android flagships, that's negligible in practice.

For older devices without hardware AES support, two options: use aegis128l (faster than aegis256, lower overhead) or, if you're syncing with Turso Cloud, use chacha20poly1305 on the cloud side. ChaCha20-Poly1305 is designed to perform well in pure software without AES-NI instructions.

The offline-first pattern: an encrypted local Turso Database syncs to Turso Cloud when connectivity returns. Encryption is maintained end-to-end. The data is encrypted at rest on the device and encrypted at rest in the cloud, with TLS protecting it in transit between the two.

#What Encryption Does and Doesn't Protect

#What it covers

Data at rest on disk. Someone who copies the database file gets ciphertext. Without the key, it's random bytes.
Filesystem-level access. A process that can read the file but doesn't have the key gets nothing useful.
Backup exposure. Encrypted backups remain encrypted. A leaked backup doesn't leak plaintext.
Forensic analysis of storage media. Disk imaging, SSD recovery, decommissioned hardware. The data on the physical media is ciphertext.
Data tampering. AEAD authentication means tampered data fails decryption explicitly. You get an error, not silent corruption.

#What it doesn't cover

SQL injection. If an attacker can run queries against your application, they're querying with the key already loaded. Encryption at rest doesn't help here. Parameterized queries do.
Runtime memory inspection. The key is in memory while the database is open. A process with sufficient access to your application's memory can extract it.
Compromised application code. If your application is compromised, the attacker has everything the application has, including the key.
Data in transit. Encryption at rest protects storage. Use TLS for network protection. These are separate concerns.
Access control. Encryption proves you have the key. It doesn't prove you're authorized. Authorization is a separate layer.

Encryption at rest protects against a specific threat model: unauthorized physical or filesystem access to storage media. A complete approach also includes parameterized queries, authentication and authorization, TLS for data in transit, secure key storage, and monitoring for anomalous access patterns.

#What's Coming Next

Several features are in active development:

Native rekeying for both Turso Database and Turso Cloud will enable key rotation without the export/import workaround. This eliminates the downtime requirement for rotation and makes compliance-mandated rotation schedules practical at scale. It's on the roadmap. Not yet available.

Encrypting existing unencrypted databases in place will remove the dump/import step when adding encryption to a database that was originally created without it.

Key derivation from passphrases (KDF-based workflows) will support applications where passphrase-based key derivation is more appropriate than managing raw keys directly.

ATTACH statement support for encrypted databases will allow attaching multiple encrypted databases to a single connection, each potentially with different keys.

As AEGIS reaches RFC finalization and gains broader adoption, compliance frameworks may follow. But don't wait on that for current compliance requirements. AES-256-GCM is the right choice today for regulated workloads, and it will remain a strong choice regardless of what happens with AEGIS standardization.

#Where This Series Started

Part 1 covers the SQLite encryption landscape: how page-level AEAD encryption works, and how SQLCipher, SEE, and newer alternatives compare. Start there if you're still evaluating your options.

Part 2 covers both encryption models end to end with working code, cipher selection guidance, and the benchmark numbers. Start there if you're ready to write code.

Resources