pg_ha_migrations 1.8.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6858f02b9a874bbaf79865c789a490c9aa1140240537d0eded8f48486c6348f3
-  data.tar.gz: 733394b7f83821f71821816777765d982d1580761522e0751534d3e3c62f598b
+  metadata.gz: cd0329ccdae5b3bf68ac759bc0eca2dbc5089c3d91f9ee6444c6791a2bd42e93
+  data.tar.gz: ecf840233b36ede3ef278411bac124cefa32036b43d62119792a8d74ac126b5e
 SHA512:
-  metadata.gz: 55f3f8e3730fc11183e71cbf6ba9d32dabf1c8b0ec532da6861b47d045cffb348184350831f564999ecee22b601931ab577ca20f8c4e831e0d4b776babe21a58
-  data.tar.gz: e260ebe93cafba7f3119c41bd2594a797293713f95d072378dbc5733f176d86ce8a93c8a24b53b6fbb9ec77756f4db9ab5fdb92f6080de6ac0fb56e158e5b5d3
+  metadata.gz: f744006470a25bff85e10026f750e1cada2b49a19809cc2279208f9ec10ac86bfacf38dbbe32bd839f655475d0dde773d1c219b584c4a5cccc7c911f570c10bd
+  data.tar.gz: 5626ac149515ef764e63797cceed133c87d6032f22100a4940573a42a0b1ae483cbebc8a26596cc77494c4420e94e55d08e74b44ebe6fb83cd7f18e1a502d731

data/.github/workflows/ci.yml

@@ -5,20 +5,18 @@ jobs:
     strategy:
       matrix:
         pg:
-          - 11
-          - 12
           - 13
           - 14
           - 15
           - 16
         ruby:
-          - "3.0"
-          - "3.1"
           - "3.2"
+          - "3.3"
+          - "3.4"
         gemfile:
-          - rails_6.1
-          - rails_7.0
           - rails_7.1
+          - rails_7.2
+          - rails_8.0
     name: PostgreSQL ${{ matrix.pg }} - Ruby ${{ matrix.ruby }} - ${{ matrix.gemfile }}
     runs-on: ubuntu-latest
     env: # $BUNDLE_GEMFILE must be set at the job level, so it is set for all steps
@@ -27,7 +25,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Build postgres image and start the container
-        run: docker-compose up -d --build
+        run: docker compose up -d --build
         env:
           PGVERSION: ${{ matrix.pg }}
       - name: Setup Ruby using .ruby-version file

data/.ruby-version

@@ -1 +1 @@
-ruby-3.0
+ruby-3.4.2

data/Appraisals

@@ -1,11 +1,11 @@
-appraise "rails-6.1" do
-  gem "rails", "6.1.7.6"
+appraise "rails-7.1" do
+  gem "rails", "~> 7.1.0"
 end
 
-appraise "rails-7.0" do
-  gem "rails", "7.0.8"
+appraise "rails-7.2" do
+  gem "rails", "~> 7.2.0"
 end
 
-appraise "rails-7.1" do
-  gem "rails", "7.1.0"
+appraise "rails-8.0" do
+  gem "rails", "~> 8.0.0"
 end

data/Gemfile

@@ -4,4 +4,3 @@ git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in pg_ha_migrations.gemspec
 gemspec
-

data/README.md

@@ -30,7 +30,36 @@ Or install it yourself as:
 
     $ gem install pg_ha_migrations
 
-## Usage
+## Migration Safety
+
+There are two major classes of concerns we try to handle in the API:
+
+- Database safety (e.g., long-held locks)
+- Application safety (e.g., dropping columns the app uses)
+
+### Migration Method Renaming
+
+We rename migration methods with prefixes to explicitly denote their safety level:
+
+- `safe_*`: These methods check for both application and database safety concerns, prefer concurrent operations where available, set low lock timeouts where appropriate, and decompose operations into multiple safe steps.
+- `unsafe_*`: Using these methods is a signal that the DDL operation is not necessarily safe for a running application. They include basic safety features like safe lock acquisition and dependent object checking, but otherwise dispatch directly to the native ActiveRecord migration method.
+- `raw_*`: These methods are a direct dispatch to the native ActiveRecord migration method.
+
+Calling the original migration methods without a prefix will raise an error.
+
+The API is designed to be explicit yet remain flexible. There may be situations where invoking the `unsafe_*` method is preferred (or the only option available for definitionally unsafe operations).
+
+While `unsafe_*` methods were historically (before 2.0) pure wrappers for invoking the native ActiveRecord migration method, there is a class of problems that we can't handle easily without breaking that design rule a bit. For example, dropping a column is unsafe from an application perspective, so we make the application safety concerns explicit by using an `unsafe_` prefix. Using `unsafe_remove_column` calls out the need to audit the application to confirm the migration won't break the application. Because there are no safe alternatives we don't define a `safe_remove_column` analogue. However there are still conditions we'd like to assert before dropping a column. For example, dropping an unused column that's used in one or more indexes may be safe from an application perspective, but the cascading drop of the index won't use a `CONCURRENT` operation to drop the dependent indexes and is therefore unsafe from a database perspective.
+
+For `unsafe_*` migration methods which support checks of this type you can bypass the checks by passing an `:allow_dependent_objects` key in the method's `options` hash containing an array of dependent object types you'd like to allow. These checks will run by default, but you can opt-out by setting `config.check_for_dependent_objects = false` [in your configuration initializer](#configuration).
+
+### Disallowed Migration Methods
+
+We disallow the use of `unsafe_change_table`, as the equivalent operation can be composed with explicit `safe_*` / `unsafe_*` methods. If you _must_ use `change_table`, it is still available as `raw_change_table`.
+
+### Migration Method Arguments
+
+We believe the `force: true` option to ActiveRecord's `create_table` method is always unsafe because it's not possible to denote exactly how the current state will change. Therefore we disallow using `force: true` even when calling `unsafe_create_table`. This option is enabled by default, but you can opt-out by setting `config.allow_force_create_table = true` [in your configuration initializer](#configuration).
 
 ### Rollback
 
@@ -46,40 +75,36 @@ end
 
 and never use `def change`. We believe that this is the only safe approach in production environments. For development environments we iterate by recreating the database from scratch every time we make a change.
 
-### Migrations
+### Transactional DDL
 
-There are two major classes of concerns we try to handle in the API:
+Individual DDL statements in PostgreSQL are transactional by default (as are all Postgres statements). Concurrent index creation and removal are two exceptions: these utility commands manage their own transaction state (and each uses multiple transactions to achieve the desired concurrency).
 
-- Database safety (e.g., long-held locks)
-- Application safety (e.g., dropping columns the app uses)
+We [disable ActiveRecord's DDL transactions](./lib/pg_ha_migrations/hacks/disable_ddl_transaction.rb) (which wrap the entire migration file in a transaction) by default for the following reasons:
 
-We rename migration methods with prefixes denoting their safety level:
+* [Running multiple DDL statements inside a transaction acquires exclusive locks on all of the modified objects](https://medium.com/paypal-tech/postgresql-at-scale-database-schema-changes-without-downtime-20d3749ed680#cc22).
+* Acquired locks are held until the end of the transaction.
+* Multiple locks creates the possibility of deadlocks.
+* Increased exposure to long waits:
+  * Each newly acquired lock has its own timeout applied (so total lock time is additive).
+  * [Safe lock acquisition](#safely_acquire_lock_for_table) (which is used in each migration method where locks will be acquired) can issue multiple lock attempts on lock timeouts (with sleep delays between attempts).
 
-- `safe_*`: These methods check for both application and database safety concerns, prefer concurrent operations where available, set low lock timeouts where appropriate, and decompose operations into multiple safe steps.
-- `unsafe_*`: These methods are generally a direct dispatch to the native ActiveRecord migration method.
-
-Calling the original migration methods without a prefix will raise an error.
+Because of the above issues attempting to re-enable transaction migrations forfeits many of the safety guarantees this library provides and may even break certain functionally. If you'd like to experiment with it anyway you can re-enable transactional migrations by adding `self.disable_ddl_transaction = false` to your migration class definition.
 
-The API is designed to be explicit yet remain flexible. There may be situations where invoking the `unsafe_*` method is preferred (or the only option available for definitionally unsafe operations).
-
-While `unsafe_*` methods were historically (through 1.0) pure wrappers for invoking the native ActiveRecord migration method, there is a class of problems that we can't handle easily without breaking that design rule a bit. For example, dropping a column is unsafe from an application perspective, so we make the application safety concerns explicit by using an `unsafe_` prefix. Using `unsafe_remove_column` calls out the need to audit the application to confirm the migration won't break the application. Because there are no safe alternatives we don't define a `safe_remove_column` analogue. However there are still conditions we'd like to assert before dropping a column. For example, dropping an unused column that's used in one or more indexes may be safe from an application perspective, but the cascading drop of the index won't use a `CONCURRENT` operation to drop the dependent indexes and is therefore unsafe from a database perspective.
-
-When `unsafe_*` migration methods support checks of this type you can bypass the checks by passing an `:allow_dependent_objects` key in the method's `options` hash containing an array of dependent object types you'd like to allow. Until 2.0 none of these checks will run by default, but you can opt-in by setting `config.check_for_dependent_objects = true` [in your configuration initializer](#configuration).
-
-Similarly we believe the `force: true` option to ActiveRecord's `create_table` method is always unsafe, and therefore we disallow it even when calling `unsafe_create_table`. This option won't be enabled by default until 2.0, but you can opt-in by setting `config.allow_force_create_table = false` [in your configuration initializer](#configuration).
+## Usage
 
-[Running multiple DDL statements inside a transaction acquires exclusive locks on all of the modified objects](https://medium.com/paypal-tech/postgresql-at-scale-database-schema-changes-without-downtime-20d3749ed680#cc22). For that reason, this gem [disables DDL transactions](./lib/pg_ha_migrations/hacks/disable_ddl_transaction.rb) by default. You can change this by resetting `ActiveRecord::Migration.disable_ddl_transaction` in your application.
+### Unsupported ActiveRecord Features
 
 The following functionality is currently unsupported:
 
-- Rollbacks
+- [Rollback methods in migrations](#rollback)
 - Generators
 - schema.rb
 
-Compatibility notes:
+### Compatibility Notes
 
-- While some features may work with other versions, this gem is currently tested against PostgreSQL 11+ and Partman 4.x
-- There is a [bug](https://github.com/rails/rails/pull/41490) in early versions of Rails 6.1 when using `algorithm: :concurrently`. To add / remove indexes concurrently, please upgrade to at least Rails 6.1.4.
+- While some features may work with other versions, this gem is currently tested against PostgreSQL 13+ and Partman 4.x
+
+### Migration Methods
 
 #### safe\_create\_table
 
@@ -153,7 +178,7 @@ safe_change_column_default :table, :column, -> { "NOW()" }
 safe_change_column_default :table, :column, -> { "'NOW()'" }
 ```
 
-Note: On Postgres 11+ adding a column with a constant default value does not rewrite or scan the table (under a lock or otherwise). In that case a migration adding a column with a default should do so in a single operation rather than the two-step `safe_add_column` followed by `safe_change_column_default`. We enforce this best practice with the error `PgHaMigrations::BestPracticeError`, but if your prefer otherwise (or are running in a mixed Postgres version environment), you may opt out by setting `config.prefer_single_step_column_addition_with_default = true` [in your configuration initializer](#configuration).
+Note: On Postgres 11+ adding a column with a constant default value does not rewrite or scan the table (under a lock or otherwise). In that case a migration adding a column with a default should do so in a single operation rather than the two-step `safe_add_column` followed by `safe_change_column_default`. We enforce this best practice with the error `PgHaMigrations::BestPracticeError`, but if your prefer otherwise (or are running in a mixed Postgres version environment), you may opt out by setting `config.prefer_single_step_column_addition_with_default = false` [in your configuration initializer](#configuration).
 
 #### safe\_make\_column\_nullable
 
@@ -162,6 +187,19 @@ Safely make the column nullable.
 ```ruby
 safe_make_column_nullable :table, :column
 ```
+#### safe\_make\_column\_not\_nullable
+
+Safely make the column not nullable - adds a temporary constraint and uses that constraint to validate no values are null before altering the column, then removes the temporary constraint.
+
+```ruby
+safe_make_column_not_nullable :table, :column
+```
+
+> **Note:**
+> - This method performs a full table scan to validate that no NULL values exist in the column. While no exclusive lock is held for this scan, on large tables the scan may take a long time.
+> - The method runs multiple DDL statements non-transactionally. Validating the constraint can fail. In such cases an exception will be raised, and an INVALID constraint will be left on the table.
+
+If you want to avoid a full table scan and have already added and validated a suitable CHECK constraint, consider using [`safe_make_column_not_nullable_from_check_constraint`](#safe_make_column_not_nullable_from_check_constraint) instead.
 
 #### unsafe\_make\_column\_not\_nullable
 
@@ -171,6 +209,23 @@ Unsafely make a column not nullable.
 unsafe_make_column_not_nullable :table, :column
 ```
 
+#### safe\_make\_column\_not\_nullable\_from\_check\_constraint
+
+Variant of `safe_make_column_not_nullable` that safely makes a column NOT NULL using an existing validated CHECK constraint that enforces non-null values for the column. This method is expected to always be fast because it avoids a full table scan.
+
+```ruby
+safe_make_column_not_nullable_from_check_constraint :table, :column, constraint_name: :constraint_name
+```
+
+- `constraint_name` (required): The name of a validated CHECK constraint that enforces `column IS NOT NULL`.
+- `drop_constraint:` (optional, default: true): Whether to drop the constraint after making the column NOT NULL.
+
+You should use [`safe_make_column_not_nullable`](#safe_make_column_not_nullable) when neither a CHECK constraint or a NOT NULL constraint exists already. You should use this method when you already have an equivalent CHECK constraint on the table.
+
+This method will raise an error if the constraint does not exist, is not validated, or does not strictly enforce non-null values for the column.
+
+> **Note:**  We do not attempt to catch all possible proofs of `column IS NOT NULL` by means of an existing constraint; only a constraint with the exact definition `column IS NOT NULL` will be recognized.
+
 #### safe\_add\_index\_on\_empty\_table
 
 Safely add an index on a table with zero rows. This will raise an error if the table contains data.
@@ -368,23 +423,7 @@ safe_partman_create_parent :table,
   premake: 10,
   start_partition: Time.current + 1.month,
   infinite_time_partitions: false,
-  inherit_privileges: false
-```
-
-#### unsafe\_partman\_create\_parent
-
-We have chosen to flag the use of `retention` and `retention_keep_table` as an unsafe operation.
-While we recognize that these options are useful, we think they fit in the same category as `drop_table` and `rename_table`, and are therefore unsafe from an application perspective.
-If you wish to define these options, you must use this method.
-
-```ruby
-safe_create_partitioned_table :table, type: :range, partition_key: :created_at do |t|
-  t.timestamps null: false
-end
-
-unsafe_partman_create_parent :table,
-  partition_key: :created_at,
-  interval: "weekly",
+  inherit_privileges: false,
   retention: "60 days",
   retention_keep_table: false
 ```
@@ -392,7 +431,7 @@ unsafe_partman_create_parent :table,
 #### safe\_partman\_update\_config
 
 There are some partitioning options that cannot be set in the call to `create_parent` and are only available in the `part_config` table.
-As mentioned previously, you can specify these args in the call to `safe_partman_create_parent` or `unsafe_partman_create_parent` which will be delegated to this method.
+As mentioned previously, you can specify these args in the call to `safe_partman_create_parent` which will be delegated to this method.
 Calling this method directly will be useful if you need to modify your partitioned table after the fact.
 
 Allowed keyword args:
@@ -414,8 +453,9 @@ safe_partman_update_config :table,
 
 #### unsafe\_partman\_update\_config
 
-As with creating a partman parent table, we have chosen to flag the use of `retention` and `retention_keep_table` as an unsafe operation.
-If you wish to define these options, you must use this method.
+We have chosen to flag the use of `retention` and `retention_keep_table` as an unsafe operation.
+While we recognize that these options are useful, changing these values fits in the same category as `drop_table` and `rename_table`, and is therefore unsafe from an application perspective.
+If you wish to change these options, you must use this method.
 
 ```ruby
 unsafe_partman_update_config :table,
@@ -435,7 +475,13 @@ safe_partman_reapply_privileges :table
 
 #### safely\_acquire\_lock\_for\_table
 
-Safely acquire an access exclusive lock for a table.
+Acquires a lock (in `ACCESS EXCLUSIVE` mode by default) on a table using the following algorithm:
+
+1. Verify that no long-running queries are using the table.
+    - If long-running queries are currently using the table, sleep `PgHaMigrations::LOCK_TIMEOUT_SECONDS` and check again.
+2. If no long-running queries are currently using the table, optimistically attempt to lock the table (with a timeout of `PgHaMigrations::LOCK_TIMEOUT_SECONDS`).
+    - If the lock is not acquired, sleep `PgHaMigrations::LOCK_FAILURE_RETRY_DELAY_MULTLIPLIER * PgHaMigrations::LOCK_TIMEOUT_SECONDS`, and start again at step 1.
+3. If the lock is acquired, proceed to run the given block.
 
 ```ruby
 safely_acquire_lock_for_table(:table) do
@@ -443,7 +489,7 @@ safely_acquire_lock_for_table(:table) do
 end
 ```
 
-Safely acquire a lock for a table in a different mode.
+Safely acquire a lock on a table in `SHARE` mode.
 
 ```ruby
 safely_acquire_lock_for_table(:table, mode: :share) do
@@ -451,10 +497,18 @@ safely_acquire_lock_for_table(:table, mode: :share) do
 end
 ```
 
+Safely acquire a lock on multiple tables in `EXCLUSIVE` mode.
+
+```ruby
+safely_acquire_lock_for_table(:table_a, :table_b, mode: :exclusive) do
+  ...
+end
+```
+
 Note:
 
-We enforce that only one table (or a table and its partitions) can be locked at a time.
-Attempting to acquire a nested lock on a different table will result in an error.
+We enforce that only one set of tables can be locked at a time.
+Attempting to acquire a nested lock on a different set of tables will result in an error.
 
 #### adjust\_lock\_timeout
 
@@ -513,9 +567,9 @@ end
 #### Available options
 
 - `disable_default_migration_methods`: If true, the default implementations of DDL changes in `ActiveRecord::Migration` and the PostgreSQL adapter will be overridden by implementations that raise a `PgHaMigrations::UnsafeMigrationError`. Default: `true`
-- `check_for_dependent_objects`: If true, some `unsafe_*` migration methods will raise a `PgHaMigrations::UnsafeMigrationError` if any dependent objects exist. Default: `false`
-- `prefer_single_step_column_addition_with_default`: If true, raise an error when adding a column and separately setting a constant default value for that column in the same migration. Default: `false`
-- `allow_force_create_table`: If false, the `force: true` option to ActiveRecord's `create_table` method is disallowed. Default: `true`
+- `check_for_dependent_objects`: If true, some `unsafe_*` migration methods will raise a `PgHaMigrations::UnsafeMigrationError` if any dependent objects exist. Default: `true`
+- `prefer_single_step_column_addition_with_default`: If true, raise an error when adding a column and separately setting a constant default value for that column in the same migration. Default: `true`
+- `allow_force_create_table`: If false, the `force: true` option to ActiveRecord's `create_table` method is disallowed. Default: `false`
 - `infer_primary_key_on_partitioned_tables`: If true, the primary key for partitioned tables will be inferred on PostgreSQL 11+ databases (identifier column + partition key columns). Default: `true`
 
 ### Rake Tasks
@@ -542,6 +596,10 @@ Rake::Task["pg_ha_migrations:check_blocking_database_transactions"].enhance ["db
 
 After checking out the repo, run `bin/setup` to install dependencies and start a postgres docker container. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. This project uses Appraisal to test against multiple versions of ActiveRecord; you can run the tests against all supported version with `bundle exec appraisal rspec`.
 
+> **Warning**: If you rebuild the Docker container _without_ using `docker-compose build` (or the `--build` flag), it will not respect the `PGVERSION` environment variable that you've set if image layers from a different version exist. The Dockerfile uses a build-time argument that's only evaluated during the initial build. To change the Postgres version, you should explicitly provide the build argument: `docker-compose build --build-arg PGVERSION=15`. **Using `bin/setup` handles this for you.**
+
+> **Warning**: The Postgres Dockerfile automatically creates an anonymous volume for the data directory. When changing the specified `PGVERSION` environment variable this volume must be reset using `--renew-anon-volumes` or booting Postgres will fail.  **Using `bin/setup` handles this for you.**
+
 Running tests will automatically create a test database in the locally running Postgres server. You can find the connection parameters in `spec/spec_helper.rb`, but setting the environment variables `PGHOST`, `PGPORT`, `PGUSER`, and `PGPASSWORD` will override the defaults.
 
 To install this gem onto your local machine, run `bundle exec rake install`.

data/Rakefile

@@ -1,6 +1,8 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "appraisal"
+# In Rails 6 this isn't required in the right order and worked by accident; fixed in rails@0f5e7a66143
+require "logger"
 require_relative File.join("lib", "pg_ha_migrations")
 
 RSpec::Core::RakeTask.new(:spec)

data/bin/setup

@@ -9,4 +9,6 @@ bundle exec appraisal install
 # Do any other automated setup that you need to do here
 
 # Launch a blank postgres image with partman for testing
-docker-compose up -d --build
+# Because the Postgres image volumizes by default, we have to reset the volumes
+# or launching the setup with different PGVERSION env vars will fail.
+docker compose up -d --build --renew-anon-volumes

data/gemfiles/rails_7.1.gemfile

@@ -2,6 +2,6 @@
 
 source "https://rubygems.org"
 
-gem "rails", "7.1.0"
+gem "rails", "~> 7.1.0"
 
 gemspec path: "../"

data/gemfiles/{rails_6.1.gemfile → rails_7.2.gemfile}

@@ -2,6 +2,6 @@
 
 source "https://rubygems.org"
 
-gem "rails", "6.1.7.6"
+gem "rails", "~> 7.2.0"
 
 gemspec path: "../"

data/gemfiles/{rails_7.0.gemfile → rails_8.0.gemfile}

@@ -2,6 +2,6 @@
 
 source "https://rubygems.org"
 
-gem "rails", "7.0.8"
+gem "rails", "~> 8.0.0"
 
 gemspec path: "../"

data/lib/pg_ha_migrations/allowed_versions.rb

@@ -1,7 +1,7 @@
 require "active_record/migration/compatibility"
 
 module PgHaMigrations::AllowedVersions
-  ALLOWED_VERSIONS = [4.2, 5.0, 5.1, 5.2, 6.0, 6.1, 7.0, 7.1].map do |v|
+  ALLOWED_VERSIONS = [4.2, 5.0, 5.1, 5.2, 6.0, 6.1, 7.0, 7.1, 7.2, 8.0].map do |v|
     begin
       ActiveRecord::Migration[v]
     rescue ArgumentError

data/lib/pg_ha_migrations/constraint.rb

@@ -0,0 +1 @@
+PgHaMigrations::CheckConstraint = Struct.new(:name, :definition, :validated)

data/lib/pg_ha_migrations/lock_mode.rb

@@ -93,6 +93,18 @@ module PgHaMigrations
       MODE_CONFLICTS.keys.index(mode) <=> MODE_CONFLICTS.keys.index(other.mode)
     end
 
+    def eql?(other)
+      other.is_a?(LockMode) && mode == other.mode
+    end
+
+    def ==(other)
+      eql?(other)
+    end
+
+    def hash
+      mode.hash
+    end
+
     def conflicts_with?(other)
       MODE_CONFLICTS[mode].include?(other.mode)
     end

data/lib/pg_ha_migrations/relation.rb

@@ -1,4 +1,8 @@
 module PgHaMigrations
+  # This object represents a pointer to an actual relation in Postgres.
+  # The mode attribute is optional metadata which can represent a lock
+  # that has already been acquired or a potential lock that we are
+  # looking to acquire.
   Relation = Struct.new(:name, :schema, :mode) do
     def self.connection
       ActiveRecord::Base.connection
@@ -13,12 +17,6 @@ module PgHaMigrations
       self.mode = LockMode.new(mode) if mode.present?
     end
 
-    def conflicts_with?(other)
-      self == other && (
-        mode.nil? || other.mode.nil? || mode.conflicts_with?(other.mode)
-      )
-    end
-
     def fully_qualified_name
       @fully_qualified_name ||= [
         PG::Connection.quote_ident(schema),
@@ -30,8 +28,26 @@ module PgHaMigrations
       name.present? && schema.present?
     end
 
+    def conflicts_with?(other)
+      eql?(other) && (
+        mode.nil? || other.mode.nil? || mode.conflicts_with?(other.mode)
+      )
+    end
+
+    # Some code paths need to compare lock modes, while others just need
+    # to determine if the relation is the same object in Postgres, so
+    # equality here is simply looking at the relation name / schema.
+    # To also compare lock modes, #conflicts_with? is used.
+    def eql?(other)
+      other.is_a?(Relation) && hash == other.hash
+    end
+
     def ==(other)
-      other.is_a?(Relation) && name == other.name && schema == other.schema
+      eql?(other)
+    end
+
+    def hash
+      [name, schema].hash
     end
   end
 
@@ -97,6 +113,18 @@ module PgHaMigrations
       tables
     end
 
+    def check_constraints
+      connection.structs_from_sql(PgHaMigrations::CheckConstraint, <<~SQL)
+        SELECT conname AS name, pg_get_constraintdef(pg_constraint.oid) AS definition, convalidated AS validated
+        FROM pg_constraint, pg_class, pg_namespace
+        WHERE pg_class.oid = pg_constraint.conrelid
+          AND pg_class.relnamespace = pg_namespace.oid
+          AND pg_class.relname = #{connection.quote(name)}
+          AND pg_namespace.nspname = #{connection.quote(schema)}
+          AND pg_constraint.contype = 'c' -- 'c' stands for check constraints
+      SQL
+    end
+
     def has_rows?
       connection.select_value("SELECT EXISTS (SELECT 1 FROM #{fully_qualified_name} LIMIT 1)")
     end
@@ -152,4 +180,45 @@ module PgHaMigrations
       SQL
     end
   end
+
+  class TableCollection
+    include Enumerable
+
+    attr_reader :raw_set
+
+    delegate :each, to: :raw_set
+    delegate :mode, to: :first
+
+    def self.from_table_names(tables, mode=nil)
+      new(tables) { |table| Table.from_table_name(table, mode) }
+    end
+
+    def initialize(tables, &blk)
+      @raw_set = tables.map(&blk).to_set
+
+      if raw_set.empty?
+        raise ArgumentError, "Expected a non-empty list of tables"
+      end
+
+      if raw_set.uniq(&:mode).size > 1
+        raise ArgumentError, "Expected all tables in collection to have the same lock mode"
+      end
+    end
+
+    def subset?(other)
+      raw_set.subset?(other.raw_set)
+    end
+
+    def to_sql
+      map(&:fully_qualified_name).join(", ")
+    end
+
+    def with_partitions
+      tables = flat_map do |table|
+        table.partitions(include_sub_partitions: true, include_self: true)
+      end
+
+      self.class.new(tables)
+    end
+  end
 end