Document Rails 7.2+ migrations_paths requirement

[abuhtoyarov]

Document Rails 7.2+ migrations_paths requirement

Problem

In Rails 7.2, the behavior of migrations_paths changed. Previously, Rails would call the migrations_paths method on the adapter to determine the migration path. In Rails 7.2+, migrations_paths is now read directly from db_config (database configuration), not from the adapter method.

This means that if migrations_paths is not explicitly specified in the database.yml configuration file, Rails 7.2+ will use the default Rails migration path (db/migrate) instead of the ClickHouse adapter's default (db/migrate_clickhouse).

Solution

Instead of trying to automatically set the default migrations_paths (which would require workarounds), we document the requirement for Rails 7.2+ users to explicitly specify migrations_paths in their database.yml configuration.

Changes

1. README.md:

   • Added note in "Available database connection parameters" section about Rails 7.2+ requirement
   • Added dedicated section in "Usage in Rails" with example configuration for Rails 7.2+

2. lib/active_record/connection_adapters/clickhouse_adapter.rb:

   • Marked migrations_paths method as @deprecated with documentation explaining the Rails 7.2+ requirement
   • Method is kept for backward compatibility with older Rails versions

Impact

• Rails 7.1 and earlier: No changes, existing behavior continues to work
• Rails 7.2+: Users must explicitly specify migrations_paths in database.yml to use custom migration paths

Migration Guide

For Rails 7.2+ users, update your database.yml:

development:
  adapter: clickhouse
  database: database
  migrations_paths: db/migrate_clickhouse  # Required for Rails 7.2+

Related

• Rails 7.2 changed how migrations_paths is read from adapters
• See Rails commit a918394 that introduced this change
  • The commit refactored InternalMetadata and MigrationContext to belong to the pool
  • migrations_paths is now read from db_config via ConnectionPool#migrations_paths method instead of adapter method
  • The method migrations_paths in ConnectionPool uses: db_config.migrations_paths || Migrator.migrations_paths