Database Integrations

​

1. Why the Database Boundary Exists

import heavenbase as hb

db = hb.Database(provider="sqlite", database="analytics.db")
print(db.tables())

​

2. Choose a Supported SQL Route

​

3. Understand Execution Behavior

• Database resolution is independent of machine bootstrap. Context constructs the system backend; ordinary SQL backends read active heavenbase.db config and do not inherit hidden bootstrap overrides.
• Engine pooling is shared by resolved database spec and tracks disposed engines explicitly. Two Database instances with the same provider/database/pool args use the same SQLAlchemy engine and pool. Dispose/create races are guarded so stale facades cannot silently recreate an engine after drop.
• Autocreate is best effort on first engine access. If superuser/database-creation credentials are missing or wrong, HeavenBase still attempts a direct connection so existing databases remain accessible.
• Explicit drop uses db.drop_database(force=True). SQLite/DuckDB remove files, PostgreSQL/MySQL/MSSQL/StarRocks drop databases, and Oracle drops the target user/schema while leaving the PDB service intact. Trino catalogs are connector-managed, so catalog create/drop is intentionally not attempted.
• readonly execution is explicit. The default is readonly=False; pass readonly=True only as a conservative guard for statements expected to be read-only. Pass readonly=None when you explicitly want conservative auto-detection for commit/rollback behavior.
• Raw SQL placeholders are normalized before execution. Supported styles are :name, ?, %s, %(name)s, $name, and $1, with dictionaries, positional tuples/lists, list-of-dicts batches, and list-of-tuples batches where the driver supports batching. Bare ? tokens are rewritten only for positional parameter payloads, so PostgreSQL JSON operators such as payload ? 'key', ?|, and ?& remain valid. PostgreSQL casts such as ?::int are preserved after bind rewriting.
• safe=True turns execution errors into SQLResponse(ok=False). In an active transaction, a safe failure marks the transaction failed and the context rolls back unless the caller explicitly handles it with rollback(). In execute_many(..., safe=True), the first failed statement stops the batch and rolls back by default; autocommit=True opts into best-effort per-statement commits.
• SQL healing is intentionally future work and tracked separately. The current API returns or raises the original database error instead of calling an LLM repair path.

​

4. Use the Direct Database Surface

import heavenbase as hb

db = hb.Database(provider="sqlite", database="workspace.db")
db.execute("create table if not exists items (id text primary key, name text)")
db.execute("insert into items (id, name) values (:id, :name)", {"id": "a", "name": "alpha"})
db.execute("insert into items (id, name) values (?, ?)", ("b", "beta"))

db.tables()
db.columns("items")
db.n_rows("items")

rows = db.execute("select id, name from items", readonly=True)
rows.to_dicts(columns=["id"])
rows.table_display()

db.execute("with input(id) as (select 'c') select id from input", readonly=True)
db.execute("select count(*) from items", readonly=None)

db = hb.Database(provider="postgres", database="workspace_demo")
db.execute("select 1")  # first engine access may autocreate the database
db.drop_database(force=True)

from sqlalchemy import select

db.engine
db.orm_execute(select(my_table.c.id), readonly=True)

rows.to_dicts(columns=["missing"], check=False)
hb.table_display(rows, columns=["name"])

​

Summary

• Workspace SQL Backends own routed Entity storage; hb.Database owns direct SQL workflows.
• Fourteen concrete SQL-family selectors cover embedded, self-hosted, and managed protocols.
• Provider identity remains distinct even when two routes share a wire protocol.

​

Further Exploration