activerecord-postgresql-branched 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 39dd95c063dde3c85a789ac3d6b5a0775bd0c95e39b7e68f2a2c33f9d50b645f
+  data.tar.gz: 2eaf350fe45a3cbb60aa16c2024c51af3e219ac99f8bc3e02e46fef4c68af2ec
+SHA512:
+  metadata.gz: 5b9b1813347f21ce285180b6ac2e9f3a88e1e752ec9521fc615dcd7ee8392310b3ac81c60875cdc4861b6c86db0497c0274d8a405e070e38ae6ac2450ec28592
+  data.tar.gz: 0fa9c515e10ff4a8cdf21537b5b271198f8b804df8e14fba9ea06afdb830052423b7c014781476fd6600da8188009a89298381aa888ead775ce8bf57aaf6129f

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- PostgreSQL adapter that isolates each git branch in its own Postgres schema
+- Shadow rule: automatically copies public tables before branch-local DDL
+- Clean `schema.rb` output with no branch schema references
+- `schema_migrations` and `ar_internal_metadata` isolated per branch
+- Schema names truncated to 63 bytes with collision-safe hashing
+- Rake tasks: `db:branch:reset`, `discard`, `list`, `diff`, `prune`
+- Branch override via `branch_override` config or `PGBRANCH` env var

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carl Dawson
+
+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,149 @@
+# activerecord-postgresql-branched
+
+Database isolation for parallel development. Each git branch (or agent) gets its own Postgres schema. Migrations run in isolation. Nobody steps on anyone else's work.
+
+Built for teams running multiple AI coding agents in parallel, each on its own worktree, all sharing one database.
+
+## The problem
+
+You have three agents working simultaneously in three worktrees:
+
+- `agent-0` adds a `payments` table and alters `users`
+- `agent-1` adds a `bio` column to `users`
+- `agent-2` drops a legacy table and adds indexes
+
+They share one dev database. Every migration collides. Every agent breaks every other agent. You spend more time untangling the database than reviewing the code.
+
+This adapter makes branching the database as cheap as branching the code.
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'activerecord-postgresql-branched'
+```
+
+```yaml
+# config/database.yml
+development:
+  adapter: postgresql_branched
+  database: myapp_development
+```
+
+That's it. No Postgres extensions, no environment variables, no initializers.
+
+## How it works
+
+On connection, the adapter reads the current git branch, creates a dedicated Postgres schema for it, and sets `search_path`:
+
+```
+git branch: feature/payments
+schema:      branch_feature_payments
+search_path: branch_feature_payments, public
+```
+
+New tables go into the branch schema. Queries against existing tables fall through to `public` via standard Postgres name resolution.
+
+When a migration modifies a table that exists in `public`, the adapter shadows it first -- copies the table and its data into the branch schema, then applies the DDL to the copy. The public table is never touched.
+
+On the primary branch (`main` by default), the adapter stands aside entirely. Migrations land in `public` as normal. When `public` advances, every branch sees the changes immediately via `search_path` fallthrough.
+
+## Agentic workflows
+
+Give each agent its own branch identity:
+
+```yaml
+# config/database.yml
+development:
+  adapter: postgresql_branched
+  database: myapp_development
+  branch_override: <%= ENV.fetch("AGENT_BRANCH", nil) %>
+```
+
+```bash
+# Launch agents with isolated schemas
+AGENT_BRANCH=agent-0 bundle exec rails ...
+AGENT_BRANCH=agent-1 bundle exec rails ...
+AGENT_BRANCH=agent-2 bundle exec rails ...
+```
+
+Or in a worktree-per-agent setup, each worktree is on its own git branch and the adapter picks it up automatically. No configuration needed beyond the adapter name.
+
+### Cleanup
+
+After agents finish:
+
+```bash
+rails db:branch:prune
+```
+
+Compares branch schemas against `git branch --list` and drops any that no longer have a corresponding local branch. One command, all stale schemas gone.
+
+For specific branches:
+
+```bash
+rails db:branch:discard BRANCH=agent-0
+```
+
+## Rake tasks
+
+```bash
+rails db:branch:reset    # drop and recreate current branch schema
+rails db:branch:discard  # drop current branch schema (or BRANCH=name)
+rails db:branch:list     # list all branch schemas and their sizes
+rails db:branch:diff     # show objects in this branch vs public
+rails db:branch:prune    # drop schemas for branches no longer in git
+```
+
+## Configuration
+
+```yaml
+development:
+  adapter: postgresql_branched
+  database: myapp_development
+  primary_branch: main        # default, can be 'master', 'trunk', etc.
+  branch_override: agent-0    # bypass git, set branch explicitly
+```
+
+The `PGBRANCH` or `BRANCH` environment variables also work for explicit branch selection.
+
+## Rebasing
+
+```bash
+git fetch && git rebase origin/main
+rails db:branch:reset
+rails db:migrate
+```
+
+`db:branch:reset` drops the branch schema. `search_path` falls through to the updated `public`. Re-running `db:migrate` reapplies your branch's migrations on top of the new baseline.
+
+## The merge story
+
+The adapter does not merge. Git does.
+
+1. Agent writes migrations on its branch
+2. Adapter isolates them in a branch schema automatically
+3. PR merged into `main`
+4. Team pulls `main`, runs `db:migrate`
+5. Adapter stands aside (primary branch), migrations land in `public`
+6. `schema.rb` updated and committed
+7. All active branch schemas see updated `public` via fallthrough
+
+## schema.rb
+
+`db:schema:dump` presents a unified view of the current branch as if everything lived in `public`:
+
+- Branch-local tables appear without the `branch_` prefix
+- Shadowed tables show the branch version
+- Public tables the branch hasn't touched are included as normal
+- No schema references, no branch artifacts
+
+The diff for a schema change looks exactly as it always has.
+
+## Limitations
+
+- **Rails + Postgres only** -- uses Postgres schemas and `search_path`
+- **Dev only** -- production and staging should use the standard `postgresql` adapter
+- **No `schema_search_path` in database.yml** -- it will conflict with the adapter
+- **Non-ActiveRecord DDL** -- raw SQL outside of migrations bypasses the shadow rule
+- **Sequences on shadowed tables** -- `rename_table` on a shadowed table with serial columns works, but the sequence keeps its original name

data/lib/active_record/connection_adapters/postgresql/branched/adapter.rb

@@ -0,0 +1,66 @@
+module ActiveRecord
+  module ConnectionAdapters
+    module PostgreSQL
+      module Branched
+        class Adapter < ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
+          ADAPTER_NAME = "PostgreSQL Branched"
+
+          SHADOW_BEFORE = %i[
+            add_column
+            remove_column
+            rename_column
+            change_column
+            change_column_default
+            change_column_null
+            change_column_comment
+            change_table_comment
+            add_index
+            remove_index
+            rename_index
+            drop_table
+            change_table
+            bulk_change_table
+          ].freeze
+
+          def initialize(...)
+            super
+            @branch_manager = BranchManager.new(self, @config)
+            @shadow = Shadow.new(self, @branch_manager.branch_schema) unless @branch_manager.primary_branch?
+          end
+
+          def configure_connection
+            super
+            @branch_manager.activate
+          end
+
+          SHADOW_BEFORE.each do |method|
+            define_method(method) do |table_name, *args, **kwargs, &block|
+              @shadow&.call(table_name)
+              super(table_name, *args, **kwargs, &block)
+            end
+          end
+
+          # rename_table needs special handling: the shadow table's sequences
+          # live in public, but Rails' rename_table tries to rename them using
+          # the branch schema. The table and index renames succeed before the
+          # sequence rename fails, so we rescue the sequence error.
+          def rename_table(table_name, new_name, **options)
+            @shadow&.call(table_name)
+            super
+          rescue ActiveRecord::StatementInvalid => e
+            raise if @branch_manager.primary_branch?
+            raise unless e.cause.is_a?(PG::UndefinedTable)
+          end
+
+          attr_reader :branch_manager
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::ConnectionAdapters.register(
+  "postgresql_branched",
+  "ActiveRecord::ConnectionAdapters::PostgreSQL::Branched::Adapter",
+  "activerecord-postgresql-branched"
+)

data/lib/active_record/connection_adapters/postgresql/branched/branch_manager.rb

@@ -0,0 +1,161 @@
+module ActiveRecord
+  module ConnectionAdapters
+    module PostgreSQL
+      module Branched
+        class BranchManager
+          attr_reader :branch, :branch_schema
+
+          def initialize(connection, config)
+            @connection = connection
+            @config = config
+            @branch = resolve_branch
+            @branch_schema = self.class.sanitise(@branch)
+          end
+
+          def activate
+            return if primary_branch?
+
+            ensure_schema
+            set_search_path
+            shadow_migration_tables
+          end
+
+          def primary_branch?
+            @branch == primary_branch_name
+          end
+
+          def reset
+            drop_schema
+            ensure_schema
+            set_search_path
+          end
+
+          def discard(branch_name = @branch)
+            schema = self.class.sanitise(branch_name)
+
+            if schema == self.class.sanitise(primary_branch_name)
+              raise "Cannot discard the primary branch schema"
+            end
+
+            @connection.execute("DROP SCHEMA IF EXISTS #{quote(schema)} CASCADE")
+          end
+
+          def list
+            @connection.select_rows(<<~SQL)
+              SELECT s.schema_name,
+                     COALESCE(pg_size_pretty(sum(pg_total_relation_size(
+                       quote_ident(t.table_schema) || '.' || quote_ident(t.table_name)
+                     ))), '0 bytes') AS size
+              FROM information_schema.schemata s
+              LEFT JOIN information_schema.tables t
+                ON t.table_schema = s.schema_name AND t.table_type = 'BASE TABLE'
+              WHERE s.schema_name LIKE 'branch_%'
+              GROUP BY s.schema_name
+              ORDER BY s.schema_name
+            SQL
+          end
+
+          def diff
+            return [] if primary_branch?
+
+            @connection.select_values(<<~SQL)
+              SELECT table_name FROM information_schema.tables
+              WHERE table_schema = #{@connection.quote(@branch_schema)}
+                AND table_type = 'BASE TABLE'
+              ORDER BY table_name
+            SQL
+          end
+
+          MAX_SCHEMA_LENGTH = 63
+          PREFIX = "branch_"
+
+          def self.sanitise(branch)
+            slug = branch.downcase.gsub(/[\/\-\.]/, "_").gsub(/[^a-z0-9_]/, "")
+            schema = PREFIX + slug
+
+            return schema if schema.bytesize <= MAX_SCHEMA_LENGTH
+
+            # Truncate and append a short hash to avoid collisions
+            hash = Digest::SHA256.hexdigest(slug)[0, 8]
+            max_slug = MAX_SCHEMA_LENGTH - PREFIX.bytesize - 9 # 9 = underscore + 8 char hash
+            PREFIX + slug[0, max_slug] + "_" + hash
+          end
+
+          def prune(keep: nil)
+            active_schemas = if keep
+              Array(keep).map { |b| self.class.sanitise(b) }.to_set
+            else
+              git_branches = `git branch --list 2>/dev/null`.lines.map { |l| l.strip.delete_prefix("* ") }
+              if git_branches.empty?
+                raise "No git branches found. Pass branch names explicitly: prune(keep: ['main', 'feature/x'])"
+              end
+              git_branches.map { |b| self.class.sanitise(b) }.to_set
+            end
+
+            all_branch_schemas = @connection.select_values(<<~SQL)
+              SELECT schema_name FROM information_schema.schemata
+              WHERE schema_name LIKE 'branch_%'
+            SQL
+
+            stale = all_branch_schemas.reject { |s| active_schemas.include?(s) }
+            stale.each do |schema|
+              @connection.execute("DROP SCHEMA IF EXISTS #{quote(schema)} CASCADE")
+            end
+            stale
+          end
+
+          def self.resolve_branch_name(config)
+            config[:branch_override]&.to_s ||
+              ENV["BRANCH"] ||
+              ENV["PGBRANCH"] ||
+              git_branch
+          end
+
+          private
+
+          def resolve_branch
+            name = self.class.resolve_branch_name(@config)
+
+            if name.nil? || name.empty?
+              raise "Could not determine git branch. " \
+                    "Set branch_override in database.yml or the PGBRANCH environment variable."
+            end
+
+            name
+          end
+
+          def primary_branch_name
+            (@config[:primary_branch] || "main").to_s
+          end
+
+          def ensure_schema
+            @connection.execute("CREATE SCHEMA IF NOT EXISTS #{quote(@branch_schema)}")
+          end
+
+          def drop_schema
+            @connection.execute("DROP SCHEMA IF EXISTS #{quote(@branch_schema)} CASCADE")
+          end
+
+          def set_search_path
+            @connection.schema_search_path = "#{@branch_schema}, public"
+          end
+
+          def shadow_migration_tables
+            shadow = Shadow.new(@connection, @branch_schema)
+            shadow.call(ActiveRecord::Base.schema_migrations_table_name)
+            shadow.call(ActiveRecord::Base.internal_metadata_table_name)
+          end
+
+          def quote(identifier)
+            @connection.quote_column_name(identifier)
+          end
+
+          def self.git_branch
+            result = `git branch --show-current 2>/dev/null`.strip
+            result.empty? ? nil : result
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/postgresql/branched/railtie.rb

@@ -0,0 +1,96 @@
+module ActiveRecord
+  module ConnectionAdapters
+    module PostgreSQL
+      module Branched
+        class Railtie < Rails::Railtie
+          rake_tasks do
+            namespace :db do
+              namespace :branch do
+                desc "Drop and recreate the current branch schema"
+                task reset: :load_config do
+                  manager = branch_manager
+
+                  if manager.primary_branch?
+                    puts "On primary branch (#{manager.branch}), nothing to reset."
+                    next
+                  end
+
+                  manager.reset
+                  puts "Reset branch schema #{manager.branch_schema}. Run db:migrate to reapply branch migrations."
+                end
+
+                desc "Drop the current branch schema entirely"
+                task discard: :load_config do
+                  manager = branch_manager
+                  branch = ENV["BRANCH"] || manager.branch
+                  schema = BranchManager.sanitise(branch)
+
+                  manager.discard(branch)
+                  puts "Discarded branch schema #{schema}."
+                rescue => e
+                  puts e.message
+                end
+
+                desc "List all branch schemas and their sizes"
+                task list: :load_config do
+                  rows = branch_manager.list
+
+                  if rows.empty?
+                    puts "No branch schemas found."
+                  else
+                    puts "Branch schemas:"
+                    rows.each { |name, size| puts "  #{name} (#{size})" }
+                  end
+                end
+
+                desc "Drop schemas for branches that no longer exist in git"
+                task prune: :load_config do
+                  pruned = branch_manager.prune
+
+                  if pruned.empty?
+                    puts "No stale branch schemas found."
+                  else
+                    puts "Pruned #{pruned.size} stale branch schema#{"s" if pruned.size > 1}:"
+                    pruned.each { |s| puts "  #{s}" }
+                  end
+                end
+
+                desc "Show objects in the current branch schema vs public"
+                task diff: :load_config do
+                  manager = branch_manager
+
+                  if manager.primary_branch?
+                    puts "On primary branch, no diff."
+                    next
+                  end
+
+                  tables = manager.diff
+
+                  if tables.empty?
+                    puts "No branch-local objects in #{manager.branch_schema}."
+                  else
+                    puts "Branch-local objects in #{manager.branch_schema}:"
+                    tables.each { |t| puts "  #{t}" }
+                  end
+                end
+              end
+            end
+
+            def branch_manager
+              connection = ActiveRecord::Base.lease_connection
+              BranchManager.new(connection, connection.instance_variable_get(:@config))
+            end
+          end
+
+          initializer "postgresql_branched.schema_dumper" do
+            ActiveSupport.on_load(:active_record) do
+              ActiveRecord::ConnectionAdapters::PostgreSQL::SchemaDumper.prepend(
+                ActiveRecord::ConnectionAdapters::PostgreSQL::Branched::SchemaDumperExtension
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/postgresql/branched/schema_dumper.rb

@@ -0,0 +1,65 @@
+require "stringio"
+
+module ActiveRecord
+  module ConnectionAdapters
+    module PostgreSQL
+      module Branched
+        module SchemaDumperExtension
+          private
+
+          def on_branch?
+            @connection.respond_to?(:branch_manager) &&
+              @connection.branch_manager &&
+              !@connection.branch_manager.primary_branch?
+          end
+
+          def initialize(connection, options = {})
+            super
+            @dump_schemas = ["public"] if on_branch?
+          end
+
+          def schemas(stream)
+            return if on_branch?
+            super
+          end
+
+          def tables(stream)
+            return super unless on_branch?
+
+            table_names = @connection.tables.uniq.sort
+            table_names.reject! { |t| ignored?(t) }
+
+            table_names.each_with_index do |table_name, index|
+              table(table_name, stream)
+              stream.puts if index < table_names.size - 1
+            end
+
+            if @connection.supports_foreign_keys?
+              fk_stream = StringIO.new
+              table_names.each { |tbl| foreign_keys(tbl, fk_stream) }
+              fk_string = fk_stream.string
+              if fk_string.length > 0
+                stream.puts
+                stream.print fk_string
+              end
+            end
+          end
+
+          def types(stream)
+            return super unless on_branch?
+
+            enums = @connection.enum_types
+            if enums.any?
+              stream.puts "  # Custom types defined in this database."
+              stream.puts "  # Note that some types may not work with other database engines. Be careful if changing database."
+              enums.sort.each do |name, values|
+                stream.puts "  create_enum #{name.inspect}, #{values.inspect}"
+              end
+              stream.puts
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/postgresql/branched/shadow.rb

@@ -0,0 +1,51 @@
+module ActiveRecord
+  module ConnectionAdapters
+    module PostgreSQL
+      module Branched
+        class Shadow
+          def initialize(connection, branch_schema)
+            @connection = connection
+            @branch_schema = branch_schema
+          end
+
+          def call(table_name)
+            table = table_name.to_s
+            return unless exists_in_public?(table)
+            return if already_shadowed?(table)
+
+            create_shadow(table)
+          end
+
+          private
+
+          def exists_in_public?(table)
+            @connection.select_value(<<~SQL) == 1
+              SELECT 1 FROM information_schema.tables
+              WHERE table_schema = 'public' AND table_name = #{@connection.quote(table)}
+            SQL
+          end
+
+          def already_shadowed?(table)
+            @connection.select_value(<<~SQL) == 1
+              SELECT 1 FROM information_schema.tables
+              WHERE table_schema = #{@connection.quote(@branch_schema)}
+                AND table_name = #{@connection.quote(table)}
+            SQL
+          end
+
+          def create_shadow(table)
+            quoted_table = @connection.quote_column_name(table)
+            @connection.execute(<<~SQL)
+              CREATE TABLE #{@branch_schema}.#{quoted_table}
+                (LIKE public.#{quoted_table} INCLUDING ALL)
+            SQL
+            @connection.execute(<<~SQL)
+              INSERT INTO #{@branch_schema}.#{quoted_table}
+                SELECT * FROM public.#{quoted_table}
+            SQL
+          end
+        end
+      end
+    end
+  end
+end

data/lib/activerecord-postgresql-branched.rb

@@ -0,0 +1,8 @@
+require "digest/sha2"
+require "set"
+require "active_record/connection_adapters/postgresql_adapter"
+require "active_record/connection_adapters/postgresql/branched/branch_manager"
+require "active_record/connection_adapters/postgresql/branched/shadow"
+require "active_record/connection_adapters/postgresql/branched/schema_dumper"
+require "active_record/connection_adapters/postgresql/branched/adapter"
+require "active_record/connection_adapters/postgresql/branched/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-postgresql-branched
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Carl Dawson
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A Rails database adapter that gives each git branch its own Postgres
+  schema. Migrations run in isolation. Nobody steps on anyone else's work.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/active_record/connection_adapters/postgresql/branched/adapter.rb
+- lib/active_record/connection_adapters/postgresql/branched/branch_manager.rb
+- lib/active_record/connection_adapters/postgresql/branched/railtie.rb
+- lib/active_record/connection_adapters/postgresql/branched/schema_dumper.rb
+- lib/active_record/connection_adapters/postgresql/branched/shadow.rb
+- lib/activerecord-postgresql-branched.rb
+homepage: https://github.com/carldaws/activerecord-postgresql-branched
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/carldaws/activerecord-postgresql-branched
+  changelog_uri: https://github.com/carldaws/activerecord-postgresql-branched/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Branch-aware PostgreSQL adapter for ActiveRecord
+test_files: []