Python SDK

The onyx-database Python SDK ships a typed, builder-pattern API with optional Pydantic code generation. It resolves credentials via config files, environment variables, or explicit config and supports Python 3.11+.

Overview

Create an organization, database, and API keys in the Onyx Cloud Console. Download youronyx-database.json and keep your schema handy for the code generator.

Install

Install the SDK from PyPI:

pip install onyx-database

Install the Onyx CLI (needed for schema pulls and 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 place an onyx-database.json 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",
  "baseUrl": "https://api.onyx.dev",
  "apiKey": "key_abc",
  "apiSecret": "secret_xyz"
}

Generate Python models

Pull the schema and generate models + table helpers:

onyx schema get onyx.schema.json
onyx gen --py

Save and query data

Save first, then list records:

from onyx_database import onyx, eq, contains, asc

# Uses config resolution chain by default
db = onyx.init()

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

active_users = (
    db.from_table("User")
      .where(eq("status", "active"))
      .and_(contains("email", "@example.com"))
      .order_by(asc("createdAt"))
      .limit(25)
      .list()
)

for user in active_users:
    print(user)

Resources

Next Steps

Need Help?

If you have any questions or need assistance:

Contact Support