Rails多数据库迁移PostgreSQL跨库外键关联实现方法

PostgreSQL单实例下的不同数据库是逻辑完全隔离的，原生不支持跨库外键约束，默认迁移时Rails生成的外键语句会在当前库查找关联表，必然抛出PG::UndefinedTable错误。基于PostgreSQL内置的postgres_fdw外部数据包装器即可打通跨库访问，配合少量迁移逻辑调整就能实现和原生关联一致的使用体验，不需要修改Rails框架源码。

步骤1：配置PostgreSQL跨库访问通道 #

所有操作在数据库层执行，先打通次级库到主库的访问链路：

1. 登录次级数据库appusers_development，用超级用户权限启用FDW扩展：

   CREATE EXTENSION IF NOT EXISTS postgres_fdw;
   

2. 创建指向同实例主库app_development的外部服务连接：

   CREATE SERVER app_main_db
   FOREIGN DATA WRAPPER postgres_fdw
   OPTIONS (host '127.0.0.1', port '5432', dbname 'app_development');
   

3. 对齐现有账号权限配置用户映射，避免权限泄露：

   -- 迁移/写操作用的deploy_root账号，映射为主库同权限账号
   CREATE USER MAPPING FOR deploy_root
   SERVER app_main_db
   OPTIONS (user 'deploy_root', password '对应账号的实际密码');
   
   -- 只读副本用的deploy_readonly账号，映射为主库只读账号
   CREATE USER MAPPING FOR deploy_readonly
   SERVER app_main_db
   OPTIONS (user 'deploy_readonly', password '对应账号的实际密码');
   

4. 创建独立schema存放外部映射表，避免和本地表命名冲突，仅导入需要关联的主库表即可，不需要全量导入：

   CREATE SCHEMA IF NOT EXISTS fdw_remote;
   -- 仅导入主库的shops表
   IMPORT FOREIGN SCHEMA public LIMIT TO (shops)
   FROM SERVER app_main_db INTO fdw_remote;
   

后续接入第三数据库applocal_development时，重复上述2-4步，新建对应外部服务、用户映射、外部表schema即可，扩展成本极低。

注意：PostgreSQL不支持直接为外部表创建原生外键约束，我们通过行级触发器实现等价的一致性校验，约束效果和原生外键完全一致。

步骤2：调整迁移文件逻辑 #

原迁移中直接给跨库关联加foreign_key: true会默认查找当前库public schema下的关联表，必须拆分逻辑手动实现：

class CreateYourTargetTable < ActiveRecord::Migration[7.0]
  def change
    create_table :your_target_table do |t|
      # 跨库关联的shop字段先只建字段，不加自动外键参数
      t.bigint :shop_id, null: false
      # role是次级库本地表，保持原外键逻辑不变
      t.references :role, index: true, null: false, foreign_key: true

      t.timestamps
    end

    # 给跨库关联字段单独加索引
    add_index :your_target_table, :shop_id

    # 创建触发器实现跨库外键校验
    execute <<-SQL
      CREATE OR REPLACE FUNCTION validate_cross_db_shop_ref()
      RETURNS trigger AS $$
      BEGIN
        IF NOT EXISTS (SELECT 1 FROM fdw_remote.shops WHERE id = NEW.shop_id) THEN
          RAISE EXCEPTION 'Foreign key violation: shop_id % does not exist in main database shops table', NEW.shop_id;
        END IF;
        RETURN NEW;
      END;
      $$ LANGUAGE plpgsql STABLE;

      CREATE TRIGGER trigger_check_shop_ref
      BEFORE INSERT OR UPDATE ON your_target_table
      FOR EACH ROW EXECUTE FUNCTION validate_cross_db_shop_ref();
    SQL
  end
end

如果需要实现原生外键的级联删除、级联更新效果，只需要在主库shops表上新增对应触发器，检测到记录删除/更新时，通过FDW连接操作次级库的关联数据即可。

步骤3：配置模型关联 #

Rails模型层不需要特殊适配，正常声明关联即可，ORM不会感知数据库层面的跨库逻辑：

# 次级库对应模型
class YourTargetModel < ApplicationRecord
  # 提前在database.yml中配置好appusers_development的连接配置
  establish_connection :appusers_development

  belongs_to :shop
  belongs_to :role
end

# 主库Shop模型
class Shop < ApplicationRecord
  establish_connection :development
  has_many :your_target_models, foreign_key: :shop_id
end

方案说明 #

• 所有数据库部署在同一台服务器上时，postgres_fdw的访问延迟和本地表差异极小，不会带来明显性能损耗
• 触发器实现的校验逻辑会在写入、更新操作时强制校验关联ID合法性，完全避免脏数据产生
• 整套方案不需要引入额外第三方gem，也不需要patch Rails框架源码，后续版本升级兼容性好

内容的提问来源于stack exchange，提问作者Jerome