Complete get-db9 API Documentation

npm install get-db9
yarn add get-db9
pnpm add get-db9
bun add get-db9

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);

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

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

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

function createDb9Client(options?: Db9ClientOptions): Db9Client;

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

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

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

# Upgrade anonymous account to verified SSO identity
db9 claim
db9 claim --id-token <AUTH0_ID_TOKEN>

# Human operator login (prints verification URL + code, then opens browser)
db9 login

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

# Mint an agent token once, then store in secret manager
db9 token create --name my-agent --expires-in-days 365

# Agent runtime
export DB9_API_KEY=<token>

First-time user
  |
  | db9 db create (no credentials found)
  v
Anonymous account + bearer token
  |
  | db9 claim (Auth0 id_token required)
  v
Verified customer account
  |
  | db9 token create --name my-agent
  v
Agent API token (recommended for automation)

Alternative
  |
  | db9 login
  | Auth0 SSO (browser)
  | Exchange verified identity for db9 bearer token
  v
Customer bearer token

// Create a named API token
const newToken = await client.tokens.create({
  name: 'ci-deploy',
  expires_in_days: 90
});
console.log(newToken.token); // Use this for CI/CD

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

// Revoke a token
await client.tokens.revoke(tokens[0].id);

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 metrics = await client.databases.observability(db.id);

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

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');
`);

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);

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);
}

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

console.log(featureDb.id, featureDb.name, featureDb.connection_string);

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');

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 store = defaultCredentialStore();

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

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

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');
  } else if (error instanceof Db9ConflictError) {
    console.error('Conflict while processing request');
  } else if (error instanceof Db9Error) {
    console.error(`db9 API error ${error.statusCode}: ${error.message}`);
  } else {
    throw error;
  }
}

import { createDb9Client } from 'get-db9/client';

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.file_type, file.size);
}

// Stat a file
const info = await client.fs.stat(dbId, '/data/hello.txt');
console.log(info.file_type, info.size, info.mtime);

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

// Get events
const events = await client.fs.events(dbId, { limit: 10, path: '/data' });
for (const event of events) {
  console.log(event.type, event.path, event.timestamp);
}

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

export function instantDatabase(options?: InstantDatabaseOptions): Promise<InstantDatabaseResult>;
export { createDb9Client } from './client';
export type { Db9ClientOptions, Db9Client } from './client';
export { Db9Error, Db9AuthError, Db9NotFoundError, Db9ConflictError } from './errors';
export { FileCredentialStore, MemoryCredentialStore, defaultCredentialStore } from './credentials';
export type * from './types';