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://staging.db9.ai/api',
  credentialStore: new MemoryCredentialStore()
});

const customer = await client.auth.register({
  email: 'dev@example.com',
  password: 'S3curePass!'
});

const login = await client.auth.login({
  email: 'dev@example.com',
  password: 'S3curePass!'
});

const anon = await client.auth.anonymousRegister();
const refreshed = await client.auth.anonymousRefresh({
  anonymous_id: anon.anonymous_id,
  anonymous_secret: anon.anonymous_secret
});

const me = await client.auth.me();
const secret = await client.auth.getAnonymousSecret();
const claimed = await client.auth.claim({
  email: 'owner@example.com',
  password: 'N3wPass!'
});

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

Anonymous start
  |
  | createDb9Client() without token
  v
anonymousRegister() -> { token, anonymous_id, anonymous_secret }
  |
  | token persisted in CredentialStore
  v
Use client.* APIs as anonymous customer
  |
  | client.auth.claim({ email, password })
  v
Registered customer account (same identity now claimed)

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