TypeScript SDK Quickstart

The @onyx.dev/onyx-database SDK is a zero-dependency, strict-typed client for the Onyx Cloud Database. Resolves credentials similar to AWS credentials chain, and works with onyx-cli code generated types.

Looking for other supported sdks?

TypeScriptPythonGoKotlin

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

Create a database and publish a schema

Login to cloud.onyx.dev to create a database and an API key & secret.

Here is a minimal example schema:

{
  "tables": [
    {
      "name": "User",
      "identifier": {"name": "id", "generator": "UUID", "type": "String"},
      "type": "DEFAULT",
      "attributes": [
        {"name": "id","type": "String","maxSize": null,"isNullable": false},
        {"name": "status","type": "String","maxSize": null,"isNullable": false},
        {"name": "email", ...},
        {"name": "createdAt", ...}
      ]
    }
  ]
}

Configure credentials

Set credentials using environment variables or a project config file.

Option A: Environment variables

export ONYX_DATABASE_ID="your-database-id"
export ONYX_DATABASE_API_KEY="key_abc"
export ONYX_DATABASE_API_SECRET="secret_xyz"

Option B: Project config file (onyx-database.json)

{
  "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 gen

Initialize the client

Initialize with env vars or config file detection:

import { onyx } from '@onyx.dev/onyx-database';
import { tables, Schema } from 'onyx/types';

const db = onyx.init<Schema>();

Or with explicit config:

const db = onyx.init<Schema>({
  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

Use a simple builder-pattern query API. Now you can perform crud operations!

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

const db = onyx.init<Schema>();

await db.save(tables.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();

What else can I do?

Atomic SavingResolversBulk SaveQuery & FilterInner QueriesAggregationsStreaming QueriesFull-Text SearchPaginationAI Chat

Resources

Next Steps

Need Help?

If you have any questions or need assistance:

Contact Support