Custom Database (BYODB)

Overview

Sendable stores each session's WhatsApp data — messages, contacts, groups, events, annotations, chat notes and tags — in its own central database. With BYODB (Bring Your Own Database) you can point a session at your own PostgreSQL instance. All WhatsApp content for that session is then read and written in your database instead of Sendable's.

This is useful when you need:

• Data residency — keep message content in a database you control, in a region of your choice
• Direct access — query or join your WhatsApp data with your own application data using your existing BI tools
• Compliance — full control over retention, encryption at rest and access to message content

What moves to your database

When a custom database is connected, these tables are created (via automated migrations) and used in your PostgreSQL instance:

Operational data stays with Sendable and is not stored in your database:

• Account, billing, API keys and session configuration
• Connection logs (waConnLogs) and connection failure logs
• Audiences and audience contacts

Requirements

• PostgreSQL — only postgres:// or postgresql:// connection URLs are supported (managed Postgres such as Supabase, Neon or RDS works).
• Network reachability — Sendable's servers must be able to reach your database host. If you self-host or use a private VPC, contact support to add your host to the allowlist.
• Permissions — the connecting user needs permission to create tables (CREATE on the schema), because Sendable runs its migrations on connect.

Connecting a database

1. Open the session's Settings page.
2. In the Custom Database (BYODB) card, paste your PostgreSQL connection URL and click Connect.
3. Sendable validates the URL, connects, creates the required tables and marks the session as using your database.

The connection URL is stored server-side but is never returned by the API or shown in the dashboard — the UI only displays the host and a status badge (Connected, Error or Unconfigured). Connect attempts are rate limited to protect against abuse.

Connection errors

If the database cannot be reached or the migrations fail, the connection is rejected with an error message and the session keeps using Sendable's database. The session shows an Error status until you fix the URL and connect again.

Existing data

When you connect a custom database to a session that already has data, Sendable does not move the data automatically. Existing content keeps working because reads fall back to the data already stored with Sendable — but to have everything in your database, the stored data must be backfilled once. Contact Sendable support to run the backfill for you (self-hosted deployments can run it directly):

# uses the session's configured connection URL
bun run backfill:session-data-to-custom-db <sessionId>

# or point at a specific database
bun run backfill:session-data-to-custom-db <sessionId> postgres://user:pass@host:5432/db

The backfill is idempotent — it copies the 13 content tables in dependency order with ON CONFLICT DO NOTHING, so re-running only copies what is missing.

Availability and failover

While a custom database is connected, all session content reads and writes go to your database. There is no silent fallback: if your database becomes unreachable, message/contact/group operations for that session will fail rather than quietly reading from Sendable's database. Restore your database (or disconnect the custom database from the settings page) to recover.

Disconnecting

Disconnecting returns the session to Sendable's storage. Your data stays in your database — Sendable never deletes or drops anything from it. Deleting a session deletes the session's rows from your database as well, but never drops your schema or affects other sessions' data.

Support

Sendable supports PostgreSQL for BYODB. If you need help with connection issues, host allowlisting or backfilling existing data, contact support.