[ruby on rails]部署时候产生ActiveRecord::PreparedStatementCacheExpired错误的原因及解决方法

一、问题：

• 有时在 Postgres 上部署 Rails 应用程序时，可能会看到 ActiveRecord::PreparedStatementCacheExpired 错误。仅当在部署中运行迁移时才会发生这种情况。
• 发生这种情况是因为 Rails 利用 Postgres 的缓存准备语句(PreparedStatementCache)功能来提高性能。这个功能在rails中默认是开启的。

二、问题复现：

• 我们可以用rspec来复现这个错误

 it 'not raise ActiveRecord::PreparedStatementCacheExpired' do
    create(:user)
    User.first
    User.find_by_sql('ALTER TABLE users ADD new_metric_column integer;')
    ActiveRecord::Base.transaction { User.first }
  end

三、产生的原理：

• rails查询语句如User.all被 active_record 解析成sql语句后，发送给数据库，先执行PREPARE预备语句，sql语句会被解析、分析、优化并且重写。当后续发出一个EXECUTE命令时，该预备语句会被规划并且执行。
• rails会把查询语句存到pg_prepared_statements中，以方便下次调用同类语句时候直接execute statements中的语句，而不用再进行解析、分析、优化，避免重复工作，提高效率。

User.first
User.all
# 执行上面的2个查询后，用connection.instance_variable_get(:@statements)就可以看到缓存的准备语句
ActiveRecord::Base.connection.instance_variable_get(:@statements)
==> <ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::StatementPool:0x00000001086b13c8 
@cache={78368=>{"\"$user\", public-SELECT \"users\".* FROM \"users\" ORDER BY \"users\".\"id\" ASC LIMIT 
$1"=>"a7", "\"$user\", public-SELECT \"users\".* FROM \"users\" /* loading for inspect */ LIMIT $1"=>"a8"}},
@statement_limit=1000, @connection=#, @counter=8>

# 这个也可以看到，会在数据库中去查询
ActiveRecord::Base.connection.execute('select * from pg_prepared_statements').values
(0.5ms) select * from pg_prepared_statements
==> [["a7", "SELECT \"users\".* FROM \"users\" ORDER BY \"users\".\"id\" ASC LIMIT $1", "2024-07-
11T07:03:06.891+00:00", "{bigint}", false], ["a8", "SELECT \"users\".* FROM \"users\" /* loading for inspect 
*/ LIMIT $1", "2024-07-11T07:04:47.772+00:00", "{bigint}", false]]

• 在 Postgres 中，如果表的模式(schema)更改影响返回结果，则预准备语句缓存将失效。具体说就是给表增加、删除字段，或者修改字段的类型、长度等ddl操作。

如下面的例子，添加或删除字段后执行SELECT时，pg数据库就会抛出cached plan must not change result type，rails中active_record获取到这个错误然后会抛出ActiveRecord::PreparedStatementCacheExpired

ALTER TABLE users ADD COLUMN new_column integer;
ALTER TABLE users DROP COLUMN old_column;
添加或删除列，然后执行 SELECT *
删除 old_column 列然后执行 SELECT users.old_column

• 部署服务中运行增、减、修改字段的迁移时，用户发出的查询语句会从预准备语句缓存中直接拿sql直接进行excute，但这时候因为表结构变化了，预准备语句缓存就失效了，pg数据库就会抛出cached plan must not change result type错误
• 查看active_record源码中的exec_cache方法，发现rails对pg的这个错误处理方式是：
  1. 事务transaction中，会直接抛出 raise ActiveRecord::PreparedStatementCacheExpired.new(e.cause.message)
  2. 事务外的会把缓存@statements中的这句删除并 try，重试后会重新解析、分析、优化sql语句并执行prepare_statement方法放入预准备语句缓存中

module ActiveRecord
  module ConnectionHandling
    def exec_cache(sql, name, binds)
      materialize_transactions
      mark_transaction_written_if_write(sql)
      update_typemap_for_default_timezone

      stmt_key = prepare_statement(sql, binds)
      type_casted_binds = type_casted_binds(binds)

      log(sql, name, binds, type_casted_binds, stmt_key) do
        ActiveSupport::Dependencies.interlock.permit_concurrent_loads do
          @connection.exec_prepared(stmt_key, type_casted_binds)
        end
      end
    rescue ActiveRecord::StatementInvalid => e
      raise unless is_cached_plan_failure?(e)

      # Nothing we can do if we are in a transaction because all commands
      # will raise InFailedSQLTransaction
      if in_transaction?
        raise ActiveRecord::PreparedStatementCacheExpired.new(e.cause.message)
      else
        @lock.synchronize do
          # outside of transactions we can simply flush this query and retry
          @statements.delete sql_key(sql)
        end
        retry
      end
    end
  end
end

• 所以出现在事务transaction中的这个错误，就会导致事务回滚，对业务来说就是请求失败了，需要我们自己来处理

四、解决方法：

1. 禁用缓存准备语句功能（不推荐）

rails6 以上可以把 database中 prepared_statements 设为 false来禁用这个功能

default: &default
  adapter: postgresql
  encoding: unicode
  prepared_statements: false

rails6以下没测试，如果上面的不行可以试试新建个初始化文件

# config/initializers/disable_prepared_statements.rb:
db_configuration = ActiveRecord::Base.configurations[Rails.env]
db_configuration.merge!('prepared_statements' => false)
ActiveRecord::Base.establish_connection(db_configuration)

验证：

User.all
ActiveRecord::Base.connection.execute('select * from pg_prepared_statements').values
==> []

结论：小型项目中其实禁用这个功能无所谓，性能几乎不影响，但是大型项目中，用户越多，越复杂的查询语句，这个功能带来的受益越大，所以可以根据实际情况来决定是否禁用

2. 使select * 变为 select id, name这样的具体字段， rails7中的官方解决方案就是这样的，但只能解决新增字段引起的报错

• rails7中 enumerate_columns_in_select_statements 设为 true

# config/application.rb
module MyApp
  class Application < Rails::Application
    config.active_record.enumerate_columns_in_select_statements = true
  end
end

• rails7以下没有这个配置，可以用 ignored_columns来实现

class ApplicationRecord < ActiveRecord::Base
  self.abstract_class = true
  #__fake_column__是自定义的，不要是某个表中的字段就行，如果是[:id],那么 User.all就会被解析为select name from users,没有id了
  self.ignored_columns = [:__fake_column__] 
end

结论：这个方案存在的问题是，增加字段可以完美解决，但是删除字段，还会出现报错，比如删除name字段后，预准备语句select id, name from users中的name不存在了，就会报错。 删除字段可以在 User.rb 中增加 self.ignored_columns = [:name], 然后先重启服务，再进行部署，部署时候最好把 self.ignored_columns = [:name] 删掉，避免以后再加回 name 字段后，select 不到，rails7 官方的方案也存在这个问题，所以这个方案感觉很麻烦

3. 重启rails应用

• 预准备语句缓存的生命周期只存在于一个数据库会话中，关闭数据库连接（重启应用会关闭原连接，重新建立新连接）那原来的预准备语句缓存就会清空，重启后的sql请求就会重新缓存预准备语句，就能正常拿到数据。

结论：重启应用会出现短暂服务502不可用，当然部署应用时候也是要重启服务的，也会出现502，所以最好是没人访问的时候（半夜？）进行部署，这样就会尽可能少的出现PreparedStatementCacheExpired报错

4. 重写 transaction 方法

class ApplicationRecord < ActiveRecord::Base
  class << self
    def transaction(*args, &block)
      retried ||= false
      super
    rescue ActiveRecord::PreparedStatementCacheExpired
      if retried
        raise
      else
        retried = true
        retry
      end
    end
  end
end

• 重写后代码里写事务的地方改为使用 ApplicationRecord.transaction do ... end 或者 MyModel.transaction或者obj.transaction, 只要不用ActiveRecord::Base.transaction就行

结论：重要提示：如果在事务中有发送电子邮件、post到 API 或执行其他与外界交互的操作，这可能会导致其中一些操作偶尔发生两次。这就是为什么 Rails官方不会自动执行重试，而是将其留给应用程序开发人员。

>>>>>>>我本人测试这个方法还是会继续报错

5. 重写 transaction 方法结合手动清除预准备语句缓存

• 既然只有在事务中产生的这个报错会影响业务，那就把事务方法重写一下，让先清除预准备语句缓存，然后执行事务代码，这样就不会报错了
• 使用了gem 'rails-settings-cached'，部署前先打开 Setting.clear_prepared_statements_cache，部署完毕后再关掉，这样性能也基本不会有任何影响

class ApplicationRecord < ActiveRecord::Base
  self.abstract_class = true

  class << self
    def transaction(*args, &block)
      connection.clear_cache! if Setting.clear_prepared_statements_cache
      super
    end
  end
end

五、最终答案

经过我们的测试，最终使用 方案5 完美解决这个问题，已使用到生产环境，可以把Setting.clear_prepared_statements_cache这个开关集成到部署脚本中就更方便了。