pg_ha_migrations 1.8.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6858f02b9a874bbaf79865c789a490c9aa1140240537d0eded8f48486c6348f3
-  data.tar.gz: 733394b7f83821f71821816777765d982d1580761522e0751534d3e3c62f598b
+  metadata.gz: 7b2e6bb12c48cffbc58e2f182f6d147f9952fd5167b82feaebee77190d0c71f0
+  data.tar.gz: f438b6095e6493bae0545cca0f9b3b3e5aa6d2dfc14d80a8c851e80f5b90e09d
 SHA512:
-  metadata.gz: 55f3f8e3730fc11183e71cbf6ba9d32dabf1c8b0ec532da6861b47d045cffb348184350831f564999ecee22b601931ab577ca20f8c4e831e0d4b776babe21a58
-  data.tar.gz: e260ebe93cafba7f3119c41bd2594a797293713f95d072378dbc5733f176d86ce8a93c8a24b53b6fbb9ec77756f4db9ab5fdb92f6080de6ac0fb56e158e5b5d3
+  metadata.gz: 85b57ebf531422f9b14ff7d3e91a0759b9e4c714dd8b53dff2e5e45e0b44fe583ab726ad9a160f5d34de0bab102da0770caae5dad622e5294d4d8eba1b178a52
+  data.tar.gz: 2992367de5df4a1b57bcd024c39edebf40ecd5cc595a2b2b8034cd89af60d9bb068a4029e8771f66abf0fc7c0a73966d7c06bb0959c678df264e874276b5e73b

data/.github/workflows/ci.yml

@@ -5,21 +5,28 @@ jobs:
     strategy:
       matrix:
         pg:
-          - 11
-          - 12
           - 13
           - 14
           - 15
           - 16
+          - 17
         ruby:
-          - "3.0"
-          - "3.1"
           - "3.2"
+          - "3.3"
+          - "3.4"
         gemfile:
-          - rails_6.1
-          - rails_7.0
           - rails_7.1
-    name: PostgreSQL ${{ matrix.pg }} - Ruby ${{ matrix.ruby }} - ${{ matrix.gemfile }}
+          - rails_7.2
+          - rails_8.0
+        partman:
+          - 4
+          - 5
+        exclude:
+          - pg: 17
+            partman: 4 # Partman 4.x is not available in PGDG for PG 17
+          - pg: 13
+            partman: 5 # Partman 5.x is not available in PGDG for PG 13
+    name: PostgreSQL ${{ matrix.pg }} - Partman ${{ matrix.partman }} - 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
       BUNDLE_GEMFILE: gemfiles/${{ matrix.gemfile }}.gemfile
@@ -27,9 +34,10 @@ 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 }}
+          PARTMAN_VERSION: ${{ matrix.partman }}
       - name: Setup Ruby using .ruby-version file
         uses: ruby/setup-ruby@v1
         with:

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/Dockerfile

@@ -1,6 +1,7 @@
 ARG PGVERSION
+ARG PARTMAN_VERSION
 
-FROM postgres:$PGVERSION-bullseye
+FROM postgres:$PGVERSION-bookworm AS base
 
 RUN apt-get update && apt-get install -y curl ca-certificates gnupg lsb-release
 
@@ -8,4 +9,11 @@ RUN curl https://www.postgresql.org/media/keys/ACCC4CF8.asc | gpg --dearmor | te
 
 RUN echo "deb https://apt-archive.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg-archive main" > /etc/apt/sources.list.d/pgdg.list
 
-RUN apt update && apt-get install -y postgresql-$PG_MAJOR-partman=4.7.4-2.pgdg110+1
+FROM base AS partman-4-branch
+ENV PARTMAN_VERSION=4.7.4-2.pgdg120+1
+
+FROM base AS partman-5-branch
+ENV PARTMAN_VERSION=5.2.4-1.pgdg120+1
+
+FROM partman-$PARTMAN_VERSION-branch AS final
+RUN apt update && apt-get install -y postgresql-$PG_MAJOR-partman=$PARTMAN_VERSION

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 rename migration methods with prefixes denoting 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_*`: These methods are generally a direct dispatch to the native ActiveRecord migration method.
+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:
 
-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).
+* [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).
 
-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.
+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.
 
-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
 
@@ -119,9 +144,7 @@ Unsafely change the value of an enum type entry.
 unsafe_rename_enum_value(:enum, "old_value", "new_value")
 ```
 
-Note:
-
-Changing an enum value does not issue any long-running scans or acquire locks on usages of the enum type. Therefore multiple queries within a transaction concurrent with the change may see both the old and new values. To highlight these potential pitfalls no `safe_rename_enum_value` equivalent exists. Before modifying an enum type entry you should verify that no concurrently executing queries will attempt to write the old value and that read queries understand the new value.
+> **Note:** Changing an enum value does not issue any long-running scans or acquire locks on usages of the enum type. Therefore multiple queries within a transaction concurrent with the change may see both the old and new values. To highlight these potential pitfalls no `safe_rename_enum_value` equivalent exists. Before modifying an enum type entry you should verify that no concurrently executing queries will attempt to write the old value and that read queries understand the new value.
 
 #### safe\_add\_column
 
@@ -153,7 +176,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 +185,19 @@ Safely make the column nullable.
 ```ruby
 safe_make_column_nullable :table, :column
 ```
+#### safe\_make\_column\_not\_nullable
+
+Safely make the column not nullable. This method uses a `CHECK column IS NOT NULL` constraint to validate no values are null before altering the column. If such a constraint exists already, it is re-used, if it does not, a temporary constraint is added. Whether or not the constraint already existed, the constraint will be validated, if necessary, and removed after the column is marked `NOT NULL`.
+
+```ruby
+safe_make_column_not_nullable :table, :column
+```
+
+> **Note:**
+> - This method may perform 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 INVALID constraint will be left on the table. Calling `safe_make_column_not_nullable` again is safe.
+
+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 +207,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.
@@ -230,11 +283,10 @@ Add a composite index using the `hash` index type with custom name for the paren
 safe_add_concurrent_partitioned_index :partitioned_table, [:column1, :column2], name: "custom_name_idx", using: :hash
 ```
 
-Note:
-
-This method runs multiple DDL statements non-transactionally.
-Creating or attaching an index on a child table could fail.
-In such cases an exception will be raised, and an `INVALID` index will be left on the parent table.
+> **Note:**
+> This method runs multiple DDL statements non-transactionally.
+> Creating or attaching an index on a child table could fail.
+> In such cases an exception will be raised, and an `INVALID` index will be left on the parent table.
 
 #### safe\_add\_unvalidated\_check\_constraint
 
@@ -328,7 +380,7 @@ The rest are keyword args with the following mappings:
 - `premake` -> `p_premake`. Required: `false`. Partman defaults to `4`.
 - `start_partition` -> `p_start_partition`. Required: `false`. Partman defaults to the current timestamp.
 
-Note that we have chosen to require PostgreSQL 11+ and hardcode `p_type` to `native` for simplicity, as previous PostgreSQL versions are end-of-life.
+> **Note:** We have chosen to require PostgreSQL 11+ and hardcode `p_type` to `native` (`range` in the case of Partman 5) for simplicity, as previous PostgreSQL versions are end-of-life.
 
 Additionally, this method allows you to configure a subset of attributes on the record stored in the [part\_config](https://github.com/pgpartman/pg_partman/blob/master/doc/pg_partman.md#tables) table.
 These options are delegated to the `unsafe_partman_update_config` method to update the record:
@@ -345,7 +397,7 @@ safe_create_partitioned_table :table, type: :range, partition_key: :created_at d
   t.timestamps null: false
 end
 
-safe_partman_create_parent :table, partition_key: :created_at, interval: "weekly"
+safe_partman_create_parent :table, partition_key: :created_at, interval: "1 week"
 ```
 
 With custom overrides:
@@ -363,28 +415,12 @@ end
 
 safe_partman_create_parent :table,
   partition_key: :created_at,
-  interval: "weekly",
+  interval: "1 week",
   template_table: :table_template,
   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 +428,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:
@@ -403,7 +439,7 @@ Allowed keyword args:
 - `retention`
 - `retention_keep_table`
 
-Note that we detect if the value of `inherit_privileges` is changing and will automatically call `safe_partman_reapply_privileges` to ensure permissions are propagated to existing child partitions.
+> **Note:** If `inherit_privileges` will change then `safe_partman_reapply_privileges` will be automatically called to ensure permissions are propagated to existing child partitions.
 
 ```ruby
 safe_partman_update_config :table,
@@ -414,8 +450,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,
@@ -431,11 +468,40 @@ If your partitioned table is configured with `inherit_privileges` set to `true`,
 safe_partman_reapply_privileges :table
 ```
 
+#### unsafe\_partman\_standardize\_partition\_naming
+
+This method provides functionality to standardize existing Partman 4 tables such that naming is consistent with Partman 5.
+The logic follows the guidelines in the [Partman upgrade docs](https://github.com/pgpartman/pg_partman/blob/v5.2.4/doc/pg_partman_5.0.1_upgrade.md).
+
+Technically, only `weekly` and `quarterly` partitioned tables _need_ to be standardized prior to the upgrade.
+_However_, Partman 5 changes the default [datetime_string](https://github.com/pgpartman/pg_partman/blob/v5.2.4/sql/functions/calculate_time_partition_info.sql#L13-L17) that is used for _all_ intervals (`YYYYMMDD` and `YYYYMMDD_HH24MISS`).
+Compare that to the Partman 4 logic for [datetime_string](https://github.com/pgpartman/pg_partman/blob/v4.7.4/sql/functions/create_parent.sql#L434-L459).
+So, this method supports standardization for _all_ Partman 4 intervals.
+
+> **Note:** This method is safe from a database perspective, but is only safe from an application perspective if child tables are not directly referenced (child tables are renamed during this operation)
+
+```ruby
+unsafe_partman_standardize_partition_naming :table
+```
+
+This method uses a default statement timeout of 1 second.
+If the target table has many partitions (hundreds of thousands), you may need to increase the statement timeout for the operation to succeed.
+
+```ruby
+unsafe_partman_standardize_partition_naming :table, statement_timeout: 2
+```
+
 ### Utilities
 
 #### 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 +509,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 +517,16 @@ safely_acquire_lock_for_table(:table, mode: :share) do
 end
 ```
 
-Note:
+Safely acquire a lock on multiple tables in `EXCLUSIVE` mode.
+
+```ruby
+safely_acquire_lock_for_table(:table_a, :table_b, mode: :exclusive) do
+  ...
+end
+```
 
-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.
+> **Note:** 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,10 +585,11 @@ 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`
+- `partman_5_compatibility_mode`: If true, `safe_partman_create_parent` will raise an error if the user provides an interval that is [not supported by Partman 5](https://github.com/pgpartman/pg_partman/blob/v5.2.4/sql/functions/create_parent.sql#L86-L96). If the interval is supported, the method will ensure table name suffixes match the Partman 5 format (`YYYYMMDD`, `YYYYMMDD_HTH24MISS`). Default: `false`
 
 ### Rake Tasks
 
@@ -542,13 +615,17 @@ 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`.
 
 To release a new version, update the version number in `version.rb`, commit the change, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-Note: if while releasing the gem you get the error ``Your rubygems.org credentials aren't set. Run `gem push` to set them.`` you can more simply run `gem signin`.
+> **Note:** If while releasing the gem you get the error ``Your rubygems.org credentials aren't set. Run `gem push` to set them.`` you can more simply run `gem signin`.
 
 ## Contributing
 

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/docker-compose.yml

@@ -4,7 +4,8 @@ services:
     build:
       context: .
       args:
-        - PGVERSION=${PGVERSION:-16}
+        - PGVERSION=${PGVERSION:-17}
+        - PARTMAN_VERSION=${PARTMAN_VERSION:-5}
     ports:
       - "5432:5432"
     environment:

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,8 @@
+PgHaMigrations::CheckConstraint = Struct.new(:name, :definition, :validated) do
+  def initialize(name, definition, validated)
+    # pg_get_constraintdef includes NOT VALID in the definition,
+    # but we return that as a separate attribute.
+    definition = definition&.gsub(/ NOT VALID\Z/, "")
+    super(name, definition, validated)
+  end
+end

data/lib/pg_ha_migrations/extension.rb

@@ -0,0 +1,35 @@
+module PgHaMigrations
+  class Extension
+    attr_reader :name, :schema, :version
+
+    def initialize(name)
+      @name = name
+
+      @schema, @version = ActiveRecord::Base.connection.select_rows(<<~SQL).first
+        SELECT nspname, extversion
+        FROM pg_namespace JOIN pg_extension
+          ON pg_namespace.oid = pg_extension.extnamespace
+        WHERE pg_extension.extname = #{ActiveRecord::Base.connection.quote(name)}
+        LIMIT 1
+      SQL
+    end
+
+    def quoted_schema
+      return unless schema
+
+      PG::Connection.quote_ident(schema)
+    end
+
+    def major_version
+      return unless version
+
+      Gem::Version.new(version)
+        .segments
+        .first
+    end
+
+    def installed?
+      !!schema && !!version
+    end
+  end
+end

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