TenantsDB — Connections

🔌 Connection Format

All databases follow a consistent connection pattern. Workspace databases use _dev suffix, tenant databases use double underscore __.

Type	Database Name	Example
Workspace	`{blueprint}_dev`	`myapp_dev`
Tenant	`{blueprint}__{tenant}`	`myapp__acme`

PostgreSQL

postgresql://{project_id}:{password}@pg.tenantsdb.com:5432/{database}

MySQL

mysql://{project_id}:{password}@mysql.tenantsdb.com:3306/{database}

MongoDB

mongodb://{project_id}:{password}@mongo.tenantsdb.com:27017/{database}?authMechanism=PLAIN&directConnection=true

Redis

redis://{tenant_id}:{api_key}@redis.tenantsdb.com:6379/0

📡 Endpoints

Database	Host	Port
PostgreSQL	pg.tenantsdb.com	5432
MySQL	mysql.tenantsdb.com	3306
MongoDB	mongo.tenantsdb.com	27017
Redis	redis.tenantsdb.com	6379

🐘 PostgreSQL

Connect with psql, Sequelize, SQLAlchemy, Prisma, or any PostgreSQL-compatible driver.

Connect to Workspace

Shell

psql "postgresql://tdb_2abf90d3:tdb_d2bf66ed7898c448@pg.tenantsdb.com:5432/myapp_dev"

Build Schema

SQL

CREATE TABLE accounts (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    balance DECIMAL(15,2) DEFAULT 0
);

INSERT INTO accounts (name, balance) VALUES
  ('Alice', 1000),
  ('Bob', 2000);

Or import a template: tdb workspaces schema myapp --template fintech

Connect to Tenant Databases

acme

Shell

psql "postgresql://tdb_2abf90d3:tdb_d2bf66ed7898c448@pg.tenantsdb.com:5432/myapp__acme"

globex

Shell

psql "postgresql://tdb_2abf90d3:tdb_d2bf66ed7898c448@pg.tenantsdb.com:5432/myapp__globex"

Same credentials, different database. Isolated data.

ORM Examples

Sequelize (Node.js)

JavaScript

const { Sequelize } = require('sequelize');
const sequelize = new Sequelize(process.env.DATABASE_URL);
// DATABASE_URL=postgresql://tdb_2abf90d3:tdb_d2bf66ed@pg.tenantsdb.com:5432/myapp__acme

SQLAlchemy (Python)

Python

from sqlalchemy import create_engine
engine = create_engine(os.environ['DATABASE_URL'])
# DATABASE_URL=postgresql://tdb_2abf90d3:tdb_d2bf66ed@pg.tenantsdb.com:5432/myapp__acme

Prisma

.env

DATABASE_URL="postgresql://tdb_2abf90d3:tdb_d2bf66ed@pg.tenantsdb.com:5432/myapp__acme"

🐬 MySQL

Connect with mysql client, Sequelize, SQLAlchemy, Prisma, or any MySQL-compatible driver.

Connect to Workspace

Shell

mysql -h mysql.tenantsdb.com -P 3306 \
  -u tdb_2abf90d3 -ptdb_d2bf66ed7898c448 \
  myapp_dev --enable-cleartext-plugin

The --enable-cleartext-plugin flag is required for TenantsDB proxy authentication.

Build Schema

SQL

CREATE TABLE accounts (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    balance DECIMAL(15,2) DEFAULT 0
);

INSERT INTO accounts (name, balance) VALUES
  ('Alice', 1000),
  ('Bob', 2000);

Connect to Tenant Databases

acme

Shell

mysql -h mysql.tenantsdb.com -P 3306 \
  -u tdb_2abf90d3 -ptdb_d2bf66ed7898c448 \
  myapp__acme --enable-cleartext-plugin

globex

Shell

mysql -h mysql.tenantsdb.com -P 3306 \
  -u tdb_2abf90d3 -ptdb_d2bf66ed7898c448 \
  myapp__globex --enable-cleartext-plugin

Same credentials, different database. ORMs handle the cleartext plugin automatically.

ORM Examples

Sequelize (Node.js)

JavaScript

const { Sequelize } = require('sequelize');
const sequelize = new Sequelize(process.env.DATABASE_URL);
// DATABASE_URL=mysql://tdb_2abf90d3:tdb_d2bf66ed@mysql.tenantsdb.com:3306/myapp__acme

SQLAlchemy (Python)

Python

from sqlalchemy import create_engine
engine = create_engine(os.environ['DATABASE_URL'])
# DATABASE_URL=mysql://tdb_2abf90d3:tdb_d2bf66ed@mysql.tenantsdb.com:3306/myapp__acme

Prisma

.env

DATABASE_URL="mysql://tdb_2abf90d3:tdb_d2bf66ed@mysql.tenantsdb.com:3306/myapp__acme"

🍃 MongoDB

Connect with mongosh, Mongoose, PyMongo, or the native MongoDB driver.

Connect to Workspace

Shell

mongosh "mongodb://tdb_2abf90d3:tdb_d2bf66ed7898c448@mongo.tenantsdb.com:27017/myapp_dev?authMechanism=PLAIN&directConnection=true"

authMechanism=PLAIN and directConnection=true are required for TenantsDB proxy authentication.

Build Schema

JavaScript

db.createCollection("accounts")

db.accounts.insertMany([
    { name: "Alice", balance: 1000 },
    { name: "Bob", balance: 2000 }
])

db.accounts.createIndex({ name: 1 })

Connect to Tenant Databases

acme

Shell

mongosh "mongodb://tdb_2abf90d3:tdb_d2bf66ed7898c448@mongo.tenantsdb.com:27017/myapp__acme?authMechanism=PLAIN&directConnection=true"

globex

Shell

mongosh "mongodb://tdb_2abf90d3:tdb_d2bf66ed7898c448@mongo.tenantsdb.com:27017/myapp__globex?authMechanism=PLAIN&directConnection=true"

Same credentials, different database. Isolated data.

Driver Examples

Node.js (native)

JavaScript

const { MongoClient } = require('mongodb');
const client = new MongoClient(process.env.MONGODB_URL);
// MONGODB_URL=mongodb://tdb_2abf90d3:tdb_d2bf66ed@mongo.tenantsdb.com:27017/myapp__acme?authMechanism=PLAIN&directConnection=true

Mongoose

JavaScript

const mongoose = require('mongoose');
mongoose.connect(process.env.MONGODB_URL);
// MONGODB_URL=mongodb://tdb_2abf90d3:tdb_d2bf66ed@mongo.tenantsdb.com:27017/myapp__acme?authMechanism=PLAIN&directConnection=true

PyMongo (Python)

Python

from pymongo import MongoClient
client = MongoClient(os.environ['MONGODB_URL'])
# MONGODB_URL=mongodb://tdb_2abf90d3:tdb_d2bf66ed@mongo.tenantsdb.com:27017/myapp__acme?authMechanism=PLAIN&directConnection=true

🔴 Redis

Connect with redis-cli, ioredis, redis-py, or node-redis.

Connect to Workspace

Shell

redis-cli -u "redis://dev:tenantsdb_sk_a91de156...@redis.tenantsdb.com:6379/0"

Redis uses {tenant_id}:{api_key} for authentication, unlike other databases which use {project_id}:{password}.

Add Data

Redis

SET user:1 "Alice"
SET user:2 "Bob"
HSET account:1 name "Alice" balance 1000
HSET account:2 name "Bob" balance 2000

Connect to Tenant Databases

acme

Shell

redis-cli -u "redis://acme:tenantsdb_sk_a91de156...@redis.tenantsdb.com:6379/0"

globex

Shell

redis-cli -u "redis://globex:tenantsdb_sk_a91de156...@redis.tenantsdb.com:6379/0"

Same API key, different tenant. Each tenant has an isolated keyspace with automatic key prefixing.

Client Examples

ioredis (Node.js)

JavaScript

const Redis = require('ioredis');
const redis = new Redis(process.env.REDIS_URL);
// REDIS_URL=redis://acme:tenantsdb_sk_xxx@redis.tenantsdb.com:6379/0

node-redis

JavaScript

const { createClient } = require('redis');
const client = createClient({ url: process.env.REDIS_URL });
// REDIS_URL=redis://acme:tenantsdb_sk_xxx@redis.tenantsdb.com:6379/0

redis-py (Python)

Python

import redis
r = redis.Redis.from_url(os.environ['REDIS_URL'])
# REDIS_URL=redis://acme:tenantsdb_sk_xxx@redis.tenantsdb.com:6379/0