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

Prefer a global CLI install? Use pipx to install the CLI-only package:

pipx install onyx-database

Config files

The recommended layout matches the README and keeps config and schema in predictable paths:

your-project/
├── config/
│   └── onyx-database.json
└── schema/
    └── onyx.schema.json

Example config:

{
  "databaseId": "YOUR_DATABASE_ID",
  "baseUrl": "https://api.onyx.dev",
  "apiKey": "YOUR_DATABASE_KEY",
  "apiSecret": "YOUR_API_SECRET"
}

Environment variables

You can also rely on env vars for credentials:

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"

Initialize & query

Initialize and run a simple query:

from onyx_database import onyx, eq, contains, asc

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

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)

Generate Python models

Generate models and a tables helper from the API:

onyx-py gen --source api --out ./onyx --package onyx

Or generate from a local schema file:

onyx-py gen --source file --schema ./schema/onyx.schema.json --out ./onyx --package onyx

Schema CLI

Use the schema CLI to fetch, validate, or publish schemas:

onyx-py schema get
onyx-py schema publish
onyx-py schema validate ./schema/onyx.schema.json
onyx-py schema diff ./schema/onyx.schema.json

Resources

Need Help?

If you have any questions or need assistance:

Contact Support