pg_ha_migrations 1.2.3 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae8983eec2507ce164936c65c32a7c296d0d3ef338ada2d90d68f37c572d00f7
-  data.tar.gz: 9c07cb77837a23a603e713e94cdae71f26acce82dbc2332d6fd77260c54d7c8c
+  metadata.gz: 05dbece254aee14a92945662e8af6ef7a0a94a871b55f21f527c8b277c9ec543
+  data.tar.gz: b744971a9a2616b41c78dacd4f6d912a97ca4e3b0799b87fbcc9823d7da11213
 SHA512:
-  metadata.gz: 247dd7ac257a208ef985d86b94710fbf41c0e622d02ce1acecb46d490ab17adb6aa080060d6e48ddf56e8ef4a5289121dcf4edd41e83f3bb7418ce20cfc91d4c
-  data.tar.gz: 0f0fb4ac98e6732d7d020a55e0f2608e256dbf34b4fe669ccfcde7e1878df43b3ccd8e153af61e6681d5eec62b8269ea435303376136207af54341d8bb19da41
+  metadata.gz: 7a6ed6c77b7106354a2f9a78545aae555145f9aac8d851e61be20d54bdaa283858646fe4f03172bb39836919aa942e8caa3854a48146caffeebf0c9bcfe48e03
+  data.tar.gz: b502c70bdc1eebda9e152bea35f1e8d000daa55b592d043eb5ae3f0bde347c459f60c83d31c6f000f741ff4d5b953ed8e3bcd70b0e4488288a3cc9b7657a9246

data/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    strategy:
+      matrix:
+        pg:
+          - 9.6
+          - 10
+          - 11
+          - 12
+        gemfile:
+          - rails_5.0
+          - rails_5.1
+          - rails_5.2
+          - rails_6.0
+          - rails_6.1
+    name: PostgreSQL ${{ matrix.pg }}
+    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
+      ImageOS: ubuntu20
+    services:
+      postgresql:
+        image: postgres:${{ matrix.pg }}
+        env:
+          POSTGRES_PASSWORD: postgres
+        # Set health checks to wait until postgres has started
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    steps:
+      - uses: actions/checkout@v2
+      - name: Setup Ruby using .ruby-version file
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+      - run: bundle exec rake spec

data/.ruby-version

@@ -1 +1 @@
-ruby-2.5.7
+ruby-2.7

data/Appraisals

@@ -14,3 +14,7 @@ appraise "rails-6.0" do
   gem "rails", "6.0.0"
 end
 
+appraise "rails-6.1" do
+  gem "rails", "6.1.0"
+end
+

data/README.md

@@ -55,7 +55,7 @@ There are two major classes of concerns we try to handle in the API:
 
 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.
+- `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.
@@ -106,6 +106,18 @@ Safely add a new enum value.
 safe_add_enum_value :enum, "value"
 ```
 
+#### unsafe\_rename\_enum\_value
+
+Unsafely change the value of an enum type entry.
+
+```ruby
+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.
+
 #### safe\_add\_column
 
 Safely add a column.
@@ -136,6 +148,8 @@ 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).
+
 #### safe\_make\_column\_nullable
 
 Safely make the column nullable.
@@ -260,6 +274,8 @@ end
 
 - `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`
 
 ### Rake Tasks
 
@@ -283,11 +299,15 @@ Rake::Task["pg_ha_migrations:check_blocking_database_transactions"].enhance ["db
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies and start a postgres docker container. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+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`.
 
 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`, 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).
+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`, 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`.
 
 ## Contributing
 

data/bin/setup

@@ -2,10 +2,14 @@
 set -euo pipefail
 IFS=$'\n\t'
 set -vx
+export PGPASSWORD="${PGPASSWORD:-postgres}"
+PGVERSION="${PGVERSION:-13}"
+
 
 bundle install
+bundle exec appraisal install
 
 # Do any other automated setup that you need to do here
 
 # Launch a blank postgres image for testing
-docker run -d -p 127.0.0.1:5432:5432 postgres:10
+docker run -d -p 127.0.0.1:5432:5432 -e POSTGRES_PASSWORD="${PGPASSWORD}" postgres:${PGVERSION}

data/gemfiles/rails_6.1.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "6.1.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].map do |v|
+  ALLOWED_VERSIONS = [4.2, 5.0, 5.1, 5.2, 6.0, 6.1].map do |v|
     begin
       ActiveRecord::Migration[v]
     rescue ArgumentError

data/lib/pg_ha_migrations/blocking_database_transactions.rb

@@ -49,10 +49,6 @@ module PgHaMigrations
           LEFT JOIN pg_class c ON ( -- Database wide
             l.locktype = 'relation'
             AND l.relation = c.oid
-            -- Be explicit about this being for a single database -- it's already implicit in
-            -- the relations used, and if we don't restrict this we could get incorrect results
-            -- with oid collisions from pg_namespace and pg_class.
-            AND l.database = (SELECT d.oid FROM pg_database d WHERE d.datname = current_database())
           )
           LEFT JOIN pg_namespace ns ON (c.relnamespace = ns.oid) -- Database wide
         WHERE psa.#{pid_column} != pg_backend_pid()
@@ -65,6 +61,10 @@ module PgHaMigrations
           )
           AND psa.xact_start < clock_timestamp() - ?::interval
           AND psa.#{query_column} !~ ?
+          -- Be explicit about this being for a single database -- it's already implicit in
+          -- the relations used, and if we don't restrict this we could get incorrect results
+          -- with oid collisions from pg_namespace and pg_class.
+          AND psa.datname = current_database()
           #{postgres_version >= 10_00_00 ? "AND #{ignore_sqlsender_sql}" : ""}
         GROUP BY psa.datname, psa.#{query_column}, psa.state, psa.xact_start
       SQL

data/lib/pg_ha_migrations/safe_statements.rb

@@ -1,4 +1,8 @@
 module PgHaMigrations::SafeStatements
+  def safe_added_columns_without_default_value
+    @safe_added_columns_without_default_value ||= []
+  end
+
   def safe_create_table(table, options={}, &block)
     if options[:force]
       raise PgHaMigrations::UnsafeMigrationError.new(":force is NOT SAFE! Explicitly call unsafe_drop_table first if you want to recreate an existing table")
@@ -25,14 +29,37 @@ module PgHaMigrations::SafeStatements
     unsafe_execute("ALTER TYPE #{PG::Connection.quote_ident(name.to_s)} ADD VALUE '#{PG::Connection.escape_string(value)}'")
   end
 
-  def safe_add_column(table, column, type, options = {})
-    if options.has_key? :default
-      raise PgHaMigrations::UnsafeMigrationError.new(":default is NOT SAFE! Use safe_change_column_default afterwards then backfill the data to prevent locking the table")
+  def unsafe_rename_enum_value(name, old_value, new_value)
+    if ActiveRecord::Base.connection.postgresql_version < 10_00_00
+      raise PgHaMigrations::InvalidMigrationError, "Renaming an enum value is not supported on Postgres databases before version 10"
     end
-    if options[:null] == false
+
+    unsafe_execute("ALTER TYPE #{PG::Connection.quote_ident(name.to_s)} RENAME VALUE '#{PG::Connection.escape_string(old_value)}' TO '#{PG::Connection.escape_string(new_value)}'")
+  end
+
+  def safe_add_column(table, column, type, options = {})
+    # Note: we don't believe we need to consider the odd case where
+    # `:default => nil` or `:default => -> { null }` (or similar) is
+    # passed because:
+    # - It's OK to exclude that case with an "unnecessary" `raise`
+    #   below as it doesn't make semantic sense anyway.
+    # - If `:null => false` is also passed we are assuming Postgres's
+    #   seq scan of the table (to verify the NOT NULL constraint) will
+    #   short-circuit (though we have not confirmed that).
+    if options.has_key?(:default)
+      if ActiveRecord::Base.connection.postgresql_version < 11_00_00
+        raise PgHaMigrations::UnsafeMigrationError.new(":default is NOT SAFE! Use safe_change_column_default afterwards then backfill the data to prevent locking the table")
+      elsif options[:default].is_a?(Proc) || (options[:default].is_a?(String) && !([:string, :text, :binary].include?(type.to_sym) || _type_is_enum(type)))
+        raise PgHaMigrations::UnsafeMigrationError.new(":default is not safe if the default value is volatile. Use safe_change_column_default afterwards then backfill the data to prevent locking the table")
+      end
+    elsif options[:null] == false
       raise PgHaMigrations::UnsafeMigrationError.new(":null => false is NOT SAFE if the table has data! If you _really_ want to do this, use unsafe_make_column_not_nullable")
     end
 
+    unless options.has_key?(:default)
+      self.safe_added_columns_without_default_value << [table.to_s, column.to_s]
+    end
+
     unsafe_add_column(table, column, type, options)
   end
 
@@ -43,6 +70,12 @@ module PgHaMigrations::SafeStatements
   end
 
   def safe_change_column_default(table_name, column_name, default_value)
+    if PgHaMigrations.config.prefer_single_step_column_addition_with_default &&
+        ActiveRecord::Base.connection.postgresql_version >= 11_00_00 &&
+        self.safe_added_columns_without_default_value.include?([table_name.to_s, column_name.to_s])
+      raise PgHaMigrations::BestPracticeError, "On Postgres 11+ it's safe to set a constant default value when adding a new column; please set the default value as part of the column addition"
+    end
+
     column = connection.send(:column_for, table_name, column_name)
 
     # In 5.2 we have an edge whereby passing in a string literal with an expression
@@ -201,6 +234,10 @@ module PgHaMigrations::SafeStatements
     raise PgHaMigrations::UnsupportedAdapter, "This gem only works with the #{expected_adapter} adapter, found #{actual_adapter} instead" unless actual_adapter == expected_adapter
   end
 
+  def _type_is_enum(type)
+    ActiveRecord::Base.connection.select_values("SELECT typname FROM pg_type JOIN pg_enum ON pg_type.oid = pg_enum.enumtypid").include?(type.to_s)
+  end
+
   def migrate(direction)
     if respond_to?(:change)
       raise PgHaMigrations::UnsupportedMigrationError, "Tracking changes for automated rollback is not supported; use explicit #up instead."

data/lib/pg_ha_migrations/unsafe_statements.rb

@@ -39,7 +39,6 @@ module PgHaMigrations::UnsafeStatements
   delegate_unsafe_method_to_migration_base_class :change_column
   delegate_unsafe_method_to_migration_base_class :change_column_default
   delegate_unsafe_method_to_migration_base_class :remove_column
-  delegate_unsafe_method_to_migration_base_class :add_index
   delegate_unsafe_method_to_migration_base_class :execute
   delegate_unsafe_method_to_migration_base_class :remove_index
   delegate_unsafe_method_to_migration_base_class :add_foreign_key
@@ -69,6 +68,16 @@ module PgHaMigrations::UnsafeStatements
     execute_ancestor_statement(:create_table, table, options, &block)
   end
 
+  def unsafe_add_index(table, column_names, options = {})
+    if ((ActiveRecord::VERSION::MAJOR == 5 && ActiveRecord::VERSION::MINOR >= 2) || ActiveRecord::VERSION::MAJOR > 5) &&
+        column_names.is_a?(String) && /\W/.match?(column_names) && options.key?(:opclass)
+      raise PgHaMigrations::InvalidMigrationError, "ActiveRecord drops the :opclass option when supplying a string containing an expression or list of columns; instead either supply an array of columns or include the opclass in the string for each column"
+    end
+
+    execute_ancestor_statement(:add_index, table, column_names, options)
+  end
+
+
   def execute_ancestor_statement(method_name, *args, &block)
     # Dispatching here is a bit complicated: we need to execute the method
     # belonging to the first member of the inheritance chain (besides

data/lib/pg_ha_migrations/version.rb

@@ -1,3 +1,3 @@
 module PgHaMigrations
-  VERSION = "1.2.3"
+  VERSION = "1.4.0"
 end

data/lib/pg_ha_migrations.rb

@@ -8,14 +8,16 @@ module PgHaMigrations
   Config = Struct.new(
     :disable_default_migration_methods,
     :check_for_dependent_objects,
-    :allow_force_create_table
+    :allow_force_create_table,
+    :prefer_single_step_column_addition_with_default
   )
 
   def self.config
     @config ||= Config.new(
       true,
       false,
-      true
+      true,
+      false
     )
   end
 
@@ -29,18 +31,24 @@ module PgHaMigrations
   # Safe versus unsafe in this context specifically means the following:
   # - Safe operations will not block for long periods of time.
   # - Unsafe operations _may_ block for long periods of time.
-  UnsafeMigrationError = Class.new(Exception)
+  UnsafeMigrationError = Class.new(StandardError)
 
   # Invalid migrations are operations which we expect to not function
   # as expected or get the schema into an inconsistent state
-  InvalidMigrationError = Class.new(Exception)
+  InvalidMigrationError = Class.new(StandardError)
+
+  # Operations violating a best practice, but not actually unsafe will
+  # raise this error. For example, adding a column without a default and
+  # then setting its default in a second action in a single migration
+  # isn't our documented best practice and will raise this error.
+  BestPracticeError = Class.new(Exception)
 
   # Unsupported migrations use ActiveRecord::Migration features that
   # we don't support, and therefore will likely have unexpected behavior.
-  UnsupportedMigrationError = Class.new(Exception)
+  UnsupportedMigrationError = Class.new(StandardError)
 
   # This gem only supports the PostgreSQL adapter at this time.
-  UnsupportedAdapter = Class.new(Exception)
+  UnsupportedAdapter = Class.new(StandardError)
 end
 
 require "pg_ha_migrations/blocking_database_transactions"

data/pg_ha_migrations.gemspec

@@ -32,11 +32,11 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "pg"
-  spec.add_development_dependency "db-query-matchers", "~> 0.9.0"
+  spec.add_development_dependency "db-query-matchers", "~> 0.10.0"
   spec.add_development_dependency "pry"
   spec.add_development_dependency "pry-byebug"
   spec.add_development_dependency "appraisal", "~> 2.2.0"
 
-  spec.add_dependency "rails", ">= 5.0", "< 6.1"
+  spec.add_dependency "rails", ">= 5.0", "< 6.2"
   spec.add_dependency "relation_to_struct", ">= 1.5.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pg_ha_migrations
 version: !ruby/object:Gem::Version
-  version: 1.2.3
+  version: 1.4.0
 platform: ruby
 authors:
 - celeen
@@ -14,7 +14,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-03-12 00:00:00.000000000 Z
+date: 2022-01-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -64,14 +64,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: 0.10.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: 0.10.0
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -123,7 +123,7 @@ dependencies:
         version: '5.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '6.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -133,7 +133,7 @@ dependencies:
         version: '5.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '6.2'
 - !ruby/object:Gem::Dependency
   name: relation_to_struct
   requirement: !ruby/object:Gem::Requirement
@@ -156,11 +156,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ci.yml"
 - ".gitignore"
 - ".pryrc"
 - ".rspec"
 - ".ruby-version"
-- ".travis.yml"
 - Appraisals
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -174,6 +174,7 @@ files:
 - gemfiles/rails_5.1.gemfile
 - gemfiles/rails_5.2.gemfile
 - gemfiles/rails_6.0.gemfile
+- gemfiles/rails_6.1.gemfile
 - lib/pg_ha_migrations.rb
 - lib/pg_ha_migrations/allowed_versions.rb
 - lib/pg_ha_migrations/blocking_database_transactions.rb
@@ -206,7 +207,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.8
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: Enforces DDL/migration safety in Ruby on Rails project with an emphasis on

data/.travis.yml

@@ -1,28 +0,0 @@
-sudo: false
-language: ruby
-rvm:
-  - 2.5
-global:
-  env:
-    PGPORT: 5433
-env:
-  - PGVERSION: "9.6"
-  - PGVERSION: "10"
-  - PGVERSION: "11"
-  - PGVERSION: "12"
-services:
-  - postgresql
-before_install:
-  - sudo service postgresql stop
-  - sudo apt-get update
-  - sudo apt-get -y install postgresql-$PGVERSION postgresql-client-$PGVERSION postgresql-server-dev-$PGVERSION postgresql-client-common postgresql-common
-  - if [ $PGVERSION != '9.6' ]; then sudo cp /etc/postgresql/{9.6,$PGVERSION}/main/pg_hba.conf; fi
-  - sudo service postgresql restart $PGVERSION
-  - gem uninstall -v '>= 2' -i $(rvm gemdir)@global -ax bundler || true
-  - gem install bundler -v 1.15.4
-gemfile:
-  - gemfiles/rails_5.0.gemfile
-  - gemfiles/rails_5.1.gemfile
-  - gemfiles/rails_5.2.gemfile
-  - gemfiles/rails_6.0.gemfile
-script: "bundle exec rake spec"