Use the Python SDK

The Python SDK offers a synchronous client and an async client that suits web frameworks such as FastAPI. It also includes a command-line tool.

Install

pip install pgbhub

Create a client and run a first query

from pgbhub import PGBHubClient

# project_id alone targets https://my-project.pgbhub.app
client = PGBHubClient(api_key="your_api_key", project_id="my-project")

User = client.user   # a table, used like a model

user = User.find_one(filter={"email": "[email protected]"})
new_user = User.create(data={"email": "[email protected]", "name": "Alex"})
User.update(filter={"id": "8ef5-492a-bb81"}, data={"name": "Alexander"})
User.delete(filter={"id": "8ef5-492a-bb81"})

Async:

from pgbhub import AsyncPGBHubClient

client = AsyncPGBHubClient(api_key="...")
row = await client.user.find_one(filter={"id": user_id})

Configuration

Setting	Argument	Environment variable
Key	api_key	PGBHUB_API_KEY or PGBHUB_PUBLISHABLE_KEY
Project	project_id	PGBHUB_PROJECT_ID
Address	endpoint	PGBHUB_ENDPOINT
Database	database	PGBHUB_DATABASE (only needed to name one)

Timeout defaults to 30 seconds with 2 retries for reads. Writes never retry.

Sign users in

auth = client.auth
result = auth.sign_up("[email protected]", "a-long-password")
login = auth.sign_in("[email protected]", "a-long-password")
if login.get("mfa_required"):
    auth.verify_mfa(login["challenge_token"], "123456")

One-time codes and links are only ever emailed. The API never returns them.

Mail, storage and actions

client.mail.send("[email protected]", "Your receipt", "Thanks for your order.",
                 html="<p>Thanks for your order.</p>", reply_to="[email protected]")

client.storage.create_bucket("receipts", visibility="private")
link = client.storage.create_signed_url("receipts", "invoices/inv-1.pdf", expires_in=900)

client.actions.save_user({"email": "[email protected]"})                 # run
client.actions.save_user({"email": "[email protected]"}, dry_run=True)   # preview

Mail and storage admin calls need your secret key.

Errors

Every failure raises PGBHubError with status_code, code, message, body and, for rate limits, retry_after.

from pgbhub import PGBHubError
try:
    client.auth.sign_in("[email protected]", "wrong")
except PGBHubError as e:
    print(e.status_code, e.message)

Generate models

pgbhub pull --db my_database --out models.py

This reads your schema and writes typed models, with no AI involved.

Good to know

• Keep the secret key in an environment variable on your server.
• For the full list of calls in other languages, see Use the TypeScript SDK.