instantDatabase(options?)
Creates or reuses a database by name. If no token is available, it can auto-register an anonymous session and save it in the credential store before creating the database. Supports SQL seeding via seed or seedFile.
Example
import { instantDatabase } from 'get-db9';
const db = await instantDatabase({
name: 'myapp',
seed: 'CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)',
});
console.log(db.databaseId, db.connectionString);Parameters
| Name | Type | Description |
|---|
name | string | Database name, default 'default'. |
baseUrl | string | API base URL override. |
fetch | FetchFn | Custom fetch implementation. |
credentialStore | CredentialStore | Token storage loader/saver. |
seed | string | SQL executed right after creation. |
seedFile | string | SQL file content executed after creation. |
timeout | number | Request timeout in milliseconds. |
maxRetries | number | Retry count (capped at 3). |
retryDelay | number | Delay between retries in ms. |
createDb9Client(options?)
Typed Client API with auth, database, SQL, schema, dump, migration, branch, user, and filesystem operations. It checks the credential store first and can auto-register an anonymous session when no token is present.
Example
import { createDb9Client } from 'get-db9';
const client = createDb9Client();
const db = await client.databases.create({ name: 'myapp' });
const result = await client.databases.sql(db.id, 'SELECT * FROM users');Parameters
| Name | Type | Description |
|---|
baseUrl | string | Client API endpoint (default production URL). |
token | string | Optional bearer token. If omitted, checks the credential store and can auto-register anonymously. |
fetch | FetchFn | Custom fetch implementation. |
credentialStore | CredentialStore | Load/save token state. |
timeout | number | Request timeout in milliseconds. |
maxRetries | number | Retry count (capped at 3). |
retryDelay | number | Delay between retries in ms. |
WebSocket | WebSocketConstructor | Override WebSocket implementation for fs operations. |
wsPort | number | Override the fs9 WebSocket port (default: 5480). |
client.fs
Cloud filesystem operations for reading, writing, and managing files attached to each database. Built for RAG pipelines, file ingestion, and agent workflows.
Methods
| Method | Returns | Description |
|---|
connect(dbId) | Promise<FsClient> | Open a persistent WebSocket connection. |
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. |
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 (recursive). |
remove(dbId, path, opts?) | Promise<void> | Delete a file or directory. |
rename(dbId, oldPath, newPath) | Promise<void> | Move or rename a path. |
Example
const client = createDb9Client();
await client.fs.mkdir(dbId, '/data');
await client.fs.write(dbId, '/data/doc.txt', 'Hello!');
const content = await client.fs.read(dbId, '/data/doc.txt');
const files = await client.fs.list(dbId, '/data/');
const info = await client.fs.stat(dbId, '/data/doc.txt');
await client.fs.remove(dbId, '/data/doc.txt');
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. |