Bring Your Own Database
Store your agents, calls, and knowledge in your own PostgreSQL — full data sovereignty and EU data residency.
What is BYODB?
By default, all tenant data (agents, calls, knowledge, messages) is stored in CustomWeb Agents's managed Supabase PostgreSQL. BYODB lets you point the platform at your own PostgreSQL database instead, so your data never leaves infrastructure you control.
This matters for:
- EU data residency — data stays in an EU-hosted database you own.
- Enterprise security — your DBA audits every schema change; your backup policy governs retention.
- Data portability — export or query your data directly without going through any API.
Supported databases
Any standard PostgreSQL 14+ database over a standard connection URL is supported. Tested providers:
| Provider | How to get a connection URL | Notes |
|---|---|---|
| Supabase | Project Settings → Database → Connection string → URI tab (use the Session Pooler URL on port 5432) | Choose the session-mode pooler URL; transaction-mode pooler has connection-count limits that can interrupt long operations. |
| Neon | Dashboard → Project → Connection Details → Connection string | Enable the connection pooler (PgBouncer) for production. Disable it for the initial schema provision if you see "prepared statement already exists" errors. |
| Railway | Project → Postgres service → Variables tab → DATABASE_URL | Railway uses TLS by default; the URL includes sslmode=require automatically. |
| Render Postgres | Dashboard → your PostgreSQL instance → Info → Connections → External Database URL | Use the External URL (not Internal) unless you're also hosting the app on Render in the same VPC. |
| Any PostgreSQL | postgresql://user:password@host:5432/dbname | Must be reachable from the internet (or your hosting provider's IP ranges). Add sslmode=require for TLS. |
Connecting your database
- Go to Dashboard → Integrations. Find Custom Database (BYODB) in the Storage & Privacy section and click it.
- Read the data migration warning — existing data stays archived on CustomWeb's servers (see below).
- Paste your PostgreSQL connection URL into the URL field.
- Click Test connection to verify the platform can reach your database (runs a SELECT 1 probe — no writes).
- Once the test passes, click Connect & Provision. The platform will run the full schema DDL inside a PostgreSQL transaction, creating all required tables, indexes, and enum types. This takes a few seconds.
- Done. All new data (agents you create, calls that happen, documents you upload) will be written to your database.
What gets provisioned
On first connect, the platform runs a versioned DDL migration that creates the full operational schema in your database. The tables created include:
- Assistant, AssistantVersion — agent configs and version history
- Call, Message — call records and transcript messages
- KnowledgeBase, KnowledgeDocument, KnowledgeSource, KnowledgePortalUser — KB infrastructure
- Tool, WorkflowGraph, WorkflowNode, WorkflowEdge — tools and workflow definitions
- UsageEvent, Event — billing ledger and audit trail
- TestSuite, EvalRun, EvalCase — automated test infrastructure
A special table `_byodb_meta` is created to track which migration version has been applied. The platform uses this to apply incremental DDL updates automatically as the schema evolves — you never need to run migrations manually.
Data migration and the blank-slate rule
When you connect a custom database, existing data (agents, calls, knowledge) is NOT automatically migrated from the platform database to your database. That data stays archived on CustomWeb's servers.
Why: automated data migration across databases is a destructive, difficult-to-reverse operation. We don't do it automatically to protect you from data loss.
What this means in practice:
- You will see a "fresh" dashboard after connecting — no agents, no calls, no knowledge (they are still archived on the platform DB).
- New agents you create go into your database. Old ones stay on the platform DB and are accessible if you disconnect later.
- The Integrations panel shows the date BYODB was activated — agents created before vs after that date can be reconciled manually if needed.
Disconnecting
To revert to the platform database: Integrations → Custom Database → Disconnect. The platform stops writing to your database immediately. New data routes to the platform DB. Data already in your database is not deleted.
Platform setup (self-hosted / white-label operators)
If you operate CustomWeb Agents as a white-label platform, BYODB requires one env var to be set in your deployment:
| Variable | Value | Required |
|---|---|---|
| SETTINGS_ENCRYPTION_KEY | 32-byte hex string (64 hex chars) — generate with: openssl rand -hex 32 | Yes — without this, connection URLs cannot be encrypted and the connect endpoint will refuse requests. |
# Generate a fresh encryption key (run once, store the output): openssl rand -hex 32
Add it to your deployment environment (Vercel → Project Settings → Environment Variables, or your Render/Railway service's env section). It must be the same value across all deployments — changing it will make existing encrypted URLs unreadable.