h2hdb

h2hdb is the database and coordination core for the H2HDB multi-repository system. It owns the SQLite/MariaDB schema, bounded transactional workflows, and backend-neutral application facades used by ingest, download, Komga, and OPDS consumers.

It deliberately does not scan files, parse galleryinfo.txt, manipulate images, choose filesystem paths, serve HTTP, serialize OPDS documents, or depend on hbrowser. Those responsibilities belong to consumer adapters and sibling packages.

Greenfield BCNF schema

The current schema is a clean epoch-2 design:

  • 125 catalog data-plane relations, each checked as BCNF.
  • 25 declared decompositions, each checked as lossless and dependency-preserving.
  • 76 operational control-plane relations, each checked as BCNF. This count includes the epoch-control relation; the generated CREATE-only provider owns the other 75.
  • One generated physical schema for SQLite and MariaDB, with backend-specific SQL rendered from the same closed-world manifests.

The logical sources of truth are verification/schema/catalog.toml and verification/schema/operational.toml. They declare functional dependencies, keys, decompositions, bootstrap facts, and semantic obligations. Deterministic generators derive the physical manifests, Lean schema proofs, and the wheel-resident runtime provider. Generated SQL is not a second schema-authoring surface.

This is a greenfield cutover. There is no v1-v7 upgrade or adoption path, no compatibility view, and no dual write. A previous or foreign database must be replaced with an empty database and rebuilt from source data.

Schema epoch

The active identity is epoch=2, schema_version=1. The singleton h2hdb_schema_epoch row binds the exact generated DDL, bootstrap-seed, and semantic-obligation manifests into one durable checksum.

Initialization follows a fail-closed state machine:

  1. A truly empty database is admitted and recorded as BUILDING.
  2. Idempotent generated DDL and bootstrap rows are applied in deterministic slices.
  3. The complete object set, bootstrap facts, and activation obligations are validated.
  4. The exact manifest is atomically marked READY.

If construction is interrupted, rerunning migrate may resume only the same checksum-matching BUILDING epoch. A READY rerun validates the exact current epoch. Drift, an unknown control residue, or any other non-empty database is rejected without adoption or destructive repair.

The command name migrate is retained as the administration interface, but it constructs or resumes this single manifest-bound greenfield epoch; it does not run numbered historical migrations.

Core responsibilities

  • MariaDB and SQLite connectors, read/write transactions, and connector-enforced read-only access.
  • Manifest-bound schema construction, full validation, and O(1) readiness checks.
  • Normalized catalog identities, immutable revisions, publication preparation, and revision-pinned reads.
  • Durable download-to-ingest handoff, exact attempt/lease fencing, and coordinated completion.
  • Bounded source-build, analysis, publication, cleanup, maintenance-gate, canonical-value, event, and hash-cache workflows.

Cross-table workflows use one connector and one managed transaction. Mutable authority is represented by normalized heads, generations, leases, seals, and receipts rather than by caller-supplied counts, cursors, digests, names, or tokens. Long-running work advances through bounded, replayable batches; pointer publication validates sealed scalar state in a short transaction.

Installation

This repository uses a src layout and an independent uv environment. It is not part of a uv workspace, and uv.lock is intentionally ignored.

uv venv --python 3.14
uv pip install -e ".[dev]"

Rebuild the local environment after toolchain changes with:

./scripts/rebuild-env.sh

Configuration

{
  "database": {
    "sql_type": "sqlite",
    "database": "/var/lib/h2hdb/catalog.sqlite3",
    "access_mode": "read-write"
  },
  "maintenance": {
    "optimize_enabled": true
  },
  "logger": {
    "level": "INFO",
    "file": null
  }
}

For MariaDB, also set host, port, user, password, and database. Read-only consumers should use "access_mode": "read-only" and a database account limited to the metadata/read privileges required by schema validation and application reads.

JSON string values consisting exactly of ${ENV_NAME} are resolved from the process environment before validation. Variable names must match [A-Za-z_][A-Za-z0-9_]*; missing or invalid variables stop startup without including their values in the error. Inline interpolation such as db-${INSTANCE} is deliberately unsupported, and unknown JSON fields are rejected.

Schema administration

The CLI exposes exactly three operations:

uv run --no-sync python -m h2hdb migrate --config config.json
uv run --no-sync python -m h2hdb check --config config.json
uv run --no-sync python -m h2hdb ready --config config.json

Choose the operation from database state:

Database state or caller Operation
Truly empty database Run migrate to construct epoch 2/version 1
Matching interrupted BUILDING epoch Rerun migrate to resume
Matching READY epoch Run read-only check for the full audit
Consumer startup Run check; never initialize schema
Frequent readiness probe Run the O(1) read-only ready check
Previous, foreign, or drifted schema Create a new empty database and rebuild

The default generated provider must resolve every required runtime validator and recurring writer binding before it opens or mutates a database. check holds a read transaction while validating the complete READY schema; ready validates only the exact epoch/version/manifest marker.

Applications can use the same administration boundary directly:

from h2hdb import VNextDatabaseAdminFacade, load_config

config = load_config("config.json")
admin = VNextDatabaseAdminFacade(config)
admin.initialize()       # deployment init job only
admin.check()            # full read-only audit
admin.check_readiness()  # lightweight probe

Public application API

Consumers should import the public facades and immutable domain values from h2hdb; they must not import connector, repository, generated-schema, or table implementation modules.

Revision-pinned catalog reads use open_database, which performs the full manifest-bound READY audit before returning a VNextCatalogFacade:

from h2hdb import load_config, open_database

catalog = open_database(load_config("readonly-config.json"))
revision = catalog.get_catalog_revision()
page = catalog.list_publications(
    revision=revision,
    offset=0,
    limit=50,
    require_artifact=True,
)
publication = catalog.get_publication("42", revision=revision)

Download request creation, bounded listing, and exact-request completion use VNextDownloadQueueFacade:

from h2hdb import VNextDownloadQueueFacade, load_config

queue = VNextDownloadQueueFacade(load_config("writer-config.json"))
request = queue.request_download(42, "https://example.invalid/gallery/42")
pending = queue.list_download_requests(limit=100)
queue.complete_download_request(request)

Each facade call owns a fresh connection and one bounded read or write transaction. Repository methods that accept connectors or units of work remain internal coordination surfaces.

Deliberate current limits

  • A nonblank catalog search query fails closed until a normalized, revision-pinned search index is part of the manifest and reader contract.
  • The durable contract needed to derive CatalogPublication.redownload_required for a pinned revision is not closed. Readers therefore do not infer it from transient operational rows.
  • Core defines the typed artifact-preparation/storage boundary, but a concrete filesystem or object-storage adapter and complete public ingest orchestration are not shipped here; the consumer integration must supply them.

Verification

The schema workflow and implementation checks are:

uv run --no-sync python scripts/verify-formal.py coverage --validate-only
uv run --no-sync python scripts/verify-formal.py schema
uv run --no-sync python scripts/verify-formal.py lean
uv run --no-sync black --check src tests scripts
uv run --no-sync ruff check src tests scripts
uv run --no-sync mypy src tests scripts
uv run --no-sync pytest
uv run --no-sync python -m build

verify-formal.py schema checks manifest validity and generator drift for the physical, Lean, operational-refinement, and runtime-provider artifacts. The Lean target proves the declared closed-world BCNF and decomposition statements under their explicit assumptions; it does not by itself prove SQL/runtime refinement.

coverage --validate-only validates the evidence-index structure while still reporting unresolved production blockers. Plain coverage is the strict production-readiness gate and must remain nonzero until every reported blocker has real evidence. Schema and Lean success must not be presented as strict coverage success.

SQLite tests run locally. Set H2HDB_TEST_MARIADB=1 with a working Docker daemon to include MariaDB testcontainer cases.

The distribution boundary can be checked with:

uv run --no-sync python scripts/build-and-verify-distributions.py \
  --output-directory /path/to/empty/output-directory

It builds in a fresh temporary directory, verifies the wheel, and confirms that the installed CLI exposes only migrate, check, and ready.

Local release gate

Install the versioned Git hooks once per clone:

./scripts/install-git-hooks.sh

The installer refuses to disable an existing hooks path or executable legacy hook; compose those hooks explicitly before switching this clone to .githooks. VS Code's built-in Git and command-line Git honor the installed hooks. GitHub web edits and clones where the installer has not run do not.

Ordinary commits and merges do not run the expensive release suite. When the staged project.version in pyproject.toml increases, the pre-commit or pre-merge-commit hook requires the candidate tree to have no unstaged or untracked files and automatically runs the complete local release gate:

  • Black, Ruff, and mypy;
  • coverage-contract and generated-schema drift checks;
  • Lean proofs and the required small TLC profiles;
  • the complete SQLite and MariaDB test suite; and
  • the installed-distribution boundary check.

The gate requires the development environment, Docker for MariaDB, the Lean toolchain declared by lean-toolchain, and either host Java or Docker for TLC. Deep TLC remains an explicit manual check. A successful gate writes a local, non-versioned receipt under the repository's Git metadata and binds it to the exact staged tree and project version. The pre-push hook allows a version-increasing master push only when that receipt is valid, so retrying the same commit does not rerun the suite.

To verify an already committed clean HEAD explicitly, or to force a fresh verification, run:

uv run --no-sync python scripts/release-gate.py run
uv run --no-sync python scripts/release-gate.py run --refresh

GitHub-hosted formal verification is manual-only. The PyPI workflow rechecks the version transition, builds and smoke-tests the distributions, and publishes them; the expensive correctness evidence is owned by the local release gate.

Multi-repository development

The repositories remain independent projects. For an isolated editable-install smoke environment, run:

./scripts/rebuild-multirepo-integration.sh

See docs/multi-repo-deployment.md for the database ownership, initialization, and consumer-adapter deployment boundary.

License

GNU Affero General Public License v3 or later. See LICENSE.

Project links

Data verified by PyPI on Aug 15, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.31.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for kuan-lun from gravatar.com kuan-lun

Credits

Author: Kuan-Lun Wang

GitHub Statistics

Data verified by PyPI on Aug 15, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

GNU Affero General Public License v3 or later (AGPLv3+) (GNU Affero General Public License v3)

Requires

Python >=3.14

Provides Extra

dev

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

h2hdb-0.23.0.1.tar.gz (1.7 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

h2hdb-0.23.0.1-py3-none-any.whl (1.1 MB view details)

Uploaded Python 3

File details

Details for the file h2hdb-0.23.0.1.tar.gz.

File metadata

  • Download URL: h2hdb-0.23.0.1.tar.gz
  • Upload date:
  • Size: 1.7 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for h2hdb-0.23.0.1.tar.gz
Algorithm Hash digest
SHA256 94e5629d22a139b03647db35cb39cd269c9fe82b648071d2d74195de5ea05fd3
MD5 4a7177ab0c26203d54ecc2f7ae7ccf82
BLAKE2b-256 ecdc0eae52ec5a26bec84337c1ca6a2998fd5b4ed1d87f21082498a7b6b128f7

See more details on using hashes here.

Provenance

The following attestation bundles were made for h2hdb-0.23.0.1.tar.gz:

Publisher: publish.yml on Kuan-Lun/h2hdb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file h2hdb-0.23.0.1-py3-none-any.whl.

File metadata

  • Download URL: h2hdb-0.23.0.1-py3-none-any.whl
  • Upload date:
  • Size: 1.1 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for h2hdb-0.23.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 8d6e5945784b14183484d7bcbd9ea8fab8bfa21016799871bbf92c078f783c0d
MD5 0289cae59db02a9e8c30e284b6881828
BLAKE2b-256 f73a837946357fe83fc06793dc54b3a4745494e3b387c3b9c6df55e07bdb3824

See more details on using hashes here.

Provenance

The following attestation bundles were made for h2hdb-0.23.0.1-py3-none-any.whl:

Publisher: publish.yml on Kuan-Lun/h2hdb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.31.0

2 files

0.29.0

2 files

0.28.3

2 files

0.28.2

2 files

0.28.1

2 files

0.27.0

2 files

0.26.0

2 files

0.25.0

2 files

0.24.0

2 files

0.23.1

2 files

0.23.0.11

2 files

0.23.0.10

2 files

0.23.0.9

2 files

0.23.0.8

2 files

0.23.0.7

2 files

0.23.0.6

2 files

0.23.0.5

2 files

0.23.0.4

2 files

0.23.0.3

2 files

0.23.0.2

2 files

This release

0.23.0.1 This release

2 files

0.22.0.2

2 files

0.22.0.1

2 files

0.21.0.1

2 files

0.21.0.0

2 files

0.20.0.2

2 files

0.20.0.1

2 files

0.20.0.0

2 files

0.19.0.0

2 files

0.18.0.0

2 files

0.17.0.0

2 files

0.16.0.0

2 files

0.15.0.0

2 files

0.14.0.2

2 files

0.14.0.1

2 files

0.14.0.0

2 files

0.13.0.2

2 files

0.13.0.1

2 files

0.13.0.0

2 files

0.12.0.6

2 files

0.12.0.5

2 files

0.12.0.4

2 files

0.12.0.3

2 files

0.12.0.2

2 files

0.12.0.1

2 files

0.12.0.0

2 files

0.11.0.5

2 files

0.11.0.4

2 files

0.11.0.3

2 files

0.11.0.2

2 files

0.11.0.1

2 files

0.11.0.0

2 files

0.10.8.4

2 files

0.10.8.3

2 files

0.10.8.2

2 files

0.10.8.1

2 files

0.10.8.0

2 files

0.10.7.5

2 files

0.10.7.4

2 files

0.10.7.3

2 files

0.10.7.2

2 files

0.10.7.1

2 files

0.10.7.0

2 files

0.10.6.0

2 files

0.10.5.8

2 files

0.10.5.7

2 files

0.10.5.6

2 files

0.10.5.5

2 files

0.10.5.4

2 files

0.10.5.3

2 files

0.10.5.2

2 files

0.10.5.1

2 files

0.10.5.0

2 files

0.10.4.2

2 files

0.10.4.1

2 files

0.10.4.0

2 files

0.10.3.0

2 files

0.10.2.0

2 files

0.10.1.1

2 files

0.10.0.0

2 files

0.9.1.9

2 files

0.9.1.8

2 files

0.9.1.7

2 files

0.9.1.6

2 files

0.9.1.5

2 files

0.9.1.4

2 files

0.9.1.3

2 files

0.9.1.2

2 files

0.9.1.1

2 files

0.9.1.0

2 files

0.9.0.5

2 files

0.9.0.4

2 files

0.9.0.3

2 files

0.9.0.2

2 files

0.9.0.1

2 files

0.9.0.0

2 files

0.8.0.2

2 files

0.8.0.1

2 files

0.8.0.0

2 files

0.7.0.9

2 files

0.7.0.8

2 files

0.7.0.5

2 files

0.7.0.4

2 files

0.7.0.3

2 files

0.7.0.2

2 files

0.7.0.1

2 files

0.7.0.0

2 files

0.6.68.63

2 files

0.6.68.62

2 files

0.6.68.61

2 files

0.6.68.60

2 files

0.6.68.59

2 files

0.6.68.58

2 files

0.6.68.57

2 files

0.6.68.56

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page