db-git 0.1.1__tar.gz → 0.3.0__tar.gz

db_git-0.3.0/.github/workflows/docs.yml

@@ -0,0 +1,61 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - requirements-docs.txt
+      - .github/workflows/docs.yml
+  pull_request:
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - requirements-docs.txt
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+      - name: Install documentation tools
+        run: python -m pip install -r requirements-docs.txt
+      - name: Validate and build documentation
+        run: python -m mkdocs build --strict
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+      - name: Deploy documentation
+        id: deployment
+        uses: actions/deploy-pages@v4

db_git-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,79 @@
+name: release
+
+on:
+  workflow_run:
+    workflows: [test]
+    branches: [main]
+    types: [completed]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.workflow_run.head_branch }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    name: semantic release
+    runs-on: ubuntu-latest
+    if: github.event.workflow_run.conclusion == 'success'
+    permissions:
+      contents: write
+      id-token: write
+    outputs:
+      released: ${{ steps.release.outputs.released || 'false' }}
+    steps:
+      - name: Checkout release branch
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.workflow_run.head_branch }}
+          fetch-depth: 0
+
+      - name: Reset to tested commit
+        run: git reset --hard "${{ github.event.workflow_run.head_sha }}"
+
+      - name: Semantic version release
+        id: release
+        uses: python-semantic-release/python-semantic-release@v10.5.3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          git_committer_name: "github-actions"
+          git_committer_email: "actions@users.noreply.github.com"
+
+      - name: Upload distributions to GitHub Release
+        if: steps.release.outputs.released == 'true'
+        uses: python-semantic-release/publish-action@v10.5.3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ steps.release.outputs.tag }}
+
+      - name: Upload distributions artifact
+        if: steps.release.outputs.released == 'true'
+        uses: actions/upload-artifact@v7
+        with:
+          name: distribution-artifacts
+          path: dist
+          if-no-files-found: error
+
+  publish:
+    name: publish to PyPI
+    runs-on: ubuntu-latest
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    permissions:
+      actions: read
+      contents: read
+      id-token: write
+    steps:
+      - name: Download distributions artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: distribution-artifacts
+          path: dist
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          print-hash: true

{db_git-0.1.1 → db_git-0.3.0}/.github/workflows/test.yml

@@ -10,14 +10,42 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  lint:
+    name: ruff
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pipx install nox
+      - run: nox -s lint
+
+  types:
+    name: mypy
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pipx install nox
+      - run: nox -s types
+
   unit:
     name: unit (${{ matrix.python }})
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     strategy:
       matrix:
         python: ["3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
@@ -29,14 +57,15 @@ jobs:
 
   integration:
     name: integration (py${{ matrix.python }}, pg${{ matrix.postgres }})
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    needs: [lint, types, unit]
     strategy:
       fail-fast: false
       matrix:
         python: ["3.12", "3.13"]
         postgres: ["13", "14", "15", "16", "17"]
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
@@ -52,30 +81,26 @@ jobs:
       - run: pipx install nox
       - run: nox -s "integration-${{ matrix.python }}(pg_image='postgres:${{ matrix.postgres }}')"
 
-  types:
-    name: mypy
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: astral-sh/setup-uv@v7
-        with:
-          enable-cache: true
-      - uses: actions/setup-python@v6
-        with:
-          python-version: "3.12"
-      - run: pipx install nox
-      - run: nox -s types
-
-  lint:
-    name: ruff
-    runs-on: ubuntu-latest
+  mysql:
+    name: mysql (py${{ matrix.python }}, mysql${{ matrix.mysql }})
+    runs-on: ubuntu-24.04
+    needs: [lint, types, unit]
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13"]
+        mysql: ["8.0", "8.4"]
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
       - uses: actions/setup-python@v6
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python }}
+      - name: Install Oracle MySQL clients
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y mysql-client
       - run: pipx install nox
-      - run: nox -s lint
+      - run: nox -s "mysql-${{ matrix.python }}(mysql_image='mysql:${{ matrix.mysql }}')"

{db_git-0.1.1 → db_git-0.3.0}/.gitignore

@@ -8,3 +8,6 @@ wheels/
 
 # Virtual environments
 .venv
+
+# Generated documentation
+/site/

{db_git-0.1.1 → db_git-0.3.0}/.pre-commit-config.yaml

@@ -13,7 +13,7 @@ repos:
       - id: check-added-large-files
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.15
+    rev: v0.15.18
     hooks:
       - id: ruff-check
         args: [--fix]

db_git-0.3.0/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!-- version list -->
+
+## v0.3.0 (2026-09-26)
+
+### Bug Fixes
+
+- Align database clients and validate release CI locally
+  ([`56600a6`](https://github.com/earthcomfy/db-git/commit/56600a6b43873c44faa619275f2f6f7f2cd424c7))
+
+- Prevent unsafe database switches and branch name collisions
+  ([`8ae904e`](https://github.com/earthcomfy/db-git/commit/8ae904ed79d7862d5994dcac065be4bde6108fce))
+
+### Build System
+
+- **deps**: Bump actions/checkout from 6 to 7 ([#10](https://github.com/earthcomfy/db-git/pull/10),
+  [`8a7221a`](https://github.com/earthcomfy/db-git/commit/8a7221ad4b248c15a93349c1d58f7a965e9b65f0))
+
+- **deps**: Bump https://github.com/astral-sh/ruff-pre-commit
+  ([#11](https://github.com/earthcomfy/db-git/pull/11),
+  [`6ff3495`](https://github.com/earthcomfy/db-git/commit/6ff34959ba9655d173f47279ae155d89eb12b41d))
+
+### Chores
+
+- Update changelog
+  ([`e135315`](https://github.com/earthcomfy/db-git/commit/e13531531c719345ebed747536a8594262b20ead))
+
+### Documentation
+
+- Add Material documentation site and Pages workflow
+  ([`b3c0b04`](https://github.com/earthcomfy/db-git/commit/b3c0b04f17adc895cd329c705859eb7eddaaa957))
+
+### Features
+
+- Add application runner and explicit branch database sources
+  ([`eab7f27`](https://github.com/earthcomfy/db-git/commit/eab7f27cf65e58c8fd7ebdad7779a2590c256003))
+
+- Add checkpoint history and recoverable retention
+  ([`3b495b8`](https://github.com/earthcomfy/db-git/commit/3b495b83cf51d207b20d1b4a6bd11d5ed8735395))
+
+- Add doctor diagnostics and preserve PostgreSQL connection options
+  ([`6abedd2`](https://github.com/earthcomfy/db-git/commit/6abedd24770a83f3635a5d2751fea3ba70a5d25b))
+
+- Add MySQL databases, shared snapshots, and recoverable generations
+  ([`124a63a`](https://github.com/earthcomfy/db-git/commit/124a63a8f96742eb8c757aff1b7104976e852cfd))
+
+- Add recoverable database and snapshot operations
+  ([`51ace0f`](https://github.com/earthcomfy/db-git/commit/51ace0fc1da9169d00c39aa39737a3860e4c5d31))
+
+- Add SQLite per-branch databases and recoverable file generations
+  ([`a42584c`](https://github.com/earthcomfy/db-git/commit/a42584c63ea7999c13acdcf907af3a14063861f4))
+
+- Support Git worktrees with shared database ownership
+  ([`701dc12`](https://github.com/earthcomfy/db-git/commit/701dc12c99c47e5d43a98bd4cd63bf805789a86b))
+
+
+## v0.2.0 (2026-06-08)
+
+### Added
+
+- Introduced a new command `db-git url` that outputs the database connection URL
+  for the current or specified branch.
+
+### Changed
+
+- Enhanced `config.py` to provide clearer documentation for the database URL configuration.
+
+## v0.1.1 (2026-06-01)
+
+### Changed
+
+- Renamed project, CLI, package imports, configuration files, environment
+  variables, hook metadata, and local state paths to `db-git`.
+
+## v0.1.0 (2026-05-22)
+
+### Added
+
+- Initial `db-git` command-line interface.
+- Git `post-checkout` hook installation, removal, enable, disable, and dispatch
+  support.
+- Shared database mode for saving and restoring branch-specific snapshots.
+- Per-branch database mode for creating one database per git branch.
+- PostgreSQL backend with `template` and `pgdump` snapshot strategies.
+- Active connection handling with `terminate` and `fail` policies.
+- Manual commands for `save`, `restore`, `create`, `reset`, `list`, `status`,
+  and `prune`.
+- Snapshot metadata and local state storage under `.git/db-git/`.
+- Unit, integration, and end-to-end tests for CLI, storage, git hooks,
+  PostgreSQL strategies, and branch database workflows.
+- Nox sessions, Ruff linting/format checks, mypy type checking, pre-commit
+  hooks, Dependabot, and GitHub Actions CI.

db_git-0.3.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: db-git
+Version: 0.3.0
+Summary: Keep your database in sync with your git branches.
+Project-URL: Homepage, https://github.com/earthcomfy/db-git
+Project-URL: Documentation, https://earthcomfy.github.io/db-git/
+Project-URL: Repository, https://github.com/earthcomfy/db-git
+Project-URL: Issues, https://github.com/earthcomfy/db-git/issues
+Project-URL: Changelog, https://github.com/earthcomfy/db-git/blob/main/CHANGELOG.md
+Author: Hana Belay
+License-Expression: MIT
+License-File: LICENSE
+Keywords: branching,cli,database,developer-tools,git,migrations,postgresql,snapshot
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: psycopg[binary]>=3.3.0
+Requires-Dist: rich>=14.0.0
+Requires-Dist: tomlkit>=0.14.0
+Requires-Dist: typer>=0.24.1
+Provides-Extra: mysql
+Requires-Dist: pymysql[rsa]>=1.1.1; extra == 'mysql'
+Description-Content-Type: text/markdown
+
+# db-git
+
+[![CI](https://github.com/earthcomfy/db-git/actions/workflows/test.yml/badge.svg)](https://github.com/earthcomfy/db-git/actions/workflows/test.yml)
+[![Python](https://img.shields.io/pypi/pyversions/db-git.svg)](https://pypi.org/project/db-git/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/earthcomfy/db-git/blob/main/LICENSE)
+
+Keep your database in sync with your Git branches.
+
+`db-git` is a developer tool for schema migrations, seed data, experimental
+features, and branch switching during reviews. Its `post-checkout` hook keeps
+your local database aligned with the branch you are working on.
+
+**[Documentation](https://earthcomfy.github.io/db-git/)** ·
+[Browse docs in GitHub](https://github.com/earthcomfy/db-git/tree/main/docs) ·
+[Release notes](https://github.com/earthcomfy/db-git/blob/main/CHANGELOG.md)
+
+## Features
+
+- Automatic database handling on Git checkout.
+- **Shared mode:** save and restore branch-specific snapshots.
+- **Per-branch mode:** keep an independent database for each branch.
+- Launch applications and migrations with `db-git run -- <command>`.
+- Named checkpoints, history, and explicit retention in shared mode.
+- Git worktrees in per-branch mode.
+- Read-only diagnostics and recoverable database operations.
+- Checkout still completes if database handling fails, with recovery guidance.
+
+## Supported databases
+
+| Database | Modes | Strategy |
+| --- | --- | --- |
+| PostgreSQL | Shared and per-branch | `template` or `pgdump` |
+| MySQL 8.0 / 8.4 | Shared and per-branch | `mysqldump` |
+| SQLite | Per-branch | Online backup |
+
+See the [database guides](https://earthcomfy.github.io/db-git/#choose-your-database)
+for required privileges, client tools, and engine-specific limitations.
+
+## Quick start
+
+Requires Python 3.12+, Git, and an existing local development database.
+For PostgreSQL:
+
+```bash
+uv tool install db-git # or pip install db-git
+
+# Run inside your application's Git repository.
+db-git init --database-url postgresql://localhost/myapp --mode per-branch
+
+git checkout -b feature/auth
+db-git run -- npm run dev # replace with your application's command
+```
+
+Install the hook during initialization. Your application must read `DATABASE_URL`;
+restart it through `db-git run` after switching branches. The default branch keeps
+the seed database, while other branches receive separate copies.
+
+For MySQL, install `uv tool install 'db-git[mysql]'` and follow the
+[MySQL guide](https://github.com/earthcomfy/db-git/blob/main/docs/databases/mysql.md).
+For SQLite, follow the [SQLite guide](https://github.com/earthcomfy/db-git/blob/main/docs/databases/sqlite.md).
+
+## Learn more
+
+- [Choose shared or per-branch mode](https://github.com/earthcomfy/db-git/blob/main/docs/concepts/modes.md)
+- [Run applications and migrations](https://github.com/earthcomfy/db-git/blob/main/docs/guides/applications.md)
+- [Work with Git worktrees](https://github.com/earthcomfy/db-git/blob/main/docs/guides/worktrees.md)
+- [Save checkpoints and inspect history](https://github.com/earthcomfy/db-git/blob/main/docs/guides/checkpoints.md)
+- [Command reference](https://github.com/earthcomfy/db-git/blob/main/docs/reference/commands.md)
+- [Configuration](https://github.com/earthcomfy/db-git/blob/main/docs/reference/configuration.md)
+- [Troubleshooting](https://github.com/earthcomfy/db-git/blob/main/docs/troubleshooting.md)
+- [Recovery](https://github.com/earthcomfy/db-git/blob/main/docs/guides/recovery.md)
+
+## Contributing
+
+See the [development guide](https://github.com/earthcomfy/db-git/blob/main/docs/contributing/development.md)
+for dependencies and tests, and the
+[documentation guide](https://github.com/earthcomfy/db-git/blob/main/docs/contributing/documentation.md)
+for local preview and publishing.
+
+## License
+
+[MIT](https://github.com/earthcomfy/db-git/blob/main/LICENSE)

db_git-0.3.0/README.md

@@ -0,0 +1,82 @@
+# db-git
+
+[![CI](https://github.com/earthcomfy/db-git/actions/workflows/test.yml/badge.svg)](https://github.com/earthcomfy/db-git/actions/workflows/test.yml)
+[![Python](https://img.shields.io/pypi/pyversions/db-git.svg)](https://pypi.org/project/db-git/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/earthcomfy/db-git/blob/main/LICENSE)
+
+Keep your database in sync with your Git branches.
+
+`db-git` is a developer tool for schema migrations, seed data, experimental
+features, and branch switching during reviews. Its `post-checkout` hook keeps
+your local database aligned with the branch you are working on.
+
+**[Documentation](https://earthcomfy.github.io/db-git/)** ·
+[Browse docs in GitHub](https://github.com/earthcomfy/db-git/tree/main/docs) ·
+[Release notes](https://github.com/earthcomfy/db-git/blob/main/CHANGELOG.md)
+
+## Features
+
+- Automatic database handling on Git checkout.
+- **Shared mode:** save and restore branch-specific snapshots.
+- **Per-branch mode:** keep an independent database for each branch.
+- Launch applications and migrations with `db-git run -- <command>`.
+- Named checkpoints, history, and explicit retention in shared mode.
+- Git worktrees in per-branch mode.
+- Read-only diagnostics and recoverable database operations.
+- Checkout still completes if database handling fails, with recovery guidance.
+
+## Supported databases
+
+| Database | Modes | Strategy |
+| --- | --- | --- |
+| PostgreSQL | Shared and per-branch | `template` or `pgdump` |
+| MySQL 8.0 / 8.4 | Shared and per-branch | `mysqldump` |
+| SQLite | Per-branch | Online backup |
+
+See the [database guides](https://earthcomfy.github.io/db-git/#choose-your-database)
+for required privileges, client tools, and engine-specific limitations.
+
+## Quick start
+
+Requires Python 3.12+, Git, and an existing local development database.
+For PostgreSQL:
+
+```bash
+uv tool install db-git # or pip install db-git
+
+# Run inside your application's Git repository.
+db-git init --database-url postgresql://localhost/myapp --mode per-branch
+
+git checkout -b feature/auth
+db-git run -- npm run dev # replace with your application's command
+```
+
+Install the hook during initialization. Your application must read `DATABASE_URL`;
+restart it through `db-git run` after switching branches. The default branch keeps
+the seed database, while other branches receive separate copies.
+
+For MySQL, install `uv tool install 'db-git[mysql]'` and follow the
+[MySQL guide](https://github.com/earthcomfy/db-git/blob/main/docs/databases/mysql.md).
+For SQLite, follow the [SQLite guide](https://github.com/earthcomfy/db-git/blob/main/docs/databases/sqlite.md).
+
+## Learn more
+
+- [Choose shared or per-branch mode](https://github.com/earthcomfy/db-git/blob/main/docs/concepts/modes.md)
+- [Run applications and migrations](https://github.com/earthcomfy/db-git/blob/main/docs/guides/applications.md)
+- [Work with Git worktrees](https://github.com/earthcomfy/db-git/blob/main/docs/guides/worktrees.md)
+- [Save checkpoints and inspect history](https://github.com/earthcomfy/db-git/blob/main/docs/guides/checkpoints.md)
+- [Command reference](https://github.com/earthcomfy/db-git/blob/main/docs/reference/commands.md)
+- [Configuration](https://github.com/earthcomfy/db-git/blob/main/docs/reference/configuration.md)
+- [Troubleshooting](https://github.com/earthcomfy/db-git/blob/main/docs/troubleshooting.md)
+- [Recovery](https://github.com/earthcomfy/db-git/blob/main/docs/guides/recovery.md)
+
+## Contributing
+
+See the [development guide](https://github.com/earthcomfy/db-git/blob/main/docs/contributing/development.md)
+for dependencies and tests, and the
+[documentation guide](https://github.com/earthcomfy/db-git/blob/main/docs/contributing/documentation.md)
+for local preview and publishing.
+
+## License
+
+[MIT](https://github.com/earthcomfy/db-git/blob/main/LICENSE)

db_git-0.3.0/docs/concepts/modes.md

@@ -0,0 +1,26 @@
+# Choose a mode
+
+## Shared Mode
+
+PostgreSQL shared mode keeps the name from the configured `database_url`.
+MySQL shared mode selects a fresh working database URL on restore; restart apps
+through `db-git run` afterward.
+
+Use this when:
+
+- You want one active working database and branch-specific snapshots
+- You restart applications after restoring or switching branches
+
+## Per-Branch Mode
+
+Per-branch mode creates a separate database for each branch. The configured
+default branch keeps the original database name and acts as the seed database.
+
+Use this when:
+
+- You want branch databases to persist independently
+- You prefer creating new databases over repeatedly restoring one shared
+  database
+
+SQLite supports only per-branch mode. Multiple Git worktrees also require
+per-branch mode. See [worktrees](../guides/worktrees.md) for setup and shared state.

db_git-0.3.0/docs/contributing/development.md

@@ -0,0 +1,67 @@
+# Development
+
+Install dependencies:
+
+```bash
+uv sync --group dev
+```
+
+Run checks:
+
+```bash
+uv run ruff check .
+uv run mypy src
+uv run pytest tests/unit tests/sqlite
+```
+
+For MySQL development, install its optional driver and Oracle MySQL clients, then
+run the Docker-backed workflow and recovery tests against each supported server:
+
+```bash
+uv sync --group dev --extra mysql
+DB_GIT_TEST_MYSQL_IMAGE=mysql:8.0 uv run pytest tests/mysql
+DB_GIT_TEST_MYSQL_IMAGE=mysql:8.4 uv run pytest tests/mysql
+```
+
+CI runs both MySQL workflows, stored-object cloning, and recovery tests on
+Python 3.12 and 3.13 against MySQL 8.0 and 8.4.
+
+Run the full nox suite:
+
+```bash
+nox
+```
+
+## Run the CI matrix locally
+
+To catch differences between macOS tools and the Linux CI environment, use the
+local runner from the repository root with Docker running:
+
+```bash
+python3 scripts/ci/local.py
+```
+
+It builds an Ubuntu 24.04 image, includes uncommitted source changes, and runs
+the same nox sessions for Python 3.12/3.13, PostgreSQL 13–17, and MySQL 8.0/8.4.
+PostgreSQL sessions select their matching client binaries; MySQL uses Ubuntu's
+Oracle MySQL 8.0 clients. The checkout and its virtual environments stay untouched.
+Logs and a JSON result summary are written to the temporary directory printed
+by the runner. The command exits nonzero when a session fails.
+
+The default is one job at a time with an x86-64 Linux test runner. GitHub gives
+each matrix job its own machine; local jobs share Docker's CPU and memory with
+your other containers. On Apple Silicon, emulation adds overhead, and concurrent
+database suites can encounter transient connection failures. Select a specific
+session, or increase concurrency when your machine has sufficient resources:
+
+```bash
+python3 scripts/ci/local.py --jobs 4
+python3 scripts/ci/local.py --session "integration-3.12(pg_image='postgres:15')"
+```
+
+The runner uses the local Docker socket to create disposable test databases.
+It validates test jobs, not GitHub authentication, caching, Pages deployment,
+or PyPI publication. Database image architecture follows the Docker daemon;
+the hosted runner's exact package patch versions may also differ over time.
+
+See [documentation development](documentation.md) to preview and publish the site.