Metadata-Version: 2.4
Name: abstract_database
Version: 0.0.2.201
Summary: SQLite and PostgreSQL stores, portable schemas, and lazy connection/query helpers.
Home-page: https://github.com/AbstractEndeavors/abstract_database
Author: putkoff
Author-email: partners@abstractendeavors.com
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: psycopg[binary]
Provides-Extra: full
Requires-Dist: pillow; extra == "full"
Requires-Dist: abstract_apis; extra == "full"
Requires-Dist: abstract_gui; extra == "full"
Requires-Dist: abstract_math; extra == "full"
Requires-Dist: abstract_security; extra == "full"
Requires-Dist: asyncpg; extra == "full"
Requires-Dist: abstract_utilities; extra == "full"
Requires-Dist: numpy; extra == "full"
Requires-Dist: pandas; extra == "full"
Requires-Dist: sqlalchemy; extra == "full"
Requires-Dist: pyyaml; extra == "full"
Requires-Dist: requests; extra == "full"
Requires-Dist: flask; extra == "full"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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

```bash
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:

```ini
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

```python
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.

```python
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](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

```python
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.
