jsondb-cloud

The official Python SDK for jsondb.cloud — a hosted JSON document database.

Install

pip install jsondb-cloud

Quick Start

from jsondb_cloud import JsonDB

db = JsonDB(api_key="jdb_sk_live_xxxx")
users = db.collection("users")

# Create
user = users.create({"name": "Alice", "email": "alice@example.com"})

# Read
user = users.get(user["_id"])

# List with filtering
admins = users.list(filter={"role": "admin", "age": {"$gte": 21}}, sort="-createdAt", limit=10)

# Update
users.update(user["_id"], {"name": "Alice Updated", "email": "alice@example.com"})

# Patch (partial update)
users.patch(user["_id"], {"age": 31})

# Delete
users.delete(user["_id"])

Configuration

db = JsonDB(
    api_key="jdb_sk_live_xxxx",  # required
    project="v1",                 # project namespace (default: "v1")
    base_url="https://api.jsondb.cloud",  # API endpoint
    timeout=30.0,                 # request timeout in seconds
    max_retries=3,                # retries on 429/5xx errors
    headers={"X-Custom": "val"},  # extra headers for every request
)

AsyncJsonDB accepts the same options and supports async with for automatic cleanup.

API

All methods are available on both Collection (sync) and AsyncCollection (async).

See the full API reference for details.

Async Usage

from jsondb_cloud import AsyncJsonDB

async with AsyncJsonDB(api_key="jdb_sk_live_xxxx") as db:
    users = db.collection("users")
    user = await users.create({"name": "Alice"})
    page = await users.list(filter={"role": "admin"})

Error Handling

from jsondb_cloud import JsonDB, NotFoundError, QuotaExceededError, JsonDBError

try:
    user = users.get("nonexistent")
except NotFoundError as e:
    print(f"Not found: {e.document_id}")
except QuotaExceededError as e:
    print(f"Limit: {e.limit}, Current: {e.current}")
except JsonDBError as e:
    print(f"Error: {e.code} - {e.message} (HTTP {e.status})")

Documentation

Full documentation at jsondb.cloud/docs/sdks/python.

Related Packages

License

MIT