TypeScript SDK

The @onyx.dev/onyx-database SDK is a zero-dependency, strict-typed client for the Onyx Cloud Database. It ships ESM & CJS builds, includes a credential resolver, and offers optional schema code generation so your queries stay table-safe.

Overview

Use this SDK to connect from Node.js (18+) or edge runtimes such as Cloudflare Workers. The recommended flow is: create an organization and database in the cloud console, create API keys, then configure credentials locally.

Install

1) Install the SDK from npm:

npm i @onyx.dev/onyx-database

2) Install the Onyx CLI (for schema pulls & codegen):

# Homebrew (macOS)
brew tap OnyxDevTools/onyx-cli
brew install onyx-cli

# Or install directly
curl -fsSL https://raw.githubusercontent.com/OnyxDevTools/onyx-cli/main/scripts/install.sh | bash

onyx version

Configure credentials

Create an API key in Onyx Database. Then either set environment variables or drop an onyx-database.json config file in your project root.

Option A: Environment variables (preferred)

export ONYX_DATABASE_ID="db_123"
export ONYX_DATABASE_BASE_URL="https://api.onyx.dev"
export ONYX_DATABASE_API_KEY="key_abc"
export ONYX_DATABASE_API_SECRET="secret_xyz"

Option B: Project config file

{
  "databaseId": "db_123",
  "apiKey": "key_abc",
  "apiSecret": "secret_xyz",
  "baseUrl": "https://api.onyx.dev"
}

Generate TypeScript types

Install the CLI, pull your schema, and generate table-safe types and a tables enum.

onyx schema get onyx.schema.json
onyx gen

Initialize the client

Initialize with env vars or pass explicit config:

import { onyx } from '@onyx.dev/onyx-database';

const db = onyx.init({ databaseId: 'YOUR_DATABASE_ID' });
const db = onyx.init({
  baseUrl: 'https://api.onyx.dev',
  databaseId: 'YOUR_DATABASE_ID',
  apiKey: 'YOUR_KEY',
  apiSecret: 'YOUR_SECRET',
  partition: 'tenantA',
  requestLoggingEnabled: true,
  responseLoggingEnabled: true,
});

Save and query data

The builder-pattern API mirrors the README examples. Here is a quick save and list flow for aUser table:

import { onyx, eq, contains, asc } from '@onyx.dev/onyx-database';

const db = onyx.init();

await db.save('User', {
  id: 'user_123',
  email: 'alice@example.com',
  status: 'active',
});

const activeUsers = await db
  .from('User')
  .where(eq('status', 'active'))
  .and(contains('email', '@example.com'))
  .orderBy(asc('createdAt'))
  .limit(25)
  .list();

Resources

Next Steps

Need Help?

If you have any questions or need assistance:

Contact Support