Overview

Two packages share the name db

There are two distinct packages both named db, in different workspaces, at different stages of maturity:

1. packages/db (this page’s nominal subject) — a root-UV-workspace member, depends on utils. Its modules (conn.py, auth.py, PostgresDBHelper.py) are almost entirely commented out — this package is effectively a scaffold/placeholder, not in active use.
2. orchestration/include/db — a separate package, also named db, but living in orchestration/’s own UV workspace ([tool.uv.workspace] members = ["include/mx_fuels_reporting", "include/db"]) and consumed by orchestration/pyproject.toml (db = { workspace = true }). This one is actively used: it defines the SQLModel tables backing the MX Fuels reporting schema, Alembic migrations, and bulk-insert persistence helpers, and is imported by DAGs (db_migrations.py, db_rollback.py) and orchestration/dags/mx_fuels_reporting.py.

In practice, “the db package” almost always means orchestration/include/db. The rest of this page documents that one; the packages/db scaffold is noted here for completeness so it isn’t mistaken for the real thing.

What it provides (orchestration/include/db)

• models/ — SQLModel table definitions: Company, CompanyPermit, CompanyUser, DashboardUser, Permit, ReportPeriod, Purchase, Sale, Inventory, Import, Export, ReportJob/JobStatus. (Import is loaded via importlib since import is a reserved keyword.)
• alembic/ — migration environment (env.py, versions/) and alembic.ini, run via the db_migrations/db_rollback Airflow DAGs. See Orchestration → Database & Migrations for the migration workflow.
• persist.py — bulk-insert helpers for writing cleaned Polars DataFrames to PostgreSQL from Airflow tasks, e.g.:

  from airflow.providers.postgres.hooks.postgres import PostgresHook
  from db.persist import persist_report
  
  hook = PostgresHook(postgres_conn_id="my-pg")
  engine = create_engine(hook.get_uri())
  persist_report(engine=engine, ...)

• migrate.py — migration entry point used by the Airflow DAGs.

Dependencies: alembic, psycopg[binary], sqlmodel, uuid-utils. Built with uv_build, not hatchling.

Connection & identity

Connections use PostgresHook/SQLAlchemy engines configured via Airflow connections, ultimately backed by the same Azure AD-token authentication model described in Architecture → Identity & Security (developer identity locally via AZURE_USERNAME/AZURE_PG_TOKEN, service identity in production).

The packages/db scaffold

packages/db (root workspace, packages/db/pyproject.toml, depends on utils) contains conn.py (commented-out SQLAlchemy URL builder), auth.py (commented-out Key Vault-backed credential fetcher), and PostgresDBHelper.py (commented-out psycopg context-manager helper) — all disabled. If this package is revived for use outside orchestration/, update this page accordingly; until then, treat orchestration/include/db as the source of truth for database access patterns.