activerecord-postgresql-branched 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39dd95c063dde3c85a789ac3d6b5a0775bd0c95e39b7e68f2a2c33f9d50b645f
-  data.tar.gz: 2eaf350fe45a3cbb60aa16c2024c51af3e219ac99f8bc3e02e46fef4c68af2ec
+  metadata.gz: 4824fa89d3e5d0b010916b43302ec81d5190f84ba520a48f9bc8f4b629e30d6f
+  data.tar.gz: 423dd436e06d97866c3866a7c139ee932501495c603d7ce2a775211d06fb8190
 SHA512:
-  metadata.gz: 5b9b1813347f21ce285180b6ac2e9f3a88e1e752ec9521fc615dcd7ee8392310b3ac81c60875cdc4861b6c86db0497c0274d8a405e070e38ae6ac2450ec28592
-  data.tar.gz: 0fa9c515e10ff4a8cdf21537b5b271198f8b804df8e14fba9ea06afdb830052423b7c014781476fd6600da8188009a89298381aa888ead775ce8bf57aaf6129f
+  metadata.gz: 67ff1ed660c4b1c442235624b64b4c5c2b1fed7a632957b3aa64b622a7c1340aa1e3e3f3b03368ec63d508131f4d29f5fca43fe440c277a1c7893e95f1f69c34
+  data.tar.gz: b9a96791beaca51e65470d50f0a2bc92991c16f432cc47c437259cbc3ef860171e45b2d0e72de35fdae5c7d10cb4edfacb30795d66f753346cc2435f9223fdd2

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.3.0
+
+- Remove primary branch concept — every branch gets its own schema equally
+- Add shadow interception for `add_foreign_key`, `remove_foreign_key`, `add_check_constraint`, `remove_check_constraint`, `validate_foreign_key`, `validate_check_constraint`
+- Add `db:branch:console` rake task — opens psql with the branch `search_path`
+- Simplify branch resolution to `PGBRANCH` env var with git fallback
+- Remove `branch_override` config option and `BRANCH` env var
+- `db:branch:prune` accepts `KEEP=branch1,branch2` for explicit control
+- Fix railtie to reuse the adapter's existing BranchManager
+- Fix redundant Shadow instantiation in migration table shadowing
+- Quote schema identifiers consistently in shadow SQL
+
 ## 0.1.0
 
 Initial release.

data/README.md

@@ -1,20 +1,16 @@
 # 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.
+A Rails database adapter that gives each branch its own PostgreSQL schema. Your database structure follows your branch, just like your code does.
 
 ## The problem
 
-You have three agents working simultaneously in three worktrees:
+You're working on a feature branch. You write a migration that adds a column to `users`. You run it. Then you need to switch branches — a review, a hotfix, something urgent.
 
-- `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
+The other branch knows nothing about that column. But your development database does. `schema.rb` is dirty. Migrations are out of sync. If the other branch has its own migration, you now have two branches' worth of structural changes in one database with no way to tell which change belongs where.
 
-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.
+You either undo your migration before switching (and redo it when you come back), maintain multiple databases by hand, or just live with the mess. None of these are good.
 
-This adapter makes branching the database as cheap as branching the code.
+Git solved this problem for code decades ago. This adapter solves it for your database.
 
 ## Installation
 
@@ -30,82 +26,67 @@ development:
   database: myapp_development
 ```
 
-That's it. No Postgres extensions, no environment variables, no initializers.
+Set the `PGBRANCH` environment variable to name your branch, or let the adapter detect it from git automatically:
+
+```bash
+export PGBRANCH=feature/payments
+```
+
+That's it. No PostgreSQL extensions, no initializers, no extra configuration.
 
 ## How it works
 
-On connection, the adapter reads the current git branch, creates a dedicated Postgres schema for it, and sets `search_path`:
+On connection, the adapter creates a dedicated PostgreSQL schema for the current branch and sets `search_path`:
 
 ```
-git branch: feature/payments
+PGBRANCH=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.
+New tables go into the branch schema. Queries against tables that don't exist in the branch schema fall through to `public` via standard PostgreSQL name resolution. No data copying for reads.
 
-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.
+### The shadow rule
 
-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.
+When a migration modifies a table that exists in `public` but not yet in the branch schema, the adapter **shadows** it first — copies the table structure and data into the branch schema, then applies the DDL to the copy:
 
-## 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) %>
 ```
+add_column :users, :bio, :string
 
-```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 ...
+1. CREATE TABLE branch_feature_payments.users (LIKE public.users INCLUDING ALL)
+2. INSERT INTO branch_feature_payments.users SELECT * FROM public.users
+3. ALTER TABLE users ADD COLUMN bio VARCHAR
 ```
 
-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.
+The public table is never touched. Step 3 operates on the shadow because `search_path` resolves `users` to the branch schema first.
 
-### Cleanup
+This applies to any DDL that modifies an existing table: `add_column`, `remove_column`, `add_index`, `add_foreign_key`, `drop_table`, and so on.
 
-After agents finish:
+### schema.rb stays clean
 
-```bash
-rails db:branch:prune
-```
+`db:schema:dump` presents a unified view as if everything lived in `public`:
 
-Compares branch schemas against `git branch --list` and drops any that no longer have a corresponding local branch. One command, all stale schemas gone.
+- Branch-local tables appear without schema prefixes
+- Shadowed tables show the branch version (with new columns, dropped indexes, etc.)
+- Public tables the branch hasn't touched are included as normal
 
-For specific branches:
+The diff for a schema change looks exactly as it always has. Switch branches, and `schema.rb` reflects that branch's database state — not the accumulated mess of every migration you've run lately.
 
-```bash
-rails db:branch:discard BRANCH=agent-0
-```
+## Switching branches
 
-## Rake tasks
+This is the whole point. When you switch git branches:
 
-```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
-```
+- The new branch gets its own schema (created on first connection if needed)
+- Its migrations are tracked independently
+- Tables it hasn't touched fall through to `public`
+- Tables it has modified are isolated in its own schema
 
-## Configuration
+Switch back, and your previous branch's state is exactly where you left it.
 
-```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
-```
+## Deploying
 
-The `PGBRANCH` or `BRANCH` environment variables also work for explicit branch selection.
+The adapter is for development and test only. Production and staging use the standard `postgresql` adapter — migrations land directly in the database as they always have. The canonical schema advances through your normal deployment process.
 
 ## Rebasing
 
@@ -115,35 +96,55 @@ 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.
+`db:branch:reset` drops the branch schema. Queries fall through to `public`. Re-running `db:migrate` reapplies your branch's migrations on top of the current baseline.
 
-## The merge story
+## Parallel agents
 
-The adapter does not merge. Git does.
+The same isolation that helps you switch branches also helps when running multiple AI agents in parallel, each on its own worktree:
 
-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
+```bash
+PGBRANCH=agent-0 bundle exec rails ...
+PGBRANCH=agent-1 bundle exec rails ...
+PGBRANCH=agent-2 bundle exec rails ...
+```
 
-## schema.rb
+Each agent gets full isolation. No locks, no coordination. When an agent's work is done:
 
-`db:schema:dump` presents a unified view of the current branch as if everything lived in `public`:
+```bash
+rails db:branch:discard BRANCH=agent-0
+```
 
-- 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
+## 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 tables in the current branch schema
+rails db:branch:prune               # drop stale schemas (KEEP=main,feature/x or auto-detect from git)
+rails db:branch:console             # open psql with the branch search_path
+```
+
+### psql
+
+`psql` connects directly to PostgreSQL and knows nothing about branch schemas. Use `db:branch:console` instead — it launches psql with `search_path` set to your branch schema, so you see exactly what your Rails app sees.
+
+## Configuration
+
+The adapter needs one thing: a branch name. Resolution order:
+
+1. `PGBRANCH` environment variable
+2. `git branch --show-current` (automatic fallback)
+
+If neither is available, the adapter raises an error.
+
+All standard PostgreSQL connection parameters work as normal (`host`, `port`, `username`, `password`, etc.).
 
-The diff for a schema change looks exactly as it always has.
+**Do not set `schema_search_path` in database.yml** — it conflicts with the adapter's `search_path` management.
 
 ## 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
+- **Rails + PostgreSQL only** — uses PostgreSQL schemas and `search_path`
+- **Development and test only** — production should use the standard `postgresql` 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

@@ -17,6 +17,12 @@ module ActiveRecord
             add_index
             remove_index
             rename_index
+            add_foreign_key
+            remove_foreign_key
+            add_check_constraint
+            remove_check_constraint
+            validate_foreign_key
+            validate_check_constraint
             drop_table
             change_table
             bulk_change_table
@@ -25,17 +31,17 @@ module ActiveRecord
           def initialize(...)
             super
             @branch_manager = BranchManager.new(self, @config)
-            @shadow = Shadow.new(self, @branch_manager.branch_schema) unless @branch_manager.primary_branch?
+            @shadow = Shadow.new(self, @branch_manager.branch_schema)
           end
 
           def configure_connection
             super
-            @branch_manager.activate
+            @branch_manager.activate(@shadow)
           end
 
           SHADOW_BEFORE.each do |method|
             define_method(method) do |table_name, *args, **kwargs, &block|
-              @shadow&.call(table_name)
+              @shadow.call(table_name)
               super(table_name, *args, **kwargs, &block)
             end
           end
@@ -45,10 +51,9 @@ module ActiveRecord
           # 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)
+            @shadow.call(table_name)
             super
           rescue ActiveRecord::StatementInvalid => e
-            raise if @branch_manager.primary_branch?
             raise unless e.cause.is_a?(PG::UndefinedTable)
           end
 

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

@@ -12,16 +12,10 @@ module ActiveRecord
             @branch_schema = self.class.sanitise(@branch)
           end
 
-          def activate
-            return if primary_branch?
-
+          def activate(shadow)
             ensure_schema
             set_search_path
-            shadow_migration_tables
-          end
-
-          def primary_branch?
-            @branch == primary_branch_name
+            shadow_migration_tables(shadow)
           end
 
           def reset
@@ -32,11 +26,6 @@ module ActiveRecord
 
           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
 
@@ -56,8 +45,6 @@ module ActiveRecord
           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)}
@@ -75,14 +62,13 @@ module ActiveRecord
 
             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
+            max_slug = MAX_SCHEMA_LENGTH - PREFIX.bytesize - 9
             PREFIX + slug[0, max_slug] + "_" + hash
           end
 
           def prune(keep: nil)
-            active_schemas = if keep
+            keep_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("* ") }
@@ -97,37 +83,30 @@ module ActiveRecord
               WHERE schema_name LIKE 'branch_%'
             SQL
 
-            stale = all_branch_schemas.reject { |s| active_schemas.include?(s) }
+            stale = all_branch_schemas.reject { |s| keep_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
+          def self.resolve_branch_name
+            ENV["PGBRANCH"] || git_branch
           end
 
           private
 
           def resolve_branch
-            name = self.class.resolve_branch_name(@config)
+            name = self.class.resolve_branch_name
 
             if name.nil? || name.empty?
-              raise "Could not determine git branch. " \
-                    "Set branch_override in database.yml or the PGBRANCH environment variable."
+              raise "Could not determine branch. " \
+                    "Set 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
@@ -140,8 +119,7 @@ module ActiveRecord
             @connection.schema_search_path = "#{@branch_schema}, public"
           end
 
-          def shadow_migration_tables
-            shadow = Shadow.new(@connection, @branch_schema)
+          def shadow_migration_tables(shadow)
             shadow.call(ActiveRecord::Base.schema_migrations_table_name)
             shadow.call(ActiveRecord::Base.internal_metadata_table_name)
           end

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

@@ -9,17 +9,11 @@ module ActiveRecord
                 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"
+                desc "Drop a branch schema (current branch or BRANCH=name)"
                 task discard: :load_config do
                   manager = branch_manager
                   branch = ENV["BRANCH"] || manager.branch
@@ -43,9 +37,10 @@ module ActiveRecord
                   end
                 end
 
-                desc "Drop schemas for branches that no longer exist in git"
+                desc "Drop schemas not in KEEP list (or not matching local git branches)"
                 task prune: :load_config do
-                  pruned = branch_manager.prune
+                  keep = ENV["KEEP"]&.split(",")&.map(&:strip)
+                  pruned = branch_manager.prune(keep: keep)
 
                   if pruned.empty?
                     puts "No stale branch schemas found."
@@ -55,15 +50,9 @@ module ActiveRecord
                   end
                 end
 
-                desc "Show objects in the current branch schema vs public"
+                desc "Show objects in the current branch schema"
                 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?
@@ -73,12 +62,27 @@ module ActiveRecord
                     tables.each { |t| puts "  #{t}" }
                   end
                 end
+
+                desc "Open psql with the branch search_path"
+                task console: :load_config do
+                  manager = branch_manager
+                  config = ActiveRecord::Base.connection_db_config.configuration_hash
+
+                  env = { "PGOPTIONS" => "-c search_path=#{manager.branch_schema},public" }
+                  args = ["psql"]
+                  args.push("-h", config[:host].to_s) if config[:host]
+                  args.push("-p", config[:port].to_s) if config[:port]
+                  args.push("-U", config[:username].to_s) if config[:username]
+                  args.push(config[:database].to_s)
+
+                  puts "Connecting to #{config[:database]} as #{manager.branch_schema}..."
+                  exec(env, *args)
+                end
               end
             end
 
             def branch_manager
-              connection = ActiveRecord::Base.lease_connection
-              BranchManager.new(connection, connection.instance_variable_get(:@config))
+              ActiveRecord::Base.lease_connection.branch_manager
             end
           end
 

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

@@ -8,9 +8,7 @@ module ActiveRecord
           private
 
           def on_branch?
-            @connection.respond_to?(:branch_manager) &&
-              @connection.branch_manager &&
-              !@connection.branch_manager.primary_branch?
+            @connection.respond_to?(:branch_manager)
           end
 
           def initialize(connection, options = {})

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

@@ -34,13 +34,14 @@ module ActiveRecord
           end
 
           def create_shadow(table)
+            quoted_branch = @connection.quote_column_name(@branch_schema)
             quoted_table = @connection.quote_column_name(table)
             @connection.execute(<<~SQL)
-              CREATE TABLE #{@branch_schema}.#{quoted_table}
+              CREATE TABLE #{quoted_branch}.#{quoted_table}
                 (LIKE public.#{quoted_table} INCLUDING ALL)
             SQL
             @connection.execute(<<~SQL)
-              INSERT INTO #{@branch_schema}.#{quoted_table}
+              INSERT INTO #{quoted_branch}.#{quoted_table}
                 SELECT * FROM public.#{quoted_table}
             SQL
           end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-postgresql-branched
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Carl Dawson