TypeScript SDK

The get-db9 SDK provides typed TypeScript access to DB9 databases — provisioning, SQL execution, filesystem operations, branching, and token management. This is the server-side SDK for Node.js environments.

Client-side? For browser and edge environments, use the @db9/browser SDK — it provides a query builder with Row-Level Security enforcement and publishable key authentication.

When to Use the SDK

Scenario	Recommended tool
One-liner database provisioning in a script or test	SDK — instantDatabase()
Programmatic fleet management (create, branch, delete)	SDK — createDb9Client()
File read/write from Node.js (RAG, ingestion)	SDK — client.fs.*
Interactive SQL from a terminal	CLI — db9 db sql (CLI Reference)
ORM or driver connection to an existing database	Raw pgwire — use the connection string (Connect)
Agent onboarding (Codex, Claude Code)	CLI — db9 onboard (Agent Workflows)

Installation

Runtime requirement: Node.js 18+ (native fetch). TypeScript 5+ for full type exports.

Terminal

npm install get-db9

Also available via yarn add get-db9, pnpm add get-db9, or bun add get-db9.

The SDK shares the credential store (~/.db9/credentials) with the db9 CLI. If you have logged in via the CLI, the SDK picks up the token automatically.

Quick Start

instantDatabase() creates or reuses a database by name. If no name is provided, it defaults to "default".

TypeScript

import { instantDatabase } from 'get-db9';

const db = await instantDatabase({
  name: 'myapp',
  seed: 'CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT)'
});

console.log(db.databaseId);
console.log(db.connectionString);
console.log(db.adminUser, db.adminPassword);
console.log(db.state, db.createdAt);

▶ Run

Authentication required

The SDK requires a valid token in ~/.db9/credentials or passed via Db9ClientOptions.token. If no token is available, the client throws an error. Run db9 login or db9 create (which auto-registers an anonymous account) before using the SDK, or pass a token explicitly.

Result shape:

TypeScript

interface InstantDatabaseResult {
  databaseId: string;
  connectionString: string;
  adminUser: string;
  adminPassword: string;
  state: string;
  createdAt: string;
}

instantDatabase(options?)

High-level API that wraps createDb9Client(), checks for an existing database by name, creates one if missing, and optionally executes seed SQL. Seed SQL runs only on initial creation — if the database already exists, seed is skipped.

TypeScript

function instantDatabase(
  options?: InstantDatabaseOptions
): Promise<InstantDatabaseResult>;

Option	Type	Description
name	string	Database name. Default: 'default'.
baseUrl	string	Override API endpoint. Default: https://api.db9.ai or DB9_API_URL env.
fetch	FetchFn	Custom fetch implementation.
credentialStore	CredentialStore	Token load/save strategy.
seed	string	SQL text executed via client.databases.sql() on creation only.
seedFile	string	SQL file content executed via client.databases.sqlFile() on creation only.
timeout	number	Request timeout in milliseconds.
maxRetries	number	Retry count for failed requests (capped at 3).
retryDelay	number	Delay between retries in milliseconds.

TypeScript

const db = await instantDatabase({
  name: 'analytics',
  seedFile: `
    CREATE TABLE events (
      id BIGSERIAL PRIMARY KEY,
      user_id TEXT NOT NULL,
      created_at TIMESTAMP DEFAULT NOW()
    );
  `
});

createDb9Client(options?)

Low-level typed client exposing grouped APIs: auth, tokens, databases, and fs.

The client lazy-loads the token from the credential store on the first protected call. If no token is found, it throws Db9Error (status 401). Use db9 login or pass a token via options.token before calling protected methods.

TypeScript

function createDb9Client(options?: Db9ClientOptions): Db9Client;

Option	Type	Description
baseUrl	string	Default: https://api.db9.ai (or DB9_API_URL env).
token	string	Bearer token; skips credential store lookup.
fetch	FetchFn	Custom HTTP implementation.
credentialStore	CredentialStore	Load/save token state.
timeout	number	Request timeout in milliseconds.
maxRetries	number	Retry count for failed requests (capped at 3).
retryDelay	number	Delay between retries in milliseconds.
WebSocket	WebSocketConstructor	Override WebSocket for client.fs operations (see Filesystem).
wsPort	number	Override the fs9 WebSocket port (default: 5480).

TypeScript

import { createDb9Client, MemoryCredentialStore } from 'get-db9';

const client = createDb9Client({
  baseUrl: 'https://api.db9.ai',
  credentialStore: new MemoryCredentialStore()
});

▶ Run

Authentication (client.auth)

• me(): Promise<CustomerResponse> — Get current user profile

The SDK itself does not handle login or registration. Use the CLI for auth:

Terminal

# Zero-setup trial (auto creates anonymous account + token)
db9 create --name quickstart

# Upgrade anonymous account to verified SSO identity
db9 claim

# Human operator login (browser-based)
db9 login

# API key login (CI/CD, agents)
db9 login --api-key <KEY>

# Create an automation token
db9 token create --name my-agent --expires-in-days 365

# Agent runtime
export DB9_API_KEY=<token>

Once authenticated via CLI, the SDK picks up the stored token automatically.

Token Management (client.tokens)

Create, inspect, and revoke API tokens for CI/CD and programmatic access.

• create(req: CreateTokenRequest): Promise<CreateTokenResponse> — Create named token with optional expiry
• list(): Promise<TokenResponse[]>
• revoke(tokenId: string): Promise<MessageResponse>

TypeScript

const newToken = await client.tokens.create({
  name: 'ci-deploy',
  expires_in_days: 90
});
console.log(newToken.token); // Store in secret manager

const tokens = await client.tokens.list();
for (const token of tokens) {
  console.log(token.id, token.name, token.created_at, token.expires_at);
}

await client.tokens.revoke(tokens[0].id);

Database Management (client.databases)

Core lifecycle APIs: create, list, get, delete, reset password, retrieve credentials, and read observability metrics.

• create(req: CreateDatabaseRequest): Promise<DatabaseResponse>
• list(): Promise<DatabaseResponse[]>
• get(databaseId: string): Promise<DatabaseResponse>
• delete(databaseId: string): Promise<MessageResponse>
• resetPassword(databaseId: string): Promise<CustomerPasswordResetResponse>
• credentials(databaseId: string): Promise<CustomerPasswordResetResponse> — Get stored admin credentials without resetting
• observability(databaseId: string): Promise<TenantObservabilityResponse>

TypeScript

const db = await client.databases.create({
  name: 'billing',
  region: 'us-west',
  admin_password: 'StrongAdminPass1'
});

const all = await client.databases.list();
const current = await client.databases.get(db.id);

const rotated = await client.databases.resetPassword(db.id);
const creds = await client.databases.credentials(db.id);
const metrics = await client.databases.observability(db.id);

await client.databases.delete(db.id);

For programmatic provisioning patterns, see Provisioning.

SQL Execution

Execute SQL strings or SQL file content through the customer API. Both methods return SqlResult.

• sql(databaseId: string, query: string): Promise<SqlResult>
• sqlFile(databaseId: string, fileContent: string): Promise<SqlResult>

TypeScript

const result = await client.databases.sql(
  databaseId,
  'SELECT id, email FROM users ORDER BY id LIMIT 10'
);

console.log(result.columns);
console.log(result.rows);
console.log(result.row_count, result.command, result.error);

const fromFile = await client.databases.sqlFile(databaseId, `
  CREATE TABLE audit_log (id BIGSERIAL PRIMARY KEY, event TEXT);
  INSERT INTO audit_log(event) VALUES ('created');
`);

SqlResult Field	Type	Description
columns	ColumnInfo[]	Column metadata for result rows.
rows	unknown[][]	Result values matrix.
row_count	number	Rows affected/returned.
command	string	Executed command label (SELECT, INSERT, etc.).
error	string | SqlErrorDetail	Structured error with message, code, detail, hint, and position.

Schema and Dump

Introspect schema objects or export SQL dump payloads.

• schema(databaseId: string): Promise<SchemaResponse>
• dump(databaseId: string, req?: DumpRequest): Promise<DumpResponse>

TypeScript

const schema = await client.databases.schema(databaseId);
for (const table of schema.tables) {
  console.log(table.schema, table.name);
}

const ddlOnly = await client.databases.dump(databaseId, { ddl_only: true });
console.log(ddlOnly.object_count);
console.log(ddlOnly.sql);

Migrations

Apply SQL migrations with checksums and inspect migration history.

• applyMigration(databaseId: string, req: MigrationApplyRequest): Promise<MigrationApplyResponse>
• listMigrations(databaseId: string): Promise<MigrationMetadata[]>

TypeScript

await client.databases.applyMigration(databaseId, {
  name: '20260218_add_users',
  sql: 'CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT NOT NULL);',
  checksum: 'f0b9c43b'
});

const applied = await client.databases.listMigrations(databaseId);
for (const migration of applied) {
  console.log(migration.name, migration.applied_at, migration.checksum);
}

Branching

Create a database branch from an existing database. Branch creation starts in CLONING state — poll with get() until it reaches ACTIVE or CREATE_FAILED.

• branch(databaseId: string, req: BranchRequest): Promise<DatabaseResponse>

TypeScript

const featureDb = await client.databases.branch(databaseId, {
  name: 'feature-auth'
});

let current = featureDb;
while (current.state === 'CLONING') {
  await new Promise((resolve) => setTimeout(resolve, 1000));
  current = await client.databases.get(featureDb.id);
}

if (current.state === 'CREATE_FAILED') {
  throw new Error('Branch clone failed');
}

console.log('Branch ready:', current.id, current.name);

For branch workflow patterns, see Multi-Tenant Patterns.

Database Users (client.databases.users)

Manage Postgres users inside a database.

• list(databaseId: string): Promise<UserResponse[]>
• create(databaseId: string, req: CreateUserRequest): Promise<MessageResponse>
• delete(databaseId: string, username: string): Promise<MessageResponse>

TypeScript

await client.databases.users.create(databaseId, {
  username: 'app_user',
  password: 'AppUserPass!'
});

const users = await client.databases.users.list(databaseId);
users.forEach((u) => {
  console.log(u.name, u.can_login, u.can_create_db, u.is_superuser);
});

await client.databases.users.delete(databaseId, 'app_user');

Filesystem (client.fs)

Cloud filesystem operations for reading, writing, and managing files attached to each database. Built for RAG pipelines, document ingestion, and agent workflows.

WebSocket requirement

Filesystem operations use WebSocket connections. Node.js 21+ and browsers have native WebSocket support. On Node.js 18–20, install the ws package or pass a WebSocket constructor via Db9ClientOptions.WebSocket.

• connect(dbId): Promise<FsClient> — Open a persistent WebSocket connection (caller must call close())
• list(dbId, path): Promise<FileInfo[]> — List directory contents
• read(dbId, path): Promise<string> — Read file content as text
• readBinary(dbId, path): Promise<Uint8Array> — Read file as binary
• write(dbId, path, content): Promise<void> — Write a file
• append(dbId, path, content): Promise<number> — Append to a file, returns bytes written
• stat(dbId, path): Promise<FileInfo> — Get file metadata
• exists(dbId, path): Promise<boolean> — Check if file exists
• mkdir(dbId, path): Promise<void> — Create a directory recursively
• remove(dbId, path, opts?): Promise<void> — Delete a file or directory
• rename(dbId, oldPath, newPath): Promise<void> — Move or rename a path

TypeScript

import { createDb9Client } from 'get-db9';

const client = createDb9Client();
const dbId = 'my-database-id';

// Create directory and write a file
await client.fs.mkdir(dbId, '/data');
await client.fs.write(dbId, '/data/hello.txt', 'Hello from db9!');

// Read file content
const content = await client.fs.read(dbId, '/data/hello.txt');

// List directory
const files = await client.fs.list(dbId, '/data/');
for (const file of files) {
  console.log(file.path, file.type, file.size);
}

// Stat and check existence
const info = await client.fs.stat(dbId, '/data/hello.txt');
console.log(info.type, info.size, info.mtime);

const exists = await client.fs.exists(dbId, '/data/hello.txt');
console.log('File exists:', exists);

// Append and rename
await client.fs.append(dbId, '/data/hello.txt', '\nHello again');
await client.fs.rename(dbId, '/data/hello.txt', '/data/hello-2.txt');

// Cleanup
await client.fs.remove(dbId, '/data/hello-2.txt');
await client.fs.remove(dbId, '/data');

FileInfo

Field	Type	Description
path	string	Full file path.
size	number	File size in bytes.
type	'file' | 'dir'	Entry type.
mode	number	Unix file mode.
mtime	string	Last modified time as RFC 3339 text.

FsRemoveOptions

Option	Type	Description
recursive	boolean	Remove directories recursively (default: false).

Batch operations: use a persistent connection

Convenience methods like read(), write(), and list() each open and close a WebSocket connection per call. For batch operations, use client.fs.connect(dbId) to open a persistent connection and reuse it.

Credential Storage

Credential stores implement a shared async interface used by client auto-auth.

• FileCredentialStore(path?) — TOML file store at ~/.db9/credentials (shared with db9 CLI)
• MemoryCredentialStore — Volatile in-memory store for tests and serverless
• defaultCredentialStore() — Factory that returns new FileCredentialStore()

TypeScript

import {
  createDb9Client,
  FileCredentialStore,
  MemoryCredentialStore,
  defaultCredentialStore
} from 'get-db9';

const fileStore = new FileCredentialStore();
const customStore = new FileCredentialStore('/tmp/db9-credentials.toml');
const memStore = new MemoryCredentialStore();

const client = createDb9Client({ credentialStore: fileStore });

Error Handling

API failures throw named Db9Error subclasses based on HTTP status code.

• Db9Error — Base class with statusCode, message, and optional response
• Db9AuthError — Status 401
• Db9NotFoundError — Status 404
• Db9ConflictError — Status 409 (e.g., duplicate database name)

TypeScript

import {
  createDb9Client,
  Db9Error,
  Db9AuthError,
  Db9NotFoundError,
  Db9ConflictError
} from 'get-db9';

const client = createDb9Client();

try {
  await client.databases.get('missing-id');
} catch (error) {
  if (error instanceof Db9NotFoundError) {
    console.error('Database not found');
  } else if (error instanceof Db9AuthError) {
    console.error('Authentication required — run `db9 login` first');
  } else if (error instanceof Db9ConflictError) {
    console.error('Conflict (e.g., duplicate name)');
  } else if (error instanceof Db9Error) {
    console.error(`db9 API error ${error.statusCode}: ${error.message}`);
  } else {
    throw error;
  }
}

TypeScript Types Reference

The package re-exports all interfaces from ./types in addition to client, credential, and filesystem types.

Already documented inline: InstantDatabaseResult (see Quick Start), SqlResult and ColumnInfo (see SQL Execution), FileInfo and FsRemoveOptions (see Filesystem).

DatabaseResponse

Returned by create(), list(), get(), and branch().

TypeScript

interface DatabaseResponse {
  id: string;
  name: string;
  state: string;
  parent_database_id?: string;
  region?: string;
  endpoints?: Endpoint[];
  admin_user?: string;
  admin_password?: string;
  created_at: string;
  connection_string?: string;
}

Field	Type	Description
id	string	Unique database identifier.
name	string	Human-readable database name.
state	string	Lifecycle state: CREATING, ACTIVE, CLONING, DISABLING, DISABLED, CREATE_FAILED.
parent_database_id	string?	Source database ID for branch databases.
region	string?	Deployment region (e.g. us-west).
endpoints	Endpoint[]?	Connection endpoints (host, port, type).
admin_user	string?	Admin Postgres username.
admin_password	string?	Admin Postgres password. Only present on create.
created_at	string	ISO 8601 creation timestamp.
connection_string	string?	Full postgresql:// connection URI.

CustomerResponse

Returned by client.auth.me().

TypeScript

interface CustomerResponse {
  id: string;
  email: string;
  created_at: string;
  status: string;
}

Field	Type	Description
id	string	Customer account identifier.
email	string	Account email address. Empty for anonymous accounts.
created_at	string	ISO 8601 account creation timestamp.
status	string	Account status: active, anonymous.

TokenResponse

Returned by client.tokens.list(). Metadata only — does not include the token secret.

TypeScript

interface TokenResponse {
  id: string;
  name: string;
  created_at: string;
  expires_at?: string;
}

Field	Type	Description
id	string	Token identifier. Use this to revoke the token.
name	string	Human-readable token label.
created_at	string	ISO 8601 creation timestamp.
expires_at	string?	ISO 8601 expiry timestamp. undefined means never expires.

CreateTokenResponse

Returned by client.tokens.create(). Includes the token secret — store it immediately.

TypeScript

interface CreateTokenResponse {
  id: string;
  name: string;
  token: string;
  created_at: string;
  expires_at?: string;
}

Field	Type	Description
id	string	Token identifier.
name	string	Human-readable token label.
token	string	The secret token value. Shown only once — store in a secret manager.
created_at	string	ISO 8601 creation timestamp.
expires_at	string?	ISO 8601 expiry timestamp.

SchemaResponse

Returned by client.databases.schema().

TypeScript

interface SchemaResponse {
  tables: TableMetadata[];
  views: ViewMetadata[];
}

Field	Type	Description
tables	TableMetadata[]	All tables in the database.
views	ViewMetadata[]	All views in the database.

TableMetadata

TypeScript

interface TableMetadata {
  name: string;
  schema: string;
  columns: ColumnMetadata[];
}

Field	Type	Description
name	string	Table name.
schema	string	Postgres schema name (e.g. public).
columns	ColumnMetadata[]	Column definitions for this table.

ColumnMetadata

TypeScript

interface ColumnMetadata {
  name: string;
  type: string;
  nullable: boolean;
  default_value?: string;
}

Field	Type	Description
name	string	Column name.
type	string	Postgres data type (e.g. text, integer, timestamp).
nullable	boolean	Whether the column accepts NULL.
default_value	string?	Default expression, if defined.

ViewMetadata

TypeScript

interface ViewMetadata {
  name: string;
  schema: string;
}

Field	Type	Description
name	string	View name.
schema	string	Postgres schema name.

DumpResponse

Returned by client.databases.dump().

TypeScript

interface DumpResponse {
  sql: string;
  object_count: number;
}

Field	Type	Description
sql	string	Full SQL dump text.
object_count	number	Number of database objects included in the dump.

TenantObservabilityResponse

Returned by client.databases.observability().

TypeScript

interface TenantObservabilityResponse {
  summary: ObservabilitySummary;
  samples: QuerySample[];
}

Field	Type	Description
summary	ObservabilitySummary	Aggregate metrics for the observation window.
samples	QuerySample[]	Per-query performance samples.

ObservabilitySummary

TypeScript

interface ObservabilitySummary {
  window_seconds: number;
  statement_count: number;
  txn_commit_count: number;
  error_count: number;
  qps: number;
  tps: number;
  latency_avg_ms: number;
  latency_p99_ms: number;
  active_connections: number;
}

Field	Type	Description
window_seconds	number	Observation window length in seconds.
statement_count	number	Total statements executed in the window.
txn_commit_count	number	Total committed transactions.
error_count	number	Total statement errors.
qps	number	Average queries per second.
tps	number	Average transactions per second.
latency_avg_ms	number	Mean query latency in milliseconds.
latency_p99_ms	number	99th-percentile query latency in milliseconds.
active_connections	number	Current active connection count.

QuerySample

TypeScript

interface QuerySample {
  query: string;
  sample_count: number;
  error_count: number;
  latency_avg_ms: number;
  latency_p99_ms: number;
  latency_max_ms: number;
  last_seen_ms_ago: number;
}

Field	Type	Description
query	string	Normalized query text (literals replaced with $N).
sample_count	number	Number of times this query pattern was observed.
error_count	number	Number of times this query pattern produced an error.
latency_avg_ms	number	Mean execution latency in milliseconds.
latency_p99_ms	number	99th-percentile latency in milliseconds.
latency_max_ms	number	Maximum observed latency in milliseconds.
last_seen_ms_ago	number	Milliseconds since this query was last observed.

CustomerPasswordResetResponse

Returned by client.databases.resetPassword() and client.databases.credentials().

TypeScript

interface CustomerPasswordResetResponse {
  admin_user: string;
  admin_password: string;
  connection_string: string;
}

Field	Type	Description
admin_user	string	Admin Postgres username.
admin_password	string	Admin Postgres password (new password after reset).
connection_string	string	Full postgresql:// connection URI.

UserResponse

Returned by client.databases.users.list().

TypeScript

interface UserResponse {
  name: string;
  is_superuser: boolean;
  can_login: boolean;
  can_create_db: boolean;
  can_create_role: boolean;
}

Field	Type	Description
name	string	Postgres username.
is_superuser	boolean	Whether the user has superuser privileges.
can_login	boolean	Whether the user can open connections.
can_create_db	boolean	Whether the user can create databases.
can_create_role	boolean	Whether the user can create roles.

MigrationApplyResponse

Returned by client.databases.applyMigration().

TypeScript

interface MigrationApplyResponse {
  status: string;
  name: string;
}

Field	Type	Description
status	string	Migration result: applied or skipped (already applied).
name	string	Migration name as provided in the request.

MigrationMetadata

Returned by client.databases.listMigrations().

TypeScript

interface MigrationMetadata {
  name: string;
  checksum: string;
  applied_at: string;
  sql_preview: string;
}

Field	Type	Description
name	string	Migration name.
checksum	string	Checksum provided at apply time.
applied_at	string	ISO 8601 timestamp when the migration was applied.
sql_preview	string	Truncated SQL for display purposes.

MessageResponse

Returned by delete and revoke operations.

TypeScript

interface MessageResponse {
  message: string;
}

Field	Type	Description
message	string	Human-readable confirmation message.

Request Types

Type	Key Fields
CreateDatabaseRequest	name: string, region?: string, admin_password?: string
CreateTokenRequest	name?: string, expires_in_days?: number
BranchRequest	name: string
DumpRequest	ddl_only?: boolean
CreateUserRequest	username: string, password?: string
MigrationApplyRequest	name: string, sql: string, checksum: string

Other Exported Types

Type	Description
TenantState	Union: 'CREATING' | 'ACTIVE' | 'DISABLING' | 'DISABLED' | 'CREATE_FAILED'
SqlErrorDetail	Structured SQL error: message, code?, position?, hint?, detail?
Endpoint	Connection endpoint: host, port, type, region?, priority, enabled
InstantDatabaseOptions	Options for instantDatabase() — see Quick Start
Db9ClientOptions	Options for createDb9Client() — see createDb9Client
CredentialStore	Interface for token load/save — see Credential Storage
FetchFn	Custom fetch implementation type
FsListOptions, FsConnectOptions	Filesystem operation options

Next Steps

• Browser SDK — Client-side data access with RLS
• CLI Reference — Terminal-based database management
• Connect — Connection strings, TLS, and driver configuration
• Provisioning — Programmatic fleet management patterns
• Agent Workflows — SDK usage in agent pipelines
• Extensions — fs9, HTTP, vector, pg_cron, and more