abstract_database

SQLite and PostgreSQL stores, portable schemas, and lazy connection/query helpers.

abstract_database is the connection layer of the Abstract Secure Backend stack. It resolves connection settings from your environment, manages connections to one or many databases, and provides thin helpers for tables and queries — without ever forcing a database connection before you actually need one.

Where this fits

abstract-securefiles   React/TypeScript UI components
abstract_logins        Flask blueprints: auth + secure files
abstract_queries       Domain query managers (users, uploads, ...)
abstract_database  <-- you are here: lazy PostgreSQL connection + helpers
abstract_security      Env loading, hashing, tokens, utilities

Dependencies flow downward; nothing reaches back up.

Install

pip install abstract_database

Requires Python ≥ 3.11. PostgreSQL APIs use psycopg[binary] and an existing server. The portable SQLite API uses Python’s standard library; no server is needed.

Configuration

Connection settings are read from the environment, so the package is portable across machines. Per-database keys follow <DBNAME>_<DBTYPE>_<FIELD> (upper-cased), or you can supply a single URL:

ABSTRACT_DATABASE_USER=app_user
ABSTRACT_DATABASE_PASSWORD=...
ABSTRACT_DATABASE_HOST=127.0.0.1
ABSTRACT_DATABASE_PORT=5432
ABSTRACT_DATABASE_DBNAME=app
# or:
ABSTRACT_DATABASE_URL=postgresql://app_user:...@127.0.0.1:5432/app

Optional locations:

Quickstart

from abstract_database import connectionManager, get_cur_conn

# Constructing a manager does NOT open a connection.
db = connectionManager(dbName="app", dbType="database")

# The connection opens on first use; failures raise a clear ConnectionError.
cur, conn = get_cur_conn()           # RealDict cursor + connection
cur.execute("SELECT 1;")
print(cur.fetchone())
conn.close()

Portable schemas: SQLite or PostgreSQL

The new opt-in Database API creates either backend from one JSON/Python schema and provides shared CRUD, transactions/savepoints, and versioned additive upgrades. Choose the backend with a connection URL. Existing PostgreSQL APIs remain unchanged; this feature does not migrate application databases.

from abstract_database import Database

db = Database("sqlite:///catalog.sqlite3")
# Or: Database("postgresql://app_user@db-host:5432/catalog")
# db.ensure_schema(schema_dict)

See PORTABLE_DATABASE.md for the schema format, complete examples, supported migrations, and the boundaries of SQL portability.

Hugpy model database viewer (development utility)

The repository has a standalone, read-only browser for inspecting Hugpy's PostgreSQL model database. It opens on discovery_models, supports searching all columns, sorting by clicking column headers, and paging through results. Selecting a row shows an expandable, syntax-colored JSON tree with controls to expand or collapse nested values. The app-specific script is outside the abstract_database package and uses the package's generic DatabaseBrowser API.

The viewer runs as a persistent solcatcher user service on the Hugpy server and is proxied by nginx. On the LAN or WireGuard, open https://dev.hugpy.ai/modeldb/. Nginx restricts this route to LAN and WireGuard addresses.

The utility reads Hugpy's connection settings from /srv/hugpy/etc/hugpy-db.env and opens http://127.0.0.1:8765/.

Multiple databases

users = connectionManager(dbName="app",      dbType="database")
audit = connectionManager(dbName="auditlog", dbType="database")
# Distinct, independently-configured managers — no global clobbering.

Design notes

• Lazy by default. Constructing a connectionManager never touches the database. The connection opens on first real use, so importing the package or booting an app never blocks (or fails) on an unreachable database. Table setup is deferred behind ensure_inserts().
• Multi-DB safe. Managers are cached by connection identity (name / type / env-path / url) rather than a single global singleton, so several databases coexist cleanly. A no-argument connectionManager() still maps to one shared default.
• Failures are visible. connect_db() raises a ConnectionError with the underlying cause instead of silently returning None and breaking three calls later.

License

MIT.