unsort_db_schema_columns 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2d5ae8c8bb1699839dfbbd549d0c82241a2d5f8625227057b8a541f04c8485cb
+  data.tar.gz: 153946257a01842d4a7957d9e36ac0ce0fcd5dc9394de43f25ec941921730dad
+SHA512:
+  metadata.gz: 4166346b74a7139b5c00e84f12e5e3ef5fa3fce72e8f7c7b918063690e6c23186bd814db0408b85f9ecbb1f6b6d561fe88d4ed29fb3072b2c9970200aa856215
+  data.tar.gz: '096ad720d60c32088ea1a4f634455cbdf9d1c67d3782197fd034302b078fac79fab14b70a15c873959c12894ae546d11d444e33270f271aa6bdd0f7600d672af'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jake Moffatt
+
+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,62 @@
+# unsort_db_schema_columns
+
+Restore the natural (database ordinal) column order in Rails `schema.rb` dumps.
+
+## Why this exists
+
+In [rails/rails#53281](https://github.com/rails/rails/pull/53281), Rails 8 changed `ActiveRecord::SchemaDumper` to sort table columns alphabetically. The intent was to reduce merge conflicts when two developers add migrations to the same table on parallel branches.
+
+The downside is that `schema.rb` no longer reflects the actual column layout of the database. That breaks several real workflows:
+
+- **`db:schema:load` for production parity.** Since Rails 8 ([#52830](https://github.com/rails/rails/pull/52830)), a fresh `db:migrate` loads `schema.rb` instead of replaying migrations. With sorting on, freshly-loaded databases have a different column order than production databases built incrementally from migrations.
+- **Postgres column-alignment padding.** Postgres pads columns to alignment boundaries; deliberate column ordering (e.g. 8-byte → 4-byte → variable-length) can meaningfully reduce table size. Alphabetical sorting destroys any layout chosen for this reason.
+- **`SELECT *` and bulk-import pipelines.** Tools like `pg_dump`/`mysqldump` round-trips, `PG::Connection#put_copy_data`, and CSV import/export depend on ordinal column position. Mismatched dev/prod column order breaks them.
+- **`add_column :after`/`:before`.** Rails supports positional column options in migrations. With alphabetical sorting in the dump, those options have no effect on schema-loaded databases.
+- **Gems that read `columns_hash` order.** The Rails change affects in-memory ordering after schema reload, not just the file (e.g. it broke a label-picking heuristic in Bullet Train).
+
+For full discussion, see [PR #55414](https://github.com/rails/rails/pull/55414) (opt-in restoration), [PR #56842](https://github.com/rails/rails/pull/56842) (full revert), and the original [PR #53281](https://github.com/rails/rails/pull/53281).
+
+## Who should use this
+
+You probably want this gem if any of these are true:
+
+- You use `db:schema:load` (or Rails 8's `db:migrate` on fresh DBs) to provision new environments and need it to match production column order.
+- You hand-tune column order in migrations for Postgres alignment-padding reasons.
+- You have CSV import/export, `pg_dump` round-trip, or `put_copy_data` pipelines.
+- You use `add_column :after` / `:before` and expect it to stick.
+
+You probably don't need it if you're a small team where merge conflicts in `schema.rb` were the bigger pain than any of the above.
+
+## Install
+
+```ruby
+# Gemfile
+gem "unsort_db_schema_columns"
+```
+
+That's it. A Railtie auto-applies the patch when ActiveRecord loads.
+
+To regenerate `schema.rb` in DB-natural order:
+
+```sh
+bin/rails db:schema:dump
+```
+
+Note: the gem only affects future dumps. The `schema.rb` already on disk is whatever was last committed. To get a correct natural-order `schema.rb`, run `db:schema:dump` against a database whose column order matches production (typically one built by replaying migrations, not loaded from a sorted schema).
+
+## How it works
+
+Prepends `ActiveRecord::SchemaDumper` and overrides `#table` with a copy of the upstream method that omits the `.sort_by(&:name)` call introduced in PR #53281. A boot-time warning fires if loaded against an untested ActiveRecord major version, since the copied method body could drift.
+
+## Why only columns?
+
+`SchemaDumper` also sorts tables, indexes, foreign keys, check constraints, and unique constraints. Those sorts have been in Rails for years (some since 2009) and this gem leaves them alone — only column ordering inside a table has functional consequences in the database engine (Postgres alignment padding, `SELECT *` ordinal position, `pg_dump`/`put_copy_data` round-trips, `add_column :after`/`:before`). Tables, indexes, and constraints are independent named objects; the order they're created has no effect on engine behavior, so sorting them in `schema.rb` is pure diff-stability with no downside.
+
+## Caveats
+
+- Coupled to ActiveRecord 8.x's `SchemaDumper#table` method body. When you upgrade Rails, re-diff against [`activerecord/lib/active_record/schema_dumper.rb`](https://github.com/rails/rails/blob/main/activerecord/lib/active_record/schema_dumper.rb) and bump the version constraint here.
+- The merge-conflict problem #53281 was solving is back. That's the intended trade.
+
+## License
+
+MIT.

data/lib/unsort_db_schema_columns/railtie.rb

@@ -0,0 +1,11 @@
+require "rails/railtie"
+
+module UnsortDbSchemaColumns
+  class Railtie < ::Rails::Railtie
+    initializer "unsort_db_schema_columns.patch_schema_dumper" do
+      ActiveSupport.on_load(:active_record) do
+        require "unsort_db_schema_columns/schema_dumper_patch"
+      end
+    end
+  end
+end

data/lib/unsort_db_schema_columns/schema_dumper_patch.rb

@@ -0,0 +1,104 @@
+require "active_record"
+require "active_record/schema_dumper"
+
+module UnsortDbSchemaColumns
+  # Restores the pre-#53281 behavior: dump columns in the order the database
+  # returns them (ordinal position), instead of alphabetically by name.
+  #
+  # We override the entire #table method because Rails sorts inline:
+  #   columns.sort_by(&:name).each do |column|
+  # The body below is copied from
+  # activerecord/lib/active_record/schema_dumper.rb at the Rails 8.x main
+  # branch, with that single `.sort_by(&:name)` removed. Verified against
+  # Rails 8.0.x. If you upgrade Rails and this gem hasn't, watch for an
+  # UnexpectedRailsVersion warning at boot.
+  module SchemaDumperPatch
+    def table(table, stream)
+      columns = @connection.columns(table)
+      begin
+        self.table_name = table
+
+        tbl = StringIO.new
+
+        # first dump primary key column
+        if @connection.respond_to?(:primary_keys)
+          pk = @connection.primary_keys(table)
+          pk = pk.first unless pk.size > 1
+        else
+          pk = @connection.primary_key(table)
+        end
+
+        tbl.print "  create_table #{remove_prefix_and_suffix(table).inspect}"
+
+        case pk
+        when String
+          tbl.print ", primary_key: #{pk.inspect}" unless pk == "id"
+          pkcol = columns.detect { |c| c.name == pk }
+          if pkcol
+            pkcolspec = column_spec_for_primary_key(pkcol)
+            if pkcolspec.present?
+              if pkcolspec != pkcolspec.slice(:id, :default)
+                pkcolspec = { id: { type: pkcolspec.delete(:id), **pkcolspec }.compact }
+              end
+              tbl.print ", #{format_colspec(pkcolspec)}"
+            end
+          end
+        when Array
+          tbl.print ", primary_key: #{pk.inspect}"
+        else
+          tbl.print ", id: false"
+        end
+
+        table_options = @connection.table_options(table)
+        if table_options.present?
+          tbl.print ", #{format_options(table_options)}"
+        end
+
+        tbl.puts ", force: :cascade do |t|"
+
+        # then dump all non-primary key columns -- in NATURAL DB order, not sorted
+        columns.each do |column|
+          raise StandardError, "Unknown type '#{column.sql_type}' for column '#{column.name}'" unless @connection.valid_type?(column.type)
+          next if column.name == pk
+
+          type, colspec = column_spec(column)
+          if type.is_a?(Symbol)
+            tbl.print "    t.#{type} #{column.name.inspect}"
+          else
+            tbl.print "    t.column #{column.name.inspect}, #{type.inspect}"
+          end
+          tbl.print ", #{format_colspec(colspec)}" if colspec.present?
+          tbl.puts
+        end
+
+        indexes_in_create(table, tbl)
+        remaining = check_constraints_in_create(table, tbl) if @connection.supports_check_constraints?
+        exclusion_constraints_in_create(table, tbl) if @connection.supports_exclusion_constraints?
+        unique_constraints_in_create(table, tbl) if @connection.supports_unique_constraints?
+
+        tbl.puts "  end"
+
+        if remaining
+          tbl.puts
+          tbl.print remaining.string
+        end
+
+        stream.print tbl.string
+      rescue => e
+        stream.puts "# Could not dump table #{table.inspect} because of following #{e.class}"
+        stream.puts "#   #{e.message}"
+        stream.puts
+      ensure
+        self.table_name = nil
+      end
+    end
+  end
+end
+
+ActiveRecord::SchemaDumper.prepend(UnsortDbSchemaColumns::SchemaDumperPatch)
+
+unless ActiveRecord::VERSION::MAJOR == 8
+  warn "[unsort_db_schema_columns] Tested against ActiveRecord 8.x; running on " \
+       "#{ActiveRecord::VERSION::STRING}. Verify schema dumps look right; " \
+       "the upstream SchemaDumper#table method may have drifted."
+end

data/lib/unsort_db_schema_columns/version.rb

@@ -0,0 +1,3 @@
+module UnsortDbSchemaColumns
+  VERSION = "0.1.0"
+end

data/lib/unsort_db_schema_columns.rb

@@ -0,0 +1,3 @@
+require "unsort_db_schema_columns/version"
+require "unsort_db_schema_columns/railtie" if defined?(Rails::Railtie)
+require "unsort_db_schema_columns/schema_dumper_patch" unless defined?(Rails::Railtie)

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: unsort_db_schema_columns
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jake Moffatt
+bindir: bin
+cert_chain: []
+date: 2026-05-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: |
+  Rails 8 (PR #53281) sorts schema.rb columns alphabetically. That breaks
+  db:schema:load parity with production, Postgres column-alignment padding,
+  add_column :after/:before, and bulk-import pipelines that depend on
+  SELECT * column order. This gem prepends ActiveRecord::SchemaDumper to
+  dump columns in the order the database actually stores them.
+email:
+- jake.moffatt@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/unsort_db_schema_columns.rb
+- lib/unsort_db_schema_columns/railtie.rb
+- lib/unsort_db_schema_columns/schema_dumper_patch.rb
+- lib/unsort_db_schema_columns/version.rb
+homepage: https://github.com/jakeonrails/unsort-db-schema-columns
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jakeonrails/unsort-db-schema-columns
+  source_code_uri: https://github.com/jakeonrails/unsort-db-schema-columns
+  bug_tracker_uri: https://github.com/jakeonrails/unsort-db-schema-columns/issues
+  changelog_uri: https://github.com/jakeonrails/unsort-db-schema-columns/blob/main/README.md
+  rubygems_mfa_required: 'true'
+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: 3.6.2
+specification_version: 4
+summary: Restore natural (database ordinal) column order in Rails schema.rb dumps.
+test_files: []