branch_db 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c68b9335eb0602387a79af5a1e9c715249e2e30070faaa916510ff8e97f21203
+  data.tar.gz: b7f409fd18171d5845e812f1b5a1b2ec052b02b46d809c5b64a611bb5ee3a966
+SHA512:
+  metadata.gz: 6ef2f12ea030b88a18549ab83d9b8aac9db5afae73ab607165d5667e789d86af0292b0a4c7b64cad56c828120c10da5a7d538529e8afd4c609748a096a70e903
+  data.tar.gz: 2314b2ab78c68af51f995ffc9d2600dbc13ed3a78a2c504661396e243fed6e6bd24326841ea6de6ada234adc01b72fbb9b67523fe99322bc51a4e9ea21eef94f

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-01-18
+
+### Added
+
+- Automatic per-branch PostgreSQL database management for Rails
+- Seamless integration with Rails `db:prepare` task
+- Automatic cloning from parent branch database (with main as fallback) when creating new branch databases
+- Smart parent branch detection via git reflog analysis
+- `BRANCH_DB_PARENT` environment variable to override parent branch detection
+- Development-only cloning (test databases use standard Rails schema load)
+- `BranchDb.database_name` helper for dynamic database naming in `database.yml`
+- `rails db:branch:list` task to list all branch databases
+- `rails db:branch:purge` task to remove all branch databases (keeps main and current)
+- `rails db:branch:prune` task to remove databases for deleted git branches
+- Support for Rails multiple database configurations
+- Configurable main branch name (default: `main`)
+- Configurable branch name length limit (default: 33 characters)
+- Configurable database suffixes (`development_suffix`, `test_suffix`)
+- Active connection detection to prevent dropping databases in use
+- Rails generator for easy installation (`rails generate branch_db:install`)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MilkStraw AI
+
+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.

data/README.md

@@ -0,0 +1,435 @@
+# BranchDb
+
+[![Gem Version](https://badge.fury.io/rb/branch_db.svg)](https://badge.fury.io/rb/branch_db)
+[![Build Status](https://github.com/milkstrawai/branch_db/actions/workflows/main.yml/badge.svg)](https://github.com/milkstrawai/branch_db/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Automatic per-branch PostgreSQL databases for Rails development.**
+
+BranchDb eliminates database migration conflicts by giving each git branch its own isolated database. Switch branches freely without worrying about schema mismatches or losing development data.
+
+## Table of Contents
+
+- [The Problem](#the-problem)
+- [The Solution](#the-solution)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [How It Works](#how-it-works)
+- [Requirements](#requirements)
+- [Important Notes](#important-notes)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
+## The Problem
+
+Working on multiple feature branches with different migrations causes pain:
+
+```
+# On feature-a branch: Add a 'status' column
+rails generate migration AddStatusToUsers status:string
+rails db:migrate
+
+# Switch to feature-b branch
+git checkout feature-b
+git status
+# => modified: db/schema.rb   <- Contains 'status' column from feature-a!
+
+# Now your schema.rb has changes that don't belong to this branch
+# Accidentally commit it? You've just mixed schema changes across branches
+# Run db:migrate? Schema.rb still shows the foreign column
+```
+
+## The Solution
+
+BranchDb automatically manages separate databases for each branch:
+
+```
+main branch         → myapp_development_main
+feature-auth        → myapp_development_feature_auth
+feature-payments    → myapp_development_feature_payments
+bugfix-login        → myapp_development_bugfix_login
+```
+
+Each branch has its own isolated database with its own schema and data. Switch branches, restart your server, and you're working with the right database automatically.
+
+## Installation
+
+Add BranchDb to your Gemfile:
+
+```ruby
+group :development, :test do
+  gem 'branch_db'
+end
+```
+
+Install and run the generator:
+
+```bash
+bundle install
+rails generate branch_db:install
+```
+
+Update your `config/database.yml`:
+
+```yaml
+development:
+  <<: *default
+  database: <%= BranchDb.database_name('myapp_development') %>
+
+test:
+  <<: *default
+  database: <%= BranchDb.database_name('myapp_test') %>
+```
+
+> **Note:** Replace `myapp` with your application name. Keep `_development` and `_test` suffixes for the cleanup feature to work correctly.
+
+Initialize your first branch database:
+
+```bash
+rails db:prepare
+```
+
+## Configuration
+
+The generator creates `config/initializers/branch_db.rb`:
+
+```ruby
+BranchDb.configure do |config|
+  # The name of your main/stable branch (default: 'main')
+  config.main_branch = 'main'
+
+  # Maximum length for branch name suffix (default: 33)
+  # PostgreSQL has a 63 character limit for database names
+  # Formula: base_name_length + 1 (underscore) + max_branch_length <= 63
+  config.max_branch_length = 33
+
+  # Database name suffixes for cleanup feature (default: '_development', '_test')
+  # Customize if your database names use different conventions
+  # config.development_suffix = '_development'
+  # config.test_suffix = '_test'
+end
+```
+
+### Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `main_branch` | `'main'` | Your primary branch name (used as fallback clone source) |
+| `max_branch_length` | `33` | Max characters for branch suffix (prevents exceeding PostgreSQL's 63-char limit) |
+| `development_suffix` | `'_development'` | Suffix pattern for development databases |
+| `test_suffix` | `'_test'` | Suffix pattern for test databases |
+
+## Usage
+
+### Daily Workflow
+
+BranchDb enhances Rails' built-in `db:prepare` command:
+
+```bash
+# Just use Rails' standard command - now branch-aware!
+rails db:prepare
+```
+
+**What happens (development only):**
+1. Checks if your branch's database exists and has schema
+2. If missing/empty and parent/main exists: **clones from parent branch** (or main as fallback)
+3. If on main branch or no source exists: defers to standard Rails behavior
+4. Rails then runs pending migrations and seeds as usual
+
+**Test databases** use standard Rails behavior (schema load, no cloning):
+```bash
+RAILS_ENV=test rails db:prepare
+```
+
+> **Note:** Cloning only runs in development environment. All commands support Rails' multiple database feature.
+
+### Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `rails db:prepare` | Rails' standard command, enhanced with cloning from parent/main |
+| `rails db:branch:list` | List all branch databases |
+| `rails db:branch:purge` | Remove all branch databases except current and main |
+| `rails db:branch:prune` | Remove databases for branches that no longer exist in git |
+
+### Examples
+
+```bash
+# Starting work on a new feature branch
+git checkout -b feature-new-thing
+rails db:prepare  # Clones from parent branch (or main as fallback)
+rails server
+
+# Switching to another branch
+git checkout feature-other-thing
+# Restart your Rails server to connect to the other database
+rails server
+
+# Purging all branch databases (keeps current and main only)
+rails db:branch:purge
+# => Found 5 database(s) to remove:
+# =>   - myapp_development_feature_old
+# =>   - myapp_test_feature_old
+# =>   ...
+# => Proceed with deletion? [y/N]
+
+# Pruning databases for deleted git branches only
+rails db:branch:prune
+# => Found 2 database(s) to remove:
+# =>   - myapp_development_merged_feature
+# =>   - myapp_test_merged_feature
+# => Proceed with deletion? [y/N]
+```
+
+## How It Works
+
+### Rails Integration
+
+BranchDb enhances Rails' `db:prepare` task by adding a prerequisite that clones from the parent branch when needed. This means:
+
+- **Zero learning curve** - use `rails db:prepare` as usual
+- **Automatic cloning** - new branch databases are cloned from their parent (or main as fallback)
+- **Rails handles the rest** - migrations, seeds, and schema dumps work normally
+
+### Database Naming
+
+BranchDb generates database names by combining your base name with a sanitized branch name:
+
+```
+Base name:    myapp_development
+Branch:       feature/user-auth
+Sanitized:    feature_user_auth
+Result:       myapp_development_feature_user_auth
+```
+
+Branch names are sanitized: non-alphanumeric characters become underscores, and names are truncated to `max_branch_length`.
+
+### Cloning Process
+
+When `db:prepare` detects a missing or empty database:
+
+1. **Detects** the parent branch to clone from (see below)
+2. **Checks** if the parent database exists; if not, falls back to main
+3. **If source exists:** Creates the target database and uses `pg_dump | psql` for efficient cloning
+4. **If no source:** Defers to Rails' standard `db:prepare` (loads schema, runs migrations, seeds)
+5. **On main branch:** Defers to Rails' standard `db:prepare`
+
+### Parent Branch Detection
+
+BranchDb intelligently detects which branch you branched from and clones its database. This enables nested feature branch workflows:
+
+```
+main → feature-a → feature-a-child
+```
+
+When you create `feature-a-child` from `feature-a`, BranchDb will clone from `feature-a`'s database (if it exists), not main.
+
+**Detection priority:**
+
+1. `BRANCH_DB_PARENT` environment variable (explicit override)
+2. Git reflog analysis (finds the last "checkout: moving from X to current-branch")
+3. Configured `main_branch` (fallback)
+
+**Fallback behavior:** If the detected parent's database doesn't exist, BranchDb automatically falls back to the main branch database.
+
+**Override with environment variable:**
+
+```bash
+# Force cloning from main, even if on a nested feature branch
+BRANCH_DB_PARENT=main rails db:prepare
+
+# Clone from a specific branch
+BRANCH_DB_PARENT=feature-other rails db:prepare
+```
+
+### Purge Safety
+
+The purge command protects important databases:
+- Current branch's development and test databases
+- Main branch's development and test databases
+- Databases with active connections (skipped with warning)
+
+## Requirements
+
+- **Ruby** >= 3.2
+- **Rails** >= 7.0
+- **PostgreSQL** (any supported version)
+- **PostgreSQL client tools** in PATH:
+  - `psql` - for database operations
+  - `pg_dump` - for cloning databases
+  - `dropdb` - for purge/prune operations
+
+### Verifying PostgreSQL Tools
+
+```bash
+which psql pg_dump dropdb
+# Should output paths for all three tools
+```
+
+If missing, install PostgreSQL client tools:
+
+```bash
+# macOS
+brew install postgresql
+
+# Ubuntu/Debian
+sudo apt-get install postgresql-client
+
+# Docker (add to your Dockerfile)
+RUN apt-get update && apt-get install -y postgresql-client
+```
+
+## Important Notes
+
+### Server Restart Required
+
+Database selection happens at Rails boot time (ERB in `database.yml` is evaluated once). After switching branches, **restart your Rails server** to connect to the correct database.
+
+```bash
+git checkout other-branch
+# Must restart Rails to use other-branch's database
+rails server  # Now connected to myapp_development_other_branch
+```
+
+### Detached HEAD State
+
+In detached HEAD state (e.g., `git checkout abc123`), BranchDb cannot determine a branch name. It falls back to using the base database name without a suffix. All detached HEAD checkouts share this database.
+
+For CI environments, ensure you checkout an actual branch:
+
+```bash
+# CI script
+git checkout $BRANCH_NAME  # Not just the commit SHA
+rails db:prepare
+```
+
+### Database Name Length
+
+PostgreSQL limits database names to 63 characters. With default settings:
+- Base name: up to 29 characters
+- Underscore: 1 character
+- Branch suffix: up to 33 characters
+
+If your base name is longer, reduce `max_branch_length` accordingly.
+
+## Troubleshooting
+
+### "PostgreSQL tool 'X' not found in PATH"
+
+Install PostgreSQL client tools (see [Requirements](#requirements)).
+
+### "Could not connect to Postgres on port X"
+
+Ensure PostgreSQL is running and accessible:
+
+```bash
+# Check if PostgreSQL is running
+pg_isready -h localhost -p 5432
+
+# For Docker users
+docker ps | grep postgres
+```
+
+### Database not switching when I change branches
+
+Remember to restart your Rails server after switching branches. The database name is determined at boot time.
+
+### Clone is slow for large databases
+
+`pg_dump | psql` is already efficient, but for very large databases consider:
+- Keeping your main branch database lean
+- Using database-level compression
+- Running cleanup regularly to remove old branch databases
+
+### Branch name too long
+
+Long branch names are automatically truncated to `max_branch_length` (default: 33). Two branches with the same prefix might collide:
+
+```
+feature/very-long-descriptive-name-for-auth    → _feature_very_long_descriptive_na
+feature/very-long-descriptive-name-for-payments → _feature_very_long_descriptive_na  # Same!
+```
+
+Use shorter branch names or increase `max_branch_length` (if your base name is short enough).
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/milkstrawai/branch_db.git
+cd branch_db
+bin/setup
+```
+
+### Running Tests
+
+```bash
+# Run test suite
+bundle exec rspec
+
+# Run with coverage report
+bundle exec rspec && open coverage/index.html
+
+# Run linter
+bundle exec rubocop
+
+# Run both
+bundle exec rake
+```
+
+### Test Coverage
+
+The project maintains high test coverage standards:
+- Line coverage: 100%
+- Branch coverage: 90%
+
+## Roadmap
+
+Features we're considering for future releases:
+
+- [ ] **SQLite and MySQL support** - Database adapter pattern for non-PostgreSQL databases
+- [ ] **Standalone clone task** - `rails db:branch:clone FROM=branch-name` for manual cloning
+- [ ] **Post-checkout git hook** - Auto-restart Rails server on branch switch (Doable?)
+- [ ] **Database info task** - `rails db:branch:info` showing current branch, DB name, size, and parent
+- [ ] **Clone progress indicator** - Visual feedback for large database clones
+- [ ] **Disk usage report** - `rails db:branch:list --size` to show storage per branch
+
+Have a feature request? [Open an issue](https://github.com/milkstrawai/branch_db/issues) to discuss it!
+
+## Contributing
+
+Contributions are welcome! Here's how you can help:
+
+1. **Fork** the repository
+2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
+3. **Commit** your changes (`git commit -m 'Add amazing feature'`)
+4. **Push** to the branch (`git push origin feature/amazing-feature`)
+5. **Open** a Pull Request
+
+### Guidelines
+
+- Write tests for new features
+- Follow existing code style (RuboCop will help)
+- Update documentation as needed
+- Keep commits focused and atomic
+
+### Reporting Issues
+
+Found a bug? Please open an issue with:
+- Ruby and Rails versions
+- PostgreSQL version
+- Steps to reproduce
+- Expected vs actual behavior
+
+## License
+
+BranchDb is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Acknowledgments
+
+Inspired by the pain of database migration conflicts and the joy of isolated development environments.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/branch_db/cleaner.rb

@@ -0,0 +1,121 @@
+require "open3"
+
+module BranchDb
+  class Cleaner
+    include PgUtils
+    include Logging
+
+    attr_reader :config, :output, :input, :name
+
+    def initialize(config, output: $stdout, input: $stdin, prefix: true, name: nil)
+      @config = config.is_a?(Hash) ? config : config.configuration_hash
+      @output = output
+      @input = input
+      @prefix = prefix
+      @name = name
+    end
+
+    def list_branch_databases
+      dev_dbs = find_databases(dev_prefix)
+      test_dbs = find_databases(test_prefix)
+
+      if dev_dbs.empty? && test_dbs.empty?
+        log "No branch databases found#{db_label}."
+        return []
+      end
+
+      all_dbs = dev_dbs + test_dbs
+      log "Found #{all_dbs.size} branch database(s)#{db_label}:"
+      all_dbs.each { |db| log "  - #{db}" }
+      all_dbs
+    end
+
+    def purge(confirm: true)
+      delete_databases(deletable_databases, empty_msg: "No old branch databases to purge#{db_label}.",
+                                            done_msg: "Purge complete#{db_label}!", confirm:)
+    end
+
+    def prune(confirm: true)
+      delete_databases(prunable_databases, empty_msg: "No stale branch databases to prune#{db_label}.",
+                                           done_msg: "Prune complete#{db_label}!", confirm:)
+    end
+
+    def protected_databases
+      current_dev = config[:database]
+      current_test = current_dev.sub(dev_prefix, test_prefix)
+
+      [
+        current_dev,
+        current_test,
+        "#{dev_prefix}#{BranchDb.configuration.main_branch}",
+        "#{test_prefix}#{BranchDb.configuration.main_branch}"
+      ]
+    end
+
+    private
+
+    def deletable_databases
+      all_branch_databases.reject { |db| protected_databases.include?(db) }
+    end
+
+    def prunable_databases
+      existing = BranchDb::Naming.git_branches.map { BranchDb::Naming.sanitize_branch(_1) }
+      all_branch_databases.reject { |db| protected_databases.include?(db) || branch_exists?(db, existing) }
+    end
+
+    def all_branch_databases = find_databases(dev_prefix) + find_databases(test_prefix)
+
+    def branch_exists?(db, existing_branches)
+      prefix = db.start_with?(test_prefix) ? test_prefix : dev_prefix
+      existing_branches.include?(db.sub(prefix, ""))
+    end
+
+    def delete_databases(to_delete, empty_msg:, done_msg:, confirm:)
+      return log(empty_msg) if to_delete.empty?
+
+      display_databases(to_delete)
+      return log("Aborted.") if confirm && !user_confirmed?
+
+      to_delete.each { |db| drop_database(db) }
+      log done_msg
+    end
+
+    def display_databases(databases)
+      log "Found #{databases.size} database(s) to remove:"
+      databases.each { log "  - #{_1}" }
+    end
+
+    def user_confirmed? = (output.print "\nProceed with deletion? [y/N] ") || input.gets&.chomp&.downcase == "y"
+
+    def find_databases(prefix)
+      check_pg_tools!(:psql, :dropdb)
+      stdout, = Open3.capture2(pg_env, "bash", "-c", "#{list_databases_cmd} | grep ^#{prefix.shellescape}")
+      stdout.split("\n").map(&:strip).reject(&:empty?)
+    end
+
+    def drop_database(db)
+      active = active_connections(db)
+      return log "⚠️  Skipping #{db} (#{active} active connection#{"s" if active > 1})" if active.positive?
+
+      dropped = system(pg_env, "bash", "-c", "dropdb #{psql_flags} #{db.shellescape}")
+      log dropped ? "✅ Dropped #{db}" : "❌ Failed to drop #{db}"
+    end
+
+    def active_connections(db)
+      query = "SELECT count(*) FROM pg_stat_activity WHERE datname = '#{db.gsub("'", "''")}'"
+      stdout, = Open3.capture2(pg_env, "bash", "-c", "psql #{psql_flags} -d postgres -tAc \"#{query}\"")
+      stdout.strip.to_i
+    end
+
+    def db_label = name && name != "primary" ? " for #{name}" : ""
+
+    def dev_prefix = "#{base_name}_"
+
+    def test_prefix = "#{base_name.sub(BranchDb.configuration.development_suffix, BranchDb.configuration.test_suffix)}_"
+
+    def base_name
+      suffix = BranchDb::Naming.branch_suffix
+      suffix.empty? ? config[:database] : config[:database].sub(/#{Regexp.escape(suffix)}\z/, "")
+    end
+  end
+end

data/lib/branch_db/cloner.rb

@@ -0,0 +1,79 @@
+module BranchDb
+  class Cloner
+    include PgUtils
+    include Logging
+
+    attr_reader :config, :output
+
+    def initialize(config, output: $stdout)
+      @config = config.is_a?(Hash) ? config : config.configuration_hash
+      @output = output
+    end
+
+    def clone
+      log "📦 Cloning #{source_db} → #{target_db}..."
+      create_or_recreate_database
+      transfer_data
+    end
+
+    def source_exists?
+      check_pg_tools!(:psql, :pg_dump)
+      database_exists?(source_db)
+    end
+
+    def source_db
+      @source_db ||= determine_source_db
+    end
+
+    def target_db
+      config[:database]
+    end
+
+    def base_name
+      suffix = BranchDb::Naming.branch_suffix
+      return target_db if suffix.empty?
+
+      target_db.sub(/#{Regexp.escape(suffix)}\z/, "")
+    end
+
+    private
+
+    def determine_source_db
+      parent_db = BranchDb::Naming.parent_database_name(base_name)
+      main_db = "#{base_name}_#{BranchDb.configuration.main_branch}"
+
+      return main_db if parent_db == main_db
+
+      check_pg_tools!(:psql, :pg_dump)
+      database_exists?(parent_db) ? parent_db : main_db
+    end
+
+    def database_exists?(db_name)
+      check_cmd = "#{list_databases_cmd} | grep -qx #{db_name.shellescape}"
+      system(pg_env, "bash", "-c", check_cmd)
+    end
+
+    def create_or_recreate_database
+      ActiveRecord::Tasks::DatabaseTasks.create(config)
+      log_indented "Created database '#{target_db}'"
+    rescue ActiveRecord::DatabaseAlreadyExists
+      log_indented "Database '#{target_db}' already exists. Recreating..."
+      ActiveRecord::Tasks::DatabaseTasks.drop(config)
+      ActiveRecord::Tasks::DatabaseTasks.create(config)
+    end
+
+    def transfer_data
+      dump_cmd = "pg_dump #{psql_flags} --no-owner --no-acl #{source_db.shellescape}"
+      restore_cmd = "psql #{psql_flags} #{target_db.shellescape}"
+      full_command = "set -o pipefail; #{dump_cmd} | #{restore_cmd}"
+
+      log_indented "Transferring data..."
+
+      unless system(pg_env, "bash", "-c", full_command, %i[out err] => File::NULL)
+        raise Error, "Clone failed! Check PostgreSQL connection."
+      end
+
+      log "✅ Database cloned successfully!"
+    end
+  end
+end

data/lib/branch_db/configuration.rb

@@ -0,0 +1,12 @@
+module BranchDb
+  class Configuration
+    attr_accessor :main_branch, :max_branch_length, :development_suffix, :test_suffix
+
+    def initialize
+      @main_branch = "main"
+      @max_branch_length = 33
+      @development_suffix = "_development"
+      @test_suffix = "_test"
+    end
+  end
+end

data/lib/branch_db/git_utils.rb

@@ -0,0 +1,48 @@
+module BranchDb
+  module GitUtils
+    def current_branch
+      `git symbolic-ref HEAD 2>/dev/null`.chomp.sub("refs/heads/", "")
+    end
+
+    def git_branches
+      output = `git branch --format='%(refname:short)' 2>/dev/null`
+      output.split("\n").map(&:strip).reject(&:empty?)
+    end
+
+    def parent_branch
+      @parent_branch ||= detect_parent_branch
+    end
+
+    def reset_parent_cache!
+      @parent_branch = nil
+    end
+
+    private
+
+    def detect_parent_branch
+      return ENV["BRANCH_DB_PARENT"] if ENV["BRANCH_DB_PARENT"]
+
+      detect_parent_from_reflog || BranchDb.configuration.main_branch
+    end
+
+    def detect_parent_from_reflog
+      current = current_branch
+      return nil if current.empty?
+
+      `git reflog show --format='%gs' -n 100 2>/dev/null`.each_line do |line|
+        parent = extract_parent_from_reflog_line(line.chomp, current)
+        return parent if parent
+      end
+      nil
+    end
+
+    def extract_parent_from_reflog_line(line, current)
+      return nil unless line =~ /\Acheckout: moving from (.+) to #{Regexp.escape(current)}\z/
+
+      parent = ::Regexp.last_match(1).strip
+      return nil if parent == current || parent =~ /\A[a-f0-9]{40}\z/
+
+      parent
+    end
+  end
+end

data/lib/branch_db/logging.rb

@@ -0,0 +1,17 @@
+module BranchDb
+  module Logging
+    PREFIX = "[branch_db]".freeze
+
+    private
+
+    def log(message)
+      output.puts prefix? ? "#{PREFIX} #{message}" : message
+    end
+
+    def log_indented(message)
+      output.puts prefix? ? "#{PREFIX}    #{message}" : "   #{message}"
+    end
+
+    def prefix? = @prefix != false
+  end
+end

data/lib/branch_db/naming.rb

@@ -0,0 +1,24 @@
+module BranchDb
+  module Naming
+    extend GitUtils
+
+    class << self
+      def sanitize_branch(branch)
+        branch.gsub(/[^a-zA-Z0-9_]/, "_")
+      end
+
+      def branch_suffix
+        branch = sanitize_branch(current_branch)
+        max_length = BranchDb.configuration.max_branch_length
+        truncated = branch[0, max_length]
+        truncated.empty? ? "" : "_#{truncated}"
+      end
+
+      def database_name(base_name) = "#{base_name}#{branch_suffix}"
+
+      def main_database_name(base_name) = "#{base_name}_#{BranchDb.configuration.main_branch}"
+
+      def parent_database_name(base_name) = "#{base_name}_#{sanitize_branch(parent_branch)}"
+    end
+  end
+end

data/lib/branch_db/pg_utils.rb

@@ -0,0 +1,35 @@
+require "shellwords"
+
+module BranchDb
+  module PgUtils
+    PG_TOOLS = %w[psql pg_dump dropdb].freeze
+
+    private
+
+    def psql_flags
+      host = config[:host].to_s.shellescape
+      port = config[:port].to_s.shellescape
+      username = config[:username].to_s.shellescape
+
+      "-h #{host} -p #{port} -U #{username}"
+    end
+
+    def pg_env
+      { "PGPASSWORD" => config[:password].to_s }
+    end
+
+    def list_databases_cmd
+      "psql #{psql_flags} -lqt | cut -d \\| -f 1 | sed 's/^[[:space:]]*//;s/[[:space:]]*$//'"
+    end
+
+    def check_pg_tools!(*tools)
+      tools = PG_TOOLS if tools.empty?
+
+      tools.each do |tool|
+        unless system("which #{tool} > /dev/null 2>&1")
+          raise Error, "PostgreSQL tool '#{tool}' not found in PATH. Please install PostgreSQL client tools."
+        end
+      end
+    end
+  end
+end

data/lib/branch_db/preparer.rb

@@ -0,0 +1,58 @@
+module BranchDb
+  # Checks if database needs initialization and triggers cloning if needed.
+  # Used by the db:prepare rake task enhancement.
+  class Preparer
+    include Logging
+
+    attr_reader :db_config, :output
+
+    def initialize(db_config, output: $stdout)
+      @db_config = db_config
+      @output = output
+    end
+
+    def prepare_if_needed
+      log "📦 Checking database#{db_label}..."
+
+      unless needs_cloning?
+        log "✅ Database '#{config[:database]}' ready."
+        return
+      end
+
+      attempt_clone
+    end
+
+    private
+
+    def config
+      db_config.configuration_hash
+    end
+
+    def db_label
+      db_config.name == "primary" ? "" : " (#{db_config.name})"
+    end
+
+    def needs_cloning?
+      establish_connection
+      !ActiveRecord::Base.connection.table_exists?("schema_migrations")
+    rescue ActiveRecord::NoDatabaseError
+      true
+    end
+
+    def establish_connection
+      ActiveRecord::Base.establish_connection(db_config)
+    end
+
+    def attempt_clone
+      cloner = Cloner.new(config, output:)
+
+      if cloner.target_db == cloner.source_db
+        log_indented "On main branch. Deferring to db:prepare..."
+      elsif cloner.source_exists?
+        cloner.clone
+      else
+        log_indented "Source database not found. Deferring to db:prepare..."
+      end
+    end
+  end
+end

data/lib/branch_db/railtie.rb

@@ -0,0 +1,9 @@
+module BranchDb
+  class Railtie < Rails::Railtie
+    railtie_name :branch_db
+
+    rake_tasks do
+      load File.expand_path("tasks/branch_db.rake", __dir__)
+    end
+  end
+end

data/lib/branch_db/tasks/branch_db.rake

@@ -0,0 +1,34 @@
+def db_configs = ActiveRecord::Base.configurations.configs_for(env_name: Rails.env)
+
+def cleaner_for(db_config) = BranchDb::Cleaner.new(db_config.configuration_hash, prefix: false, name: db_config.name)
+
+namespace :db do
+  namespace :branch do
+    desc "List all branch databases"
+    task list: :environment do
+      db_configs.each { cleaner_for(_1).list_branch_databases }
+    end
+
+    desc "Remove all branch databases (keeps main and current branch)"
+    task purge: :environment do
+      db_configs.each { cleaner_for(_1).purge }
+    end
+
+    desc "Remove databases for branches that no longer exist in git"
+    task prune: :environment do
+      db_configs.each { cleaner_for(_1).prune }
+    end
+
+    desc "Ensure branch database exists (used by db:prepare enhancement)"
+    task ensure_cloned: :environment do
+      next unless Rails.env.development?
+
+      db_configs.each { BranchDb::Preparer.new(_1).prepare_if_needed }
+    rescue ActiveRecord::ConnectionNotEstablished, PG::ConnectionBad => e
+      abort "❌ Could not connect to Postgres: #{e.message}"
+    end
+  end
+end
+
+# Enhance Rails' db:prepare to clone from parent branch when needed
+Rake::Task["db:prepare"].enhance(["db:branch:ensure_cloned"])

data/lib/branch_db/version.rb

@@ -0,0 +1,3 @@
+module BranchDb
+  VERSION = "0.1.0".freeze
+end

data/lib/branch_db.rb

@@ -0,0 +1,32 @@
+require_relative "branch_db/version"
+require_relative "branch_db/configuration"
+require_relative "branch_db/git_utils"
+require_relative "branch_db/naming"
+require_relative "branch_db/pg_utils"
+require_relative "branch_db/logging"
+require_relative "branch_db/cloner"
+require_relative "branch_db/cleaner"
+require_relative "branch_db/preparer"
+require_relative "branch_db/railtie" if defined?(Rails::Railtie)
+
+module BranchDb
+  class Error < StandardError; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def database_name(base_name)
+      Naming.database_name(base_name)
+    end
+
+    def main_database_name(base_name)
+      Naming.main_database_name(base_name)
+    end
+  end
+end

data/lib/generators/branch_db/install_generator.rb

@@ -0,0 +1,43 @@
+require "rails/generators/base"
+
+module BranchDb
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    desc "Creates a BranchDb initializer and shows setup instructions"
+
+    def create_initializer
+      template "initializer.rb", "config/initializers/branch_db.rb"
+    end
+
+    def show_instructions # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+      say ""
+      say "=== BranchDb Installation Complete ===", :green
+      say ""
+      say "Next steps:", :yellow
+      say ""
+      say "1. Update your config/database.yml to use dynamic database names:"
+      say ""
+      say "   development:"
+      say "     database: <%= BranchDb.database_name('#{app_name}_development') %>"
+      say ""
+      say "   test:"
+      say "     database: <%= BranchDb.database_name('#{app_name}_test') %>"
+      say ""
+      say "2. Initialize your database:"
+      say "   rails db:prepare          # Creates and clones from main"
+      say ""
+      say "3. Other available tasks:"
+      say "   rails db:branch:list      # List all branch databases"
+      say "   rails db:branch:purge     # Remove all branch databases (keeps main/current)"
+      say "   rails db:branch:prune     # Remove databases for deleted git branches"
+      say ""
+    end
+
+    private
+
+    def app_name
+      Rails.application.class.module_parent_name.underscore
+    end
+  end
+end

data/lib/generators/branch_db/templates/initializer.rb

@@ -0,0 +1,15 @@
+BranchDb.configure do |config|
+  # The name of your main/stable branch (default: 'main')
+  # config.main_branch = 'main'
+
+  # Maximum length for branch name suffix in database names (default: 33)
+  # PostgreSQL has a 63 character limit for database names
+  # Ensure: base_name_length + 1 + max_branch_length <= 63
+  # config.max_branch_length = 33
+
+  # Database name suffixes for dev/test environment matching (default: '_development', '_test')
+  # Used by cleanup to find corresponding test databases for each dev database
+  # Customize if your database names use different suffixes (e.g., '_dev', '_test')
+  # config.development_suffix = '_development'
+  # config.test_suffix = '_test'
+end

data/sig/branch_db.rbs

@@ -0,0 +1,4 @@
+module BranchDb
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: branch_db
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ali Hamdi Ali Fadel
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Creates isolated database copies for each git branch, enabling parallel
+  feature development without schema conflicts.
+email:
+- aliosm1997@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/branch_db.rb
+- lib/branch_db/cleaner.rb
+- lib/branch_db/cloner.rb
+- lib/branch_db/configuration.rb
+- lib/branch_db/git_utils.rb
+- lib/branch_db/logging.rb
+- lib/branch_db/naming.rb
+- lib/branch_db/pg_utils.rb
+- lib/branch_db/preparer.rb
+- lib/branch_db/railtie.rb
+- lib/branch_db/tasks/branch_db.rake
+- lib/branch_db/version.rb
+- lib/generators/branch_db/install_generator.rb
+- lib/generators/branch_db/templates/initializer.rb
+- sig/branch_db.rbs
+homepage: https://github.com/milkstrawai/branch_db
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/milkstrawai/branch_db
+  source_code_uri: https://github.com/milkstrawai/branch_db
+  changelog_uri: https://github.com/milkstrawai/branch_db/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Automatic per-branch PostgreSQL databases for Rails development
+test_files: []