SDK Cheat Sheet

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

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

const account: Account = {
  id: "acct_1",
  name: "Checking",
  balance: 1250,
};

await db.save(tables.Account, account);

const fetched = await db.findById(tables.Account, "acct_1");

await db.save(tables.Account, { ...account, balance: 1400 });

await db.delete(tables.Account, "acct_1");

onyx.init<Schema>(): IOnyxDatabase<Schema>
db.save(tables.Account, account): Promise<Account>
db.findById(tables.Account, id): Promise<Account | null>
db.save(tables.Account, partialAccount): Promise<Account> // upsert
db.delete(tables.Account, id): Promise<boolean>

import { tables } from "./generated/onyx/types";

const transactions = [
  { id: "txn_batch_1", accountId: "acct_batch", amount: 1.99, currency: "USD" },
  { id: "txn_batch_2", accountId: "acct_batch", amount: 12.5, currency: "USD" },
  { id: "txn_batch_3", accountId: "acct_batch", amount: 45.0, currency: "USD" },
  { id: "txn_batch_4", accountId: "acct_batch", amount: 7.25, currency: "USD" },
];

await db.save(tables.Transaction, transactions);

db.save(tables.Transaction, transactions): Promise<Transaction[]>

import { eq, gt, gte, contains, desc } from "@onyx.dev/onyx-database";
import { tables } from "./generated/onyx/types";

const transactions = await db
  .from(tables.Transaction)
  .where(
    eq("status", "posted")
      .and(gt("amount", 100))
      .and(gte("createdAt", "2025-01-01"))
      .and(contains("merchant", "aws"))
  )
  .orderBy(desc("createdAt"))
  .limit(25)
  .list();

Defaults: if you omit limit() and pageSize, the API uses its server-side default page size (capped at 1000); responses include nextPage when more rows remain.

from(tables.Transaction): IQueryBuilder<Transaction>
eq()/gt()/gte()/contains(): ConditionBuilderImpl (IConditionBuilder)
where(...): IQueryBuilder<Transaction>
orderBy(desc("createdAt")): IQueryBuilder<Transaction>
limit(25): IQueryBuilder<Transaction>
list(): QueryResultsPromise<Transaction> // await -> QueryResults<Transaction> & Transaction[]

import { eq } from "@onyx.dev/onyx-database";
import { tables } from "./generated/onyx/types";

const rows = await db
  .select("id", "accountId", "amount", "createdAt")
  .from(tables.Transaction)
  .list();

select("id","accountId",...): IQueryBuilder<Pick<Transaction, "id" | "accountId" | "amount" | "createdAt">>
from(tables.Transaction): IQueryBuilder<...>
where(eq(...)): IQueryBuilder<...>
orderBy(desc("createdAt")): IQueryBuilder<...>
limit(20): IQueryBuilder<...>
list(): QueryResultsPromise<Pick<Transaction, "id" | "accountId" | "amount" | "createdAt">>

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

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

const tx = await db
  .from(tables.Transaction)
  .where(eq("id", "txn_123"))
  .firstOrNull();

const txAlt = await db
  .from(tables.Transaction)
  .where(eq("id", "txn_123"))
  .one();

from(tables.Transaction): IQueryBuilder<Transaction>
where(eq("id", ...)): IQueryBuilder<Transaction>
firstOrNull(): Promise<Transaction | null>
one(): Promise<Transaction | null>

import { onyx, within, gt } from "@onyx.dev/onyx-database";
import { Schema, tables } from "./generated/onyx/types";

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

const accountsWithLargeTx = await db
  .from(tables.Account)
  .where(
    within(
      "id",
      db
        .select("accountId")
        .from(tables.Transaction)
        .where(gt("amount", 1000))
    )
  )
  .list();

onyx.init<Schema>(): IOnyxDatabase<Schema>
db.select("accountId"): IQueryBuilder<Transaction>
within("id", subquery): ConditionBuilderImpl
db.from(tables.Account): IQueryBuilder<Account>
where(...): IQueryBuilder<Account>
list(): QueryResultsPromise<Account> // await -> QueryResults<Account> & Account[]

import { eq, gt } from "@onyx.dev/onyx-database";
import { tables } from "./generated/onyx/types";

const updated = await db
  .from(tables.Transaction)
  .where(eq("status", "pending").and(gt("amount", 100)))
  .setUpdates({ status: "posted" })
  .update();

from(tables.Transaction): IQueryBuilder<Transaction>
where(...): IQueryBuilder<Transaction>
setUpdates({ status: "posted" }): IQueryBuilder<Transaction>
update(): Promise<unknown>

import { eq } from "@onyx.dev/onyx-database";
import { tables } from "./generated/onyx/types";

const deletedCount = await db
  .from(tables.Transaction)
  .where(eq("status", "archived"))
  .delete();

from(tables.Transaction): IQueryBuilder<Transaction>
where(eq("status", "archived")): IQueryBuilder<Transaction>
delete(): Promise<number>

import { eq } from "@onyx.dev/onyx-database";
import { tables } from "./generated/onyx/types";

const byMerchant = await db
  .select("merchant", "currency")
  .from(tables.Transaction)
  .where(eq("status", "posted"))
  .groupBy("merchant", "currency")
  .list();

import { sum, eq } from "@onyx.dev/onyx-database";
import { tables } from "./generated/onyx/types";

const totals = await db
  .select(sum("amount"), "merchant")
  .from(tables.Transaction)
  .where(eq("status", "posted"))
  .list();

from(tables.Transaction): IQueryBuilder<Transaction>
sum("amount"): string // aggregation expression
select(...): IQueryBuilder<Transaction>
groupBy("merchant"): IQueryBuilder<Transaction>
list(): QueryResultsPromise<Record<string, unknown>> // await -> QueryResults<Record<string, unknown>> & Record<string, unknown>[]

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

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

const handle = await db
  .from(tables.Transaction)
  .where(eq("status", "posted"))
  .pageSize(100)
  .onItem((tx, action) => {
    if (!tx) return;
    switch (action) {
      case "QUERY_RESPONSE":
        console.log("Initial result", tx.id, tx.amount);
        break;
      case "CREATE":
        console.log("Created", tx.id);
        break;
      case "UPDATE":
        console.log("Updated", tx.id);
        break;
      case "DELETE":
        console.log("Deleted", tx.id);
        break;
      default:
        break;
    }
  })
  .stream(true, false);

setTimeout(() => handle.cancel(), 1000);

from(tables.Transaction): IQueryBuilder<Transaction>
pageSize(100): IQueryBuilder<Transaction>
onItem((tx, action) => ...): IQueryBuilder<Transaction>
stream(includeQueryResults?: boolean, keepAlive?: boolean): Promise<{ cancel(): void }>

import { desc } from "@onyx.dev/onyx-database";
import { tables } from "./generated/onyx/types";

const page1 = await db
  .from(tables.Transaction)
  .orderBy(desc("createdAt"))
  .list({ pageSize: 50 });

const page2 = page1.nextPage
  ? await db.from(tables.Transaction).nextPage(page1.nextPage).list()
  : null;

if (page2) {
  console.log("page2 size", page2.length, "next token", page2.nextPage);
}

from(tables.Transaction): IQueryBuilder<Transaction>
orderBy(...): IQueryBuilder<Transaction>
list({ pageSize: 50 }): QueryResultsPromise<Transaction> // await -> QueryResults<Transaction> & Transaction[]
await list result -> { nextPage?: string }
nextPage(token): IQueryBuilder<Transaction>
list(): QueryResultsPromise<Transaction>

import { onyx, type SchemaEntity } from "@onyx.dev/onyx-database";

const db = onyx.init();

const current = await db.getSchema();

const tempTable: SchemaEntity = {
  name: "TempTable",
  identifier: { name: "id", generator: "UUID", type: "String" },
  attributes: [
    { name: "id", type: "String", isNullable: false },
    { name: "name", type: "String", isNullable: false },
  ],
};

const nextSchema = {
  ...current,
  entities: [...(current.entities ?? []), tempTable],
  revisionDescription: "Add TempTable via SDK",
};

const diff = await db.diffSchema(nextSchema);
const validation = await db.validateSchema(nextSchema);

if (validation.valid) {
  await db.updateSchema(nextSchema, { publish: true });
}

Need the JSON shape for entities, attributes, and resolvers? See Schema Example.

db.getSchema(): Promise<SchemaRevision>
db.diffSchema(schema): Promise<SchemaDiff>
db.validateSchema(schema): Promise<SchemaValidationResult>
db.updateSchema(schema, { publish?: boolean }): Promise<SchemaRevision>