API reference
Database package¶
Your settings, queues, whatever you persist. Gateway events and the Discord cache do not go here.
from astrae import Database
db = Database.shared("sqlite:///bot.db")
await db.connect()
row = await db.fetchrow(
"SELECT value FROM settings WHERE name = :name",
{"name": "greeting"},
)
async with db.transaction() as connection:
await connection.execute(
"UPDATE settings SET value = :value WHERE name = :name",
{"value": "Hello", "name": "greeting"},
)
await db.close()
URLs¶
| Name | Purpose |
|---|---|
sqlite:///bot.db |
sqlite+aiosqlite. Own pool. |
postgresql:// / postgres:// |
postgresql+asyncpg. |
mysql:// / mariadb:// |
mysql+asyncmy. |
pool_size / max_overflow / pool_timeout / pool_recycle |
Postgres/MySQL pool knobs. |
Drivers ship with the default install.
Connections¶
| Name | Purpose |
|---|---|
Database.shared(url) |
One registry instance per normalized URL in this process. Not across processes. |
connect() |
Optional eager connectivity check. |
fetch |
All rows as dictionaries. Named :parameter bindings. |
fetchrow |
First row or None. |
fetchval |
One column or None. |
execute |
ExecuteResult with row count and inserted key when the dialect reports it. |
transaction() |
Commit on exit, rollback on exception. |
session() |
ORM AsyncSession. Same commit/rollback. |
| Async context manager | Verify on entry, close the engine on exit. |
Database.close_all() |
Shut down every shared instance in this process. |
Bind values. Do not interpolate user input into SQL.
Migrations¶
| Name | Purpose |
|---|---|
Migration |
Positive integer version, name, up, optional down. SQL, a sequence, or a callback on Connection. |
Migrator.upgrade() |
Apply unapplied versions in order. Recorded in the same transaction. |
downgrade(target) |
Reverse in descending order. Fails if a required down is missing. |
Downgrade SQL is an operator decision. Back up first.