abstract_database
Lazy, environment-driven PostgreSQL connection management with multi-database support and table/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 and PostgreSQL (uses psycopg[binary]).
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:
| Variable | Purpose |
|---|---|
ABSTRACT_DB_ENV_PATH |
Path to the .env file to read. |
ABSTRACT_DB_TABLES_DIR |
Directory holding table-config JSON. |
ABSTRACT_DB_TYPE |
Default db-type label (default database). |
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()
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
connectionManagernever 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 behindensure_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 aConnectionErrorwith the underlying cause instead of silently returningNoneand breaking three calls later.
License
MIT.
1 maintainer
Metadata
1 maintainer
Release files for abstract-database 0.0.2.199
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| abstract_database-0.0.2.199.tar.gz | 74.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| abstract_database-0.0.2.199-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 166.6 kB
Release files / abstract_database-0.0.2.199.tar.gz
| Download URL | abstract_database-0.0.2.199.tar.gz |
|---|---|
| Size | 74.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b41ab752a987e4c3f693cd0f41a971f521ff3b3b971dd9e9e05ad06953c33e23
|
|
BLAKE2b-256 checksum How to use checksums |
8ffcaacc6e34b9faee5f3f0bf3eaca818c9cf35ecd84526ed5a008b59e37739e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / abstract_database-0.0.2.199-py3-none-any.whl
| Download URL | abstract_database-0.0.2.199-py3-none-any.whl |
|---|---|
| Size | 92.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e9fb9e1d5c519d058f5e0ae256b09239bac0a34a9b445fa250b121641fd70817
|
|
BLAKE2b-256 checksum How to use checksums |
2ec02a6107d2e98847145ea88e4292f13a0fb4c8bfb0528fe1adee69ee3b3a04
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
