Connect to DB9

DB9 speaks the PostgreSQL wire protocol on port 5433. Any client that connects to Postgres — psql, a Node.js driver, Prisma, SQLAlchemy, or a raw libpq binding — connects to DB9 with no adapter or proxy needed.

Connection string format

Every DB9 connection string follows this pattern:

Output

postgresql://<tenant_id>.<role>@<host>:<port>/postgres

Component	Value	Notes
Scheme	postgresql:// or postgres://	Both work.
Username	<tenant_id>.<role>	The tenant ID is assigned at database creation. The default role is admin.
Host	api.db9.ai	The public endpoint for hosted DB9.
Port	5433	Default PostgreSQL wire protocol port for DB9.
Database	postgres	All DB9 databases use the postgres database name.

Example:

Output

postgresql://a1b2c3d4e5f6.admin@api.db9.ai:5433/postgres

Get your connection string

Using the CLI

After creating a database, use db9 db connect to retrieve connection details:

Terminal

# Create a database
db9 create myapp

# Show connection info
db9 db connect myapp

For a short-lived token (recommended for production and automation):

Terminal

db9 db connect-token myapp

This returns a token, host, port, user, and a ready-to-use psql command:

Output

Host:       api.db9.ai
Port:       5433
Database:   postgres
User:       a1b2c3d4e5f6.admin
Expires At: 2026-03-12T10:30:00Z

Token:
  ey...

psql Command:
  PGPASSWORD='ey...' psql "postgresql://a1b2c3d4e5f6.admin@api.db9.ai:5433/postgres"

To reset a static password instead:

Terminal

db9 db reset-password myapp

Using the TypeScript SDK

The SDK returns a connection string automatically when you create or connect to a database:

TypeScript

import { instantDatabase } from 'get-db9';

const db = await instantDatabase({ name: 'myapp' });
console.log(db.connectionString);
// postgresql://a1b2c3d4e5f6.admin:password@api.db9.ai:5433/postgres

Or use the full client to get a connect token:

TypeScript

import { createDb9Client } from 'get-db9';

const client = createDb9Client();
const token = await client.databases.connectToken(databaseId);
// { host, port, database, user, token, expires_at }

Connect with psql

Use the connection string directly or let db9 db connect-token generate the command for you:

Terminal

# Using a connect token (recommended)
PGPASSWORD='<token>' psql "postgresql://a1b2c3d4e5f6.admin@api.db9.ai:5433/postgres"

# Using a static password
PGPASSWORD='<password>' psql "postgresql://a1b2c3d4e5f6.admin@api.db9.ai:5433/postgres"

You can also use a .pgpass file:

Terminal

echo "api.db9.ai:5433:postgres:a1b2c3d4e5f6.admin:<password>" >> ~/.pgpass
chmod 600 ~/.pgpass
psql "postgresql://a1b2c3d4e5f6.admin@api.db9.ai:5433/postgres"

Or use the built-in DB9 SQL REPL, which handles authentication automatically:

Terminal

db9 sql myapp "SELECT version()"

Connect with ORMs and drivers

DB9 works with any PostgreSQL-compatible driver or ORM. Set the connection string as your database URL.

Node.js (pg)

TypeScript

import pg from 'pg';

const client = new pg.Client({
  connectionString: 'postgresql://a1b2c3d4e5f6.admin:password@api.db9.ai:5433/postgres',
});
await client.connect();
const res = await client.query('SELECT NOW()');
console.log(res.rows[0]);
await client.end();

Prisma

Output

# .env
DATABASE_URL="postgresql://a1b2c3d4e5f6.admin:password@api.db9.ai:5433/postgres"

prisma

// schema.prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

Drizzle

TypeScript

import { drizzle } from 'drizzle-orm/node-postgres';

const db = drizzle('postgresql://a1b2c3d4e5f6.admin:password@api.db9.ai:5433/postgres');

SQLAlchemy (Python)

Python

from sqlalchemy import create_engine

# With psycopg2 (default driver)
engine = create_engine(
    "postgresql+psycopg2://a1b2c3d4e5f6.admin:password@api.db9.ai:5433/postgres"
)

Go (pgx)

Go

conn, err := pgx.Connect(context.Background(),
    "postgresql://a1b2c3d4e5f6.admin:password@api.db9.ai:5433/postgres")

For detailed setup guides with migrations, schema patterns, and troubleshooting, see the integration guides for Prisma, Drizzle, SQLAlchemy, TypeORM, Sequelize, Knex, and GORM.

Authentication

DB9 supports three ways to authenticate connections:

Static password

Set at database creation or reset with db9 db reset-password. The password is embedded in the connection string or passed via PGPASSWORD. Simple, but the credential does not expire.

Short-lived connect token

Generated with db9 db connect-token or client.databases.connectToken() in the SDK. The token is used as the password and expires automatically. Recommended for production and CI/CD.

Terminal

# Generate a token for a specific role
db9 db connect-token myapp --role admin

API token (for SDK and REST API)

Named tokens created with db9 token create are used for the DB9 REST API and SDK, not for direct pgwire connections. Use them when your application manages databases programmatically rather than connecting with SQL.

Terminal

db9 token create --name ci-agent --expires-in-days 90
export DB9_API_KEY=<token>

See the TypeScript SDK docs for the full auth lifecycle, including anonymous trial accounts and Auth0 SSO.

TLS

DB9’s hosted service supports TLS connections. The server uses SCRAM-SHA-256 authentication by default.

Most PostgreSQL clients default to sslmode=prefer, which will use TLS when available. For stricter security:

Terminal

psql "postgresql://a1b2c3d4e5f6.admin@api.db9.ai:5433/postgres?sslmode=require"

Or in a connection string for an ORM:

Output

DATABASE_URL="postgresql://a1b2c3d4e5f6.admin:password@api.db9.ai:5433/postgres?sslmode=require"

Multi-tenant username format

DB9 uses the username field to route connections to the correct tenant. The format is:

Output

<tenant_id>.<role>

• The tenant ID is a 12-character alphanumeric string assigned when the database is created.
• The role defaults to admin. You can create additional roles with db9 db users create.

This encoding means your username in connection strings will look different from a typical Postgres setup, but it works transparently with all standard PostgreSQL drivers.

Connection checklist

Check	Details
Port	5433, not the default PostgreSQL 5432
Database name	Always postgres
Username	Must include the tenant ID prefix: <tenant_id>.<role>
Password	Static password or connect token — both go in PGPASSWORD or the connection string
TLS	Use sslmode=require or sslmode=prefer
Protocol	Standard PostgreSQL wire protocol — no special drivers needed

Troubleshooting

“password authentication failed”

• Verify your tenant ID and role are correct in the username field.
• If using a connect token, check that it has not expired.
• Run db9 db connect-token myapp to generate a fresh token.

“connection refused” on port 5432

• DB9 uses port 5433, not the PostgreSQL default 5432.

“SSL SYSCALL error” or TLS handshake failures

• Ensure your client supports TLS. Try adding ?sslmode=require to the connection string.
• Some older clients may need updated CA certificates.

ORM connection timeouts

• Check that your ORM’s connection string uses the correct port (5433) and database name (postgres).
• Verify your network allows outbound connections on port 5433.

Next steps

• Quick Start — create your first database and run SQL
• CLI Reference — full command reference including db connect, db connect-token, and db reset-password
• TypeScript SDK — instantDatabase(), credential management, and programmatic access
• Architecture — how DB9 routes connections through the pgwire protocol to TiKV
• Extensions — enable vector search, fs9, HTTP from SQL, and pg_cron after connecting