stitchdb

The official Python client for StitchDB: Postgres database, auth, storage, realtime and Edge Functions. Sync and async.

pip install stitchdb

Python 3.9+. To install the latest code from this repository instead: pip install "git+https://github.com/stitchdb/stitchdb-python".

import os
from stitchdb import create_client

stitchdb = create_client(os.environ["STITCHDB_URL"], os.environ["STITCHDB_KEY"])

# Database (respects Row Level Security)
rows = stitchdb.table("todos").select("id, task").eq("is_complete", False).limit(10).execute().data
stitchdb.table("todos").insert({"task": "Ship it"}).execute()
stitchdb.rpc("search_todos", {"term": "ship"}).execute()

# Auth
stitchdb.auth.sign_in_with_password({"email": "ada@example.com", "password": "..."})
user = stitchdb.auth.get_user()

# Storage
stitchdb.storage.from_("avatars").upload("user-1/avatar.png", open("avatar.png", "rb").read())
url = stitchdb.storage.from_("avatars").create_signed_url("user-1/avatar.png", 60)

# Edge Functions
stitchdb.functions.invoke("hello-world", {"body": {"name": "Ada"}})

Async: from stitchdb import acreate_client and stitchdb = await acreate_client(url, key). Realtime needs the async client.

App services

The same client reaches StitchDB's app services (turn each on in Studio first). Errors raise a subclass of stitchdb.StitchDBAppsError (.status, .code, .message).

stitchdb.flags.load(attributes={"app_version": "2.4.1"})
if stitchdb.flags.is_on("new-checkout"): ...

stitchdb.analytics.track("purchase", {"plan": "pro"}); stitchdb.analytics.flush()
stitchdb.crashes.start(release="2.4.1")          # reports uncaught exceptions
stitchdb.push.register({"platform": "android", "token": fcm_token})
stitchdb.purchases.has_entitlement("pro")
stitchdb.search("articles", "postgres backups", mode="hybrid")
stitchdb.orgs.create("Acme")
offline = stitchdb.offline(["todos"], path="todos.json"); offline.sync()

# Server side, with the service key
stitchdb.jobs.start("send-invoice", {"order": 42}, idempotency_key="order-42")
stitchdb.metering.record("api_calls", 1, customer="acme")

Also: links (deep links), collab (collaborative documents), history (realtime message history and replay), heartbeat (job monitoring), status_page, graphql(), and in stitchdb.auth: sign_in_with_web3, passkey, oauth (consent), mfa.recovery_codes.

Standalone helpers:

from stitchdb import create_sql, verify_webhook, AgentClient

sql = create_sql(os.environ["STITCHDB_SQL_URL"])            # SQL over HTTP: https://<sql key>@<host>
rows = sql.query("select * from orders where id = $1", [42])

event = verify_webhook(request_body, request_headers, secret=WEBHOOK_SECRET)  # raises if not genuine

agent = AgentClient(os.environ["STITCHDB_AGENT_KEY"])        # sdb_agt_ keys for AI agents
agent.sql("select count(*) from orders", session="task-1")

Find your project URL and keys in the dashboard under Settings → API keys. Use the service_role key only on servers you control.

Documentation: https://stitchdb.com/docs/sdk/python