db-git 0.1.0__py3-none-any.whl

db_git-0.1.0.dist-info/METADATA

@@ -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

db_git-0.1.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+git_db/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+git_db/config.py,sha256=9mE8Pwc6iFnc6wfX_9HjzpJkwSGQNtYcp6c3mcDfPAI,7414
+git_db/db.py,sha256=FA3VWaG7Avm6NyXP4eFwPJAP2TLF2bxa416eGalSrSs,533
+git_db/errors.py,sha256=_KvV20_N3PP9ESETvsl0L4k55y8rl8F22AVpYb-w9q0,754
+git_db/git.py,sha256=G-XW-xEt97Wh5TEsyVTH_0NX0UbvPhIa0NDzcXwPyvw,10057
+git_db/hook_script.py,sha256=KEA1xt77J8IvS0SbpqMLgwgV4y2fgK7BA6wWBEHDqaA,1434
+git_db/state.py,sha256=42_ikKGJG6f52sohk6fz-nAqhOLOnB5ZVLkiLvA4NYg,2568
+git_db/storage.py,sha256=Fid6jepNM1-8lYTX-324WXEkk7Bma3HubSxXjKz7k6s,5592
+git_db/backends/__init__.py,sha256=onyhOXPXR_eh38C4WJDAzLu-J0CJP8cuW4vchnS80CA,4020
+git_db/backends/postgresql/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+git_db/backends/postgresql/backend.py,sha256=uaYRnb1JMeT0ER2xNrfEwRBd1dDsFA2Tug9X0r2lUYg,6026
+git_db/backends/postgresql/branch_db.py,sha256=PEA1QTz7U3Vkkx1S8N9Gl2gqYPUecejNGBVPQ3dadTo,5726
+git_db/backends/postgresql/connections.py,sha256=gR3IV4MTQlfBNo8lR78a8HJMvAqE1-kKdZ_NgqGnPM0,2453
+git_db/backends/postgresql/pgdump.py,sha256=-epWSQvSypV6BGK2hyeO6gul_JIdEbsglA4hs7OH0BA,5629
+git_db/backends/postgresql/template.py,sha256=fexuoTy0IKrs8V1zDIyJO1L8ZSpTDSAYeP5jw70pgug,4490
+git_db/cli/__init__.py,sha256=ZLn5HbrLOokWC1rt7QY2hUPaj55w2SC7sGVCi4Pa1Rk,225
+git_db/cli/_common.py,sha256=uyzlafCaB-tsUrRq25UmboujblA5v3g_9jLCBRU3zqQ,1042
+git_db/cli/_console.py,sha256=nK7JES1yT7oi1iRMuPQY8P9oHttD4WMDd8l2ZoqEF6s,409
+git_db/cli/_format.py,sha256=g1CEy-E8rz_sfRhRxwcYlCg0SsvUK6FZZgUQQNM54pg,1616
+git_db/cli/_prompts.py,sha256=lfknOgNHNAPWkMi4RRIbrVbn6RZIgMqzRyb7ta5pLE4,3076
+git_db/cli/branch.py,sha256=jtBA-i-TR7HE-dYj_Azxa1yJMwGXoGDaS7hao3S1h3Y,5377
+git_db/cli/hook.py,sha256=-DW_0sOo7hHot5j0aqSISsmZAmFrns-XsyYJb5Xv85U,2640
+git_db/cli/init.py,sha256=fsQhka7DdMj3i1vdWro9lVxBF1oB0eKQMh0J6Qc57qQ,9248
+git_db/cli/inspect.py,sha256=ma_bF53Sy6DFN3orgF88wXyHKdZlrcbCIgGyLL5xb14,12457
+git_db/cli/snapshot.py,sha256=5OjMdwr97Ga2HqK6xLf2sXNJbH6iAzyW5ZhEYUjpNSo,3713
+db_git-0.1.0.dist-info/METADATA,sha256=VLNZ4dZ_nqdRfLoWpqAtuOb4xWJM3-iCGVBoWQGihp8,8451
+db_git-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+db_git-0.1.0.dist-info/entry_points.txt,sha256=dU0NWsfYR8-COUVsowXR795CsqRqSFE-yBijHSX-wN8,42
+db_git-0.1.0.dist-info/licenses/LICENSE,sha256=JTB2YQpxa0QXq1mU53Qj0hi-CwzxrV4GWa0g4FTZl8Q,1067
+db_git-0.1.0.dist-info/RECORD,,

db_git-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

db_git-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+db-git = git_db.cli:app

db_git-0.1.0.dist-info/licenses/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.

git_db/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

git_db/backends/__init__.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import contextlib
+import importlib
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+from urllib.parse import urlparse
+
+from git_db.errors import ConfigError
+
+if TYPE_CHECKING:
+    from git_db.config import GitDbConfig
+    from git_db.state import BranchDbEntry
+
+_BACKEND_REGISTRY: dict[str, type[DatabaseBackend]] = {}
+_BUILTIN_BACKENDS: dict[str, str] = {
+    "postgresql": "git_db.backends.postgresql.backend",
+}
+
+
+class DbCursor(Protocol):
+    """
+    Minimal cursor protocol for database query results.
+    """
+
+    def fetchone(self) -> tuple[Any, ...] | None: ...
+    def fetchall(self) -> list[tuple[Any, ...]]: ...
+
+
+class DbConnection(Protocol):
+    """
+    Minimal connection protocol returned by connect_maintenance.
+    """
+
+    def execute(self, query: Any, params: Any = None) -> DbCursor: ...
+    def close(self) -> None: ...
+
+
+@runtime_checkable
+class SnapshotStrategy(Protocol):
+    """
+    Protocol for snapshot save/restore strategies.
+    """
+
+    name: str
+
+    def save(
+        self,
+        db_url: str,
+        branch: str,
+        snapshot_dir: Path,
+        config: GitDbConfig,
+    ) -> None: ...
+
+    def restore(
+        self,
+        db_url: str,
+        branch: str,
+        snapshot_dir: Path,
+        config: GitDbConfig,
+    ) -> None: ...
+
+    def cleanup(
+        self,
+        branch: str,
+        snapshot_dir: Path,
+        config: GitDbConfig,
+    ) -> None: ...
+
+
+class BranchDbManager(Protocol):
+    """
+    Protocol for per-branch database operations.
+    """
+
+    def exists(self, name: str) -> bool: ...
+
+    def create(
+        self,
+        target: str,
+        source: str,
+        branch: str,
+        created_from: str,
+        git_dir: Path,
+    ) -> None: ...
+
+    def drop(
+        self,
+        name: str,
+        branch: str,
+        git_dir: Path,
+    ) -> None: ...
+
+    def list(
+        self,
+        git_dir: Path,
+    ) -> list[tuple[str, BranchDbEntry, bool]]: ...
+
+
+@runtime_checkable
+class DatabaseBackend(Protocol):
+    """
+    Protocol for database engine backends.
+    """
+
+    engine: str
+    max_identifier_length: int
+
+    def apply_url_defaults(
+        self, params: dict[str, str | int | None]
+    ) -> dict[str, str | int]: ...
+
+    def get_engine_version(self, url: str) -> int: ...
+
+    def detect_strategy(self, config: GitDbConfig) -> SnapshotStrategy: ...
+
+    def branch_db_manager(self, config: GitDbConfig) -> BranchDbManager: ...
+
+    def connect_maintenance(self, params: dict[str, str | int]) -> DbConnection: ...
+
+    def build_subprocess_env(self, params: dict[str, str | int]) -> dict[str, str]: ...
+
+    def check_permissions(self, url: str) -> object: ...
+
+    def database_exists(self, url: str, name: str) -> bool: ...
+
+
+def register_backend(scheme: str, cls: type[DatabaseBackend]) -> None:
+    """
+    Register a backend class for a URL scheme.
+    """
+    _BACKEND_REGISTRY[scheme] = cls
+
+
+def get_backend(url: str) -> DatabaseBackend:
+    """
+    Auto-detect and instantiate the correct backend from a database URL.
+    """
+    parsed = urlparse(url)
+    scheme = parsed.scheme or "postgresql"
+
+    if scheme in ("postgres", "postgresql"):
+        scheme = "postgresql"
+
+    if scheme not in _BACKEND_REGISTRY:
+        _try_import_backend(scheme)
+
+    if scheme not in _BACKEND_REGISTRY:
+        supported = ", ".join(sorted(_BACKEND_REGISTRY.keys())) or "none"
+        raise ConfigError(
+            f"Unknown database scheme '{scheme}'. Supported: {supported}."
+        )
+
+    return _BACKEND_REGISTRY[scheme]()
+
+
+def _try_import_backend(scheme: str) -> None:
+    """
+    Attempt to import a built-in backend module to trigger registration.
+    """
+    module_name = _BUILTIN_BACKENDS.get(scheme)
+    if module_name:
+        with contextlib.suppress(ImportError):
+            importlib.import_module(module_name)
+
+
+__all__ = [
+    "BranchDbManager",
+    "DatabaseBackend",
+    "SnapshotStrategy",
+    "get_backend",
+    "register_backend",
+]