Python SDK Quickstart

The onyx-database Python SDK works with onyx cli generated models. It resolves credentials via config files, environment variables, or explicit config and supports Python 3.11+.

Looking for other supported sdks?

TypeScriptPythonGoKotlin

Overview

Create an organization, database, and API keys in the Onyx Cloud Console. Download your api key config file, and use the Onyx CLI to pull your schema and generate Python models.

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

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",
  "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 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)

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