How Connections Work
Your application never connects to raw database servers. Every connection goes through the TenantsDB proxy, which reads the database name from your connection string and routes to the right backend.
How routing works
Your Application
Same host · Same credentials · Different database name
↓
TenantsDB Proxy
TLS encrypted · Routes by database name
↓
controlplane_workspace
→
Your backend — users, billing, config
myapp_workspace
→
Schema design — DDL tracked as blueprint
myapp__acme
→
Customer A — isolated data, CRUD only
myapp__globex
→
Customer B — isolated data, CRUD only
One credential, one proxy. The database name controls everything.
Your app connects to
pg.tenantsdb.com, mysql.tenantsdb.com, mongo.tenantsdb.com, or redis.tenantsdb.com. Same pattern for every database type. Three Connection Types
Every connection to TenantsDB falls into one of three categories. Same proxy, same credentials; the database name determines which type.
Control
Your App's Backend
Users, billing, config; everything that isn't per-tenant. Full DDL and DML access. No blueprints, no versioning.
controlplane_workspace
Workspace
Schema Design
Where you build and iterate on your schema. DDL changes are tracked as versioned blueprints and deployed to tenants.
myapp_workspace
Tenant
Customer Database
Isolated production database for one customer. Schema deployed from blueprint. CRUD only — DDL is blocked.
myapp__acme
| Type | DDL | DML | Blueprint | Who connects |
|---|---|---|---|---|
| Control | ✓ Full access | ✓ | None | Your application |
| Workspace | ✓ Tracked | ✓ | Versioned | You, during development |
| Tenant | ✗ Blocked | ✓ | Deployed | Your application, per customer |
Your application typically holds two connection pools: one to the control database (shared across all requests) and one per tenant (resolved from authentication). See Quick Start for the full wiring pattern.
Connection Format
Database names follow a consistent pattern. The proxy uses the name to identify the workspace or tenant.
| Type | Pattern | Example |
|---|---|---|
| Control workspace | {name}_workspace |
controlplane_workspace |
| Tenant workspace | {blueprint}_workspace |
myapp_workspace |
| Tenant database | {blueprint}__{tenant} |
myapp__acme |
Double underscore
__ is a reserved separator. Workspace and tenant names cannot contain __. Endpoints
One host per database type. All connections require TLS.
| Database | Host | Port | TLS |
|---|---|---|---|
| PostgreSQL | pg.tenantsdb.com | 5432 | ?sslmode=require |
| MySQL | mysql.tenantsdb.com | 3306 | TLS required |
| MongoDB | mongo.tenantsdb.com | 27017 | &tls=true |
| Redis | redis.tenantsdb.com | 6379 | rediss:// scheme |
PostgreSQL
postgresql://{project_id}:{password}@pg.tenantsdb.com:5432/{database}?sslmode=require
MySQL
mysql://{project_id}:{password}@mysql.tenantsdb.com:3306/{database}
MongoDB
mongodb://{project_id}:{password}@mongo.tenantsdb.com:27017/{database}?authMechanism=PLAIN&directConnection=true&tls=true
Redis
rediss://{tenant_id}:{api_key}@redis.tenantsdb.com:6379/0
MySQL TLS is configured per driver, not via URL parameter. See the MySQL page for per-language examples.
Choose Your Database
Each database has its own connection guide with shell commands, ORM examples, and proxy behavior. Pick yours.
