db-git 0.1.0__tar.gz

db_git-0.1.0/.claude/settings.local.json

@@ -0,0 +1,26 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "mcp__context7__query-docs",
+      "Read(//private/tmp/git-hook-test/**)",
+      "Bash(chmod +x .git/hooks/post-checkout)",
+      "mcp__context7__resolve-library-id",
+      "Bash(uv run:*)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(gh search:*)",
+      "WebFetch(domain:pytest-postgresql.readthedocs.io)",
+      "WebFetch(domain:github.com)",
+      "Bash(gh api *)",
+      "Bash(curl -s \"https://api.github.com/repos/dbt-labs/dbt-core/contents/tests/functional\")",
+      "Bash(python3 -c \"import json,sys; [print\\(x['name']\\) for x in json.load\\(sys.stdin\\)]\")",
+      "Bash(curl -s \"https://api.github.com/repos/dolthub/dolt/contents/integration-tests/bats\")",
+      "Bash(python3 -c \"import json,sys; [print\\(x['name']\\) for x in json.load\\(sys.stdin\\) if 'branch' in x.get\\('name',''\\).lower\\(\\) or 'checkout' in x.get\\('name',''\\).lower\\(\\)]\")",
+      "Bash(curl -s \"https://api.github.com/repos/dbt-labs/dbt-adapters/contents/dbt-tests-adapter/src/dbt/tests/fixtures\")",
+      "Bash(python3 -c \"import json,sys; d=json.load\\(sys.stdin\\); [print\\(x['name']\\) for x in d] if isinstance\\(d,list\\) else print\\(d\\)\")",
+      "Bash(curl -s \"https://api.github.com/repos/dbt-labs/dbt-adapters/git/trees/main?recursive=1\")",
+      "Bash(python3 -c \"import json,sys; d=json.load\\(sys.stdin\\); [print\\(x['path']\\) for x in d.get\\('tree',[]\\) if 'fixtures' in x['path'] and x['path'].endswith\\('.py'\\)]\")",
+      "Bash(python -c \"import typer, click; print\\('typer.Exit MRO:', [c.__name__ for c in typer.Exit.__mro__]\\); print\\('is Exception subclass:', issubclass\\(typer.Exit, Exception\\)\\)\")"
+    ]
+  }
+}

db_git-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "pre-commit"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

db_git-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,81 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  unit:
+    name: unit (${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pipx install nox
+      - run: nox -s unit -p "${{ matrix.python }}"
+
+  integration:
+    name: integration (py${{ matrix.python }}, pg${{ matrix.postgres }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13"]
+        postgres: ["13", "14", "15", "16", "17"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install matching postgresql-client
+        run: |
+          sudo sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
+          curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/pgdg.gpg
+          sudo apt-get update
+          sudo apt-get install -y postgresql-client-${{ matrix.postgres }}
+      - 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
+    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 lint

db_git-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

db_git-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+default_language_version:
+  python: python3.12
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.15
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run mypy
+        language: system
+        types: [python]
+        pass_filenames: false
+        args: [src/]

db_git-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# 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).
+
+## [0.1.0] - 2026-05-22
+
+### Added
+
+- Initial `git-db` 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/git-db/`.
+- 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.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hana Belay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

db_git-0.1.0/PKG-INFO

@@ -0,0 +1,363 @@
+Metadata-Version: 2.4
+Name: db-git
+Version: 0.1.0
+Summary: Keep your database in sync with your git branches.
+Project-URL: Homepage, https://github.com/earthcomfy/git-db
+Project-URL: Repository, https://github.com/earthcomfy/git-db
+Project-URL: Issues, https://github.com/earthcomfy/git-db/issues
+Project-URL: Changelog, https://github.com/earthcomfy/git-db/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 :: 3 - Alpha
+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
+Description-Content-Type: text/markdown
+
+# git-db
+
+[![CI](https://github.com/earthcomfy/git-db/actions/workflows/test.yml/badge.svg)](https://github.com/earthcomfy/git-db/actions/workflows/test.yml)
+[![Python](https://img.shields.io/pypi/pyversions/git-db.svg)](https://pypi.org/project/git-db/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Keep your database in sync with your git branches.
+
+`git-db` is a developer tool for projects where database state follows code
+changes: schema migrations, seed data, experimental feature work, and branch
+switching during reviews. It installs a git `post-checkout` hook and keeps your
+local database aligned with the branch you are working on.
+
+> Status: PostgreSQL is supported today; support for additional database
+> engines is planned.
+
+## Features
+
+- Automatic database handling on `git checkout`
+- Two workflows:
+  - `shared`: one database, saved and restored per branch
+  - `per-branch`: one database per branch
+- PostgreSQL support today, with plans for more database backends
+- Two PostgreSQL snapshot strategies:
+  - `template`: fast database clones using `CREATE DATABASE ... TEMPLATE`
+  - `pgdump`: portable snapshots using `pg_dump` and `pg_restore`
+- Manual `save`, `restore`, `create`, `reset`, `list`, `status`, and `prune`
+  commands
+- Safe hook behavior: checkout is never blocked by git-db failures
+- Rich terminal output and local state stored under `.git/git-db/`
+
+## Quick Start
+
+```bash
+uv tool install git-db # or pip install git-db
+```
+
+Run this from inside a git repository:
+
+```bash
+git-db init --database-url postgresql://postgres:postgres@localhost:5432/myapp
+```
+
+Interactive init will ask:
+
+- Whether to use `shared` or `per-branch` mode
+- Whether to use `template` or `pgdump` strategy
+- What to do when active connections block database operations
+- Whether to install the git `post-checkout` hook
+
+After setup, switch branches normally:
+
+```bash
+git checkout feature/auth
+```
+
+In `shared` mode, git-db saves the previous branch database and restores the
+new branch snapshot if one exists.
+
+In `per-branch` mode, git-db creates or selects a database named from the
+current branch, for example:
+
+```text
+myapp__feature__auth
+```
+
+Because the database name changes per branch, your application server also
+needs to connect to the branch database. For example, when working on
+`feature/auth`, point your app's `DATABASE_URL` at `myapp__feature__auth`.
+
+## Choosing a Mode
+
+### Shared Mode
+
+Shared mode keeps one database name from `DATABASE_URL`.
+
+Use this when:
+
+- You want one familiar local database name
+- You want branch-specific snapshots
+- You are comfortable with git-db dropping and restoring that local database
+  during branch switches
+
+### 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
+
+## Choosing a Strategy
+
+### template
+
+The `template` strategy uses PostgreSQL database cloning:
+
+```sql
+CREATE DATABASE target TEMPLATE source;
+```
+
+It is usually fast, but requires sufficient PostgreSQL privileges and can be
+blocked by active connections to the source or target database.
+
+### pgdump
+
+The `pgdump` strategy uses `pg_dump` and `pg_restore`.
+
+It is slower than `template`, but can be a better fit when template cloning is
+not available. It requires PostgreSQL client tools to be installed locally.
+
+## Commands
+
+### Initialize
+
+```bash
+git-db init --database-url postgresql://user:password@localhost:5432/myapp
+```
+
+Useful options:
+
+```bash
+git-db init \
+  --database-url postgresql://user:password@localhost:5432/myapp \
+  --mode per-branch \
+  --strategy template \
+  --on-active-connections terminate
+```
+
+Skip hook installation:
+
+```bash
+git-db init --database-url postgresql://localhost/myapp --no-hook
+```
+
+### Inspect State
+
+```bash
+git-db status
+git-db list
+```
+
+### Shared Mode Commands
+
+Save the current branch database:
+
+```bash
+git-db save
+```
+
+Restore the current branch database:
+
+```bash
+git-db restore
+```
+
+Save or restore a specific branch:
+
+```bash
+git-db save main
+git-db restore feature/auth
+```
+
+### Per-Branch Commands
+
+Create a branch database before checking out the branch:
+
+```bash
+git-db create feature/auth
+```
+
+Drop and recreate a branch database from the seed database:
+
+```bash
+git-db reset feature/auth
+```
+
+The default branch database cannot be reset because it is the seed for other
+branch databases.
+
+### Prune Deleted Branches
+
+Preview stale snapshots or branch databases:
+
+```bash
+git-db prune --dry-run
+```
+
+Remove stale snapshots or branch databases:
+
+```bash
+git-db prune --yes
+```
+
+### Hook Management
+
+Install or reinstall the checkout hook:
+
+```bash
+git-db hook install
+```
+
+Remove the checkout hook:
+
+```bash
+git-db hook remove
+```
+
+Temporarily disable git-db without removing the hook:
+
+```bash
+git-db disable
+git-db enable
+```
+
+You can also skip hook behavior for a single checkout:
+
+```bash
+GIT_DB_SKIP=1 git checkout other-branch
+```
+
+## Configuration
+
+`git-db init` writes `.git-db.toml` at the repository root.
+
+Example:
+
+```toml
+database_url = "postgresql://postgres:postgres@localhost:5432/myapp"
+mode = "per-branch"
+default_branch = "main"
+strategy = "template"
+on_active_connections = "terminate"
+```
+
+Supported configuration keys:
+
+| Key | Description | Default |
+| --- | --- | --- |
+| `database_url` | Database connection URL | required |
+| `mode` | `shared` or `per-branch` | `shared` |
+| `default_branch` | Seed branch for per-branch mode | `main` |
+| `strategy` | `template` or `pgdump` | required |
+| `on_active_connections` | `terminate` or `fail` | `terminate` |
+| `snapshot_dir` | Shared-mode snapshot metadata/dump directory | `.git/git-db/snapshots` |
+| `max_snapshots` | Snapshot count kept by prune logic | `20` |
+| `force_terminate_timeout_ms` | Active connection termination timeout | `5000` |
+
+Configuration precedence:
+
+1. Built-in defaults
+2. `.git-db.toml`
+3. Environment variables
+4. CLI options
+
+Environment variables:
+
+```bash
+DATABASE_URL
+GIT_DB_DATABASE_URL
+GIT_DB_MODE
+GIT_DB_STRATEGY
+GIT_DB_ON_ACTIVE_CONNECTIONS
+GIT_DB_SNAPSHOT_DIR
+GIT_DB_MAX_SNAPSHOTS
+GIT_DB_FORCE_TERMINATE_TIMEOUT_MS
+```
+
+`GIT_DB_DATABASE_URL` takes precedence over `DATABASE_URL`.
+
+### Active connections block an operation
+
+Stop your development server, database console, migration watcher, or GUI
+client, then retry.
+
+Alternatively, configure:
+
+```toml
+on_active_connections = "terminate"
+```
+
+Your PostgreSQL user may need superuser privileges or membership in
+`pg_signal_backend` to terminate sessions owned by other users.
+
+### Temporarily skip git-db
+
+```bash
+git-db disable
+git checkout some-branch
+git-db enable
+```
+
+Or for one command:
+
+```bash
+GIT_DB_SKIP=1 git checkout some-branch
+```
+
+### Show full tracebacks
+
+```bash
+GIT_DB_DEBUG=1 git-db status
+```
+
+## Development
+
+Install dependencies:
+
+```bash
+uv sync --group dev
+```
+
+Run checks:
+
+```bash
+uv run ruff check .
+uv run mypy src tests
+uv run pytest tests/unit
+```
+
+Run the full nox suite:
+
+```bash
+nox
+```
+
+## License
+
+MIT