Add multi-database support to Nandi (#146)

* Add multi-database support to Nandi config (#139)

* Support multi-db in Config

Fix specs and paths

Update comment to use correct class

Update comment and remove unnecessary imports

Make multi database interface private

Fix database specs and config

Fix delegation

* Unify database config

* Lint, update specs and delegation

* Support multi-db in Nandi Lockfile (#142)

* Support multi-db in Nandi Lockfile

Fix bugs, lint

Clean up specs

Fix rubocop violations

* Instantiate lockfile by database

Fix rubocop violations

* Add Nandi::Lockfile.for interface for managing multiple lock files

Reduce diffs in lockfile

Remove unnecessary spec

* Add comments for lockfile .for method and default value for db_name in initialiser

* Remove global nandilock file File mocking

* Remove named argument from `Lockfile.get` method

Remove named arg from safe migration enforcer

* Refactor safe_migration_enforcer to support multi databases (#145)

* Support validating migrations for multi-db mode

* Do not re-order constants

* Refactor safe migration enforcer

* Use separate MigrationViolations class to store state

* Support compiling migrations for multiple databases (#143)

* Remove named argument from `Lockfile.get` method

* Update compile generator args

Pass file_name, database to Nandi.compile, CompiledMigration

Update compiled_migration specs

Remove unused function

Lint changes

Add compile generator spec and fix types

* Update Nandi mocking in specs

* Always cast db name to symbol

Remove unnecessary call

* Add default argument

* Add ability to create safe migrations for multiple databases (#144)

* Add multi-database support to generators

* Update usage docs and add specs

Remove update to compile spec

Update specs

* Clean up usage docs

* Add default value to generator base class

* Bump nandi to next major version

* Update readme with multi-database functionality

* Fix path require issues and standardise name handling

Fix rubocop issues

* Use alias instead of `config`

* Always return a set in safe migration enforcer

* Remove duplicate violations from enforcer

Author: mfmmq

README.md

@@ -336,6 +336,8 @@ Some schema changes need to be split across two migration files. Whenever you wa
 
 For some of the most common cases, we provide a Rails generator that generates both files for you.
 
+All generators support multi-database mode with the `--database` option (see Multi-Database Support section below).
+
 ### Not-null checks
 
 To generate migration files for a not-null check, run this command:
@@ -394,12 +396,23 @@ rails generate nandi:foreign_key foos bar --name my_fk
 Nandi can be configured in various ways, typically in an initializer:
 
 ```rb
+# Single database configuration
 Nandi.configure do |config|
+  config.migration_directory = "db/safe_migrations"
   config.lock_timeout = 1_000
 end
+
+# Multi-database configuration (see Multi-Database Support section below)
+Nandi.configure do |config|
+  config.register_database(:primary)
+  config.register_database(:analytics,
+    migration_directory: "db/analytics_safe_migrations",
+    output_directory: "db/analytics_migrate"
+  )
+end
 ```
 
-The configuration parameters are as follows.
+The configuration parameters are as follows for setting Nandi up for a single database.
 
 ### `access_exclusive_lock_timeout_limit` (Integer)
 
@@ -419,11 +432,11 @@ The default lock timeout for migrations. Can be overridden by way of the `set_lo
 
 ### `migration_directory` (String)
 
-The directory for Nandi migrations. Default: `db/safe_migrations`
+The directory for Nandi migrations. Default: `db/safe_migrations`.
 
 ### `output_directory` (String)
 
-The directory for output files. Default: `db/migrate`
+The directory for output files. Default: `db/migrate`.
 
 ### `renderer` (Class)
 
@@ -470,6 +483,142 @@ Parameters:
 
 `klass` (Class) — The class to initialise with the arguments to the method. It should define a `template` instance method which will return a subclass of Cell::ViewModel from the Cells templating library and a `procedure` method that returns the name of the method. It may optionally define a `mixins` method, which will return an array of `Module`s to be mixed into any migration that uses this method.
 
+## Multi-Database Support
+
+Nandi 2.0+ supports managing migrations for multiple databases within a single Rails application. 
+
+**Note:** Single database configurations continue to work without any changes. Multi-database support is fully backward compatible.
+
+### Configuring Multiple Databases
+
+Instead of setting configuration values directly, register each database with its own configuration. If no values are specified, the existing defaults will be used.
+
+**Database-specific options** (passed to `register_database`):
+These options can be set individually for each database. **All are optional** - if not specified, the standard Nandi defaults are used:
+
+- `migration_directory`: Where Nandi migrations are stored (default: `"db/safe_migrations"` for primary, `"db/<name>_safe_migrations"` for others)
+- `output_directory`: Where compiled ActiveRecord migrations go (default: `"db/migrate"` for primary, `"db/<name>_migrate"` for others)
+- `lockfile_name`: Name of the lockfile for this database (default: `".nandilock.yml"` for primary, `".<name>_nandilock.yml"` for others)
+- `default`: Mark this database as the default when not named `:primary` (default: `false`)
+- `access_exclusive_lock_timeout`: Timeout for ACCESS EXCLUSIVE locks (default: 5,000ms)
+- `access_exclusive_statement_timeout`: Statement timeout for ACCESS EXCLUSIVE operations (default: 1,500ms)
+- `access_exclusive_lock_timeout_limit`: Maximum allowed lock timeout (default: 5,000ms)
+- `access_exclusive_statement_timeout_limit`: Maximum allowed statement timeout (default: 1,500ms)
+- `concurrent_lock_timeout_limit`: Minimum timeout for concurrent operations (default: 3,600,000ms / 1 hour)
+- `concurrent_statement_timeout_limit`: Minimum statement timeout for concurrent operations (default: 3,600,000ms / 1 hour)
+
+**Global options** (set via config accessors):
+
+These options apply to all databases:
+
+- `config.lockfile_directory`: Directory where all lockfiles are stored (default: `"db"`)
+- `config.compile_files`: Filter for which files to compile (default: `"all"`)
+- `config.renderer`: Rendering backend (default: `Nandi::Renderers::ActiveRecord`)
+- `config.post_process { |migration| ... }`: Optional post-processing block for formatting
+
+```rb
+# Minimal configuration - primary uses all defaults
+Nandi.configure do |config|
+  config.register_database(:primary)  # Uses all default paths and settings
+
+  config.register_database(:analytics)
+
+  # Global options (apply to all databases)
+  config.lockfile_directory = "db"
+  config.compile_files = "all"
+end
+
+# Full example with both database-specific and global options
+Nandi.configure do |config|
+  # Primary database (automatically becomes default)
+  # If no values are specified, uses the standard defaults:
+  # - migration_directory: "db/safe_migrations"
+  # - output_directory: "db/migrate"
+  # - lockfile_name: ".nandilock.yml"
+  # - All timeout values use their defaults
+  config.register_database(:primary,
+    access_exclusive_lock_timeout: 5_000  # Only override what you need
+  )
+
+  # Analytics database with custom paths and relaxed timeouts
+  config.register_database(:analytics,
+    migration_directory: "db/analytics_safe_migrations",
+    output_directory: "db/analytics_migrate",
+    lockfile_name: ".analytics_nandilock.yml",
+    access_exclusive_lock_timeout: 30_000,
+    access_exclusive_statement_timeout: 10_000,
+    concurrent_statement_timeout_limit: 7_200_000
+  )
+
+  # Global configuration options (apply to all databases)
+  config.lockfile_directory = "db"       # Where all lockfiles are stored
+  config.compile_files = "all"           # Filter for compilation
+  config.renderer = Nandi::Renderers::ActiveRecord  # Optional, this is the default
+
+  # Optional post-processing for all compiled migrations
+  config.post_process do |migration|
+    # Format, lint, etc.
+    migration
+  end
+end
+```
+
+### Directory Structure
+
+Each database maintains its own directory structure. The primary database uses the default paths if not specified:
+
+```
+db/
+├── safe_migrations/              # Primary database (default path)
+│   └── 20250901_add_users.rb
+├── migrate/                     # Primary database (default path)
+│   └── 20250901_add_users.rb
+├── .nandilock.yml                # Primary database (default)
+│
+├── analytics_safe_migrations/    # Analytics database
+│   └── 20250902_add_events.rb
+├── analytics_migrate/
+│   └── 20250902_add_events.rb
+├── .analytics_nandilock.yml
+│
+├── reporting_safe_migrations/    # Reporting database
+│   └── 20250903_add_reports.rb
+├── reporting_migrate/
+│   └── 20250903_add_reports.rb
+└── .reporting_nandilock.yml
+```
+
+### Using Generators with Multiple Databases
+
+All Nandi generators accept a `--database` option to specify which database to target:
+
+```bash
+# Generate for primary database (default)
+rails generate nandi:migration create_users_table
+
+# Generate for analytics database
+rails generate nandi:migration create_events_table --database=analytics
+```
+
+### Compiling Migrations
+
+The compile generator can compile all databases or a specific one:
+
+```bash
+# Compile all databases
+rails generate nandi:compile
+
+# Compile specific database with filter
+rails generate nandi:compile --database=analytics --files=git-diff
+```
+
+### Default Database
+
+- If you register a database named `:primary`, it automatically becomes the default per rails conventions
+- Otherwise, mark a database as default with `default: true`
+- Generators without `--database` option use the default database
+- Single database configurations work without changes
+
 ## `.nandiignore`
 
 To protect people from writing unsafe migrations, we provide a script [`nandi-enforce`](https://github.com/gocardless/nandi/blob/master/exe/nandi-enforce) that ensures all migrations in the specified directories are safe migrations generated by Nandi.

lib/generators/nandi/check_constraint/USAGE

@@ -9,6 +9,8 @@ Example:
         db/safe_migrations/20190424123727_add_check_constraint_baz_or_quux_not_null_on_foos.rb
         db/safe_migrations/20190424123728_validate_check_constraint_baz_or_quux_not_null_on_foos.rb
 
+    If no --database option is specified, uses the default database.
+
 Example:
     rails generate nandi:check_constraint foos baz_or_quux_not_null --validation-timeout 20000
 
@@ -17,3 +19,10 @@ Example:
         db/safe_migrations/20190424123728_validate_check_constraint_baz_or_quux_not_null_on_foos.rb
 
     The statement timeout in the second migration will be set to 20,000ms.
+
+Multi-database examples:
+    rails generate nandi:check_constraint users email_valid --database primary
+        creates check constraint migrations in primary database directory
+
+    rails generate nandi:check_constraint events status_valid --database analytics
+        creates check constraint migrations in analytics database directory

lib/generators/nandi/check_constraint/check_constraint_generator.rb

@@ -2,10 +2,12 @@
 
 require "rails/generators"
 require "nandi/formatting"
+require "nandi/multi_db_generator"
 
 module Nandi
   class CheckConstraintGenerator < Rails::Generators::Base
     include Nandi::Formatting
+    include Nandi::MultiDbGenerator
 
     argument :table, type: :string
     argument :name, type: :string
@@ -41,10 +43,6 @@ def validate_check_constraint
 
     private
 
-    def base_path
-      Nandi.config.migration_directory || "db/safe_migrations"
-    end
-
     def timestamp(offset = 0)
       (Time.now.utc + offset).strftime("%Y%m%d%H%M%S")
     end

lib/generators/nandi/compile/USAGE

@@ -1,10 +1,15 @@
 Description:
-    Takes all files from the db/nandi directory and turns
-    them into ActiveRecordmigration files.
+    Takes all files from the safe migration directories and turns
+    them into ActiveRecord migration files. Supports both single
+    and multi-database configurations.
+
+    If no --database option is specified, compiles for all configured databases
+    (or the default database in single-database configurations).
 
 Examples:
     rails generate nandi:compile
         compiles all migrations that have changed since last git commit
+        (for all configured databases in multi-database setups)
 
     rails generate nandi:compile --files all
         compiles all migrations ever
@@ -17,3 +22,10 @@ Examples:
 
     rails generate nandi:compile --files >=20190101
         compiles all migrations from January 1st 2019 and after
+
+Multi-database examples:
+    rails generate nandi:compile --database primary
+        compiles migrations only for the primary database
+
+    rails generate nandi:compile --database analytics
+        compiles migrations only for the analytics database

lib/generators/nandi/compile/compile_generator.rb

@@ -10,6 +10,12 @@ module Nandi
   class CompileGenerator < Rails::Generators::Base
     source_root File.expand_path("templates", __dir__)
 
+    class_option :database,
+                 type: :string,
+                 default: nil,
+                 desc: "Database to compile. " \
+                       "If not specified, compiles for all databases"
+
     class_option :files,
                  type: :string,
                  default: Nandi.config.compile_files,
@@ -22,41 +28,38 @@ class CompileGenerator < Rails::Generators::Base
                  DESC
 
     def compile_migration_files
-      Nandi.compile(files: files) do |results|
-        results.each do |result|
-          Nandi::Lockfile.add(
-            file_name: result.file_name,
-            source_digest: result.source_digest,
-            compiled_digest: result.compiled_digest,
-          )
-
-          unless result.migration_unchanged?
-            create_file result.output_path, result.body, force: true
+      databases.each do |db_name|
+        Nandi.compile(files: files(db_name), db_name: db_name) do |results|
+          results.each do |result|
+            Nandi::Lockfile.for(db_name).add(
+              file_name: result.file_name,
+              source_digest: result.source_digest,
+              compiled_digest: result.compiled_digest,
+            )
+            unless result.migration_unchanged?
+              create_file result.output_path, result.body, force: true
+            end
           end
         end
+        Nandi::Lockfile.for(db_name).persist!
       end
-
-      Nandi::Lockfile.persist!
     end
 
     private
 
-    def safe_migrations_dir
-      if Nandi.config.migration_directory.nil?
-        Rails.root.join("db", "safe_migrations").to_s
-      else
-        File.expand_path(Nandi.config.migration_directory)
-      end
+    def databases
+      return [options[:database].to_sym] if options[:database]
+
+      Nandi.config.databases.names
     end
 
-    def output_path
-      Nandi.config.output_directory || "db/migrate"
+    def safe_migrations_dir(db_name)
+      File.expand_path(Nandi.config.migration_directory(db_name))
     end
 
-    def files
-      safe_migration_files = Dir.chdir(safe_migrations_dir) { Dir["*.rb"] }
-      FileMatcher.call(files: safe_migration_files, spec: options["files"]).
-        map { |file| File.join(safe_migrations_dir, file) }
+    def files(db_name)
+      safe_migration_files = Dir.chdir(safe_migrations_dir(db_name)) { Dir["*.rb"] }
+      FileMatcher.call(files: safe_migration_files, spec: options["files"])
     end
   end
 end

lib/generators/nandi/foreign_key/USAGE

@@ -14,6 +14,8 @@ Example:
     new foreign key constraint on that column against the id column of bars, and
     validate that constraint separately.
 
+    If no --database option is specified, uses the default database.
+
 Example:
     rails generate nandi:foreign_key foos bars --type text
 
@@ -45,3 +47,10 @@ Example:
 
     Assumes that there is a column on table foos called special_bar_id that points to
     bars. Will create an FK constraint called my_fk
+
+Multi-database examples:
+    rails generate nandi:foreign_key posts users --database primary
+        creates foreign key migrations in primary database directory
+
+    rails generate nandi:foreign_key events sessions --database analytics
+        creates foreign key migrations in analytics database directory

lib/generators/nandi/foreign_key/foreign_key_generator.rb

@@ -2,10 +2,12 @@
 
 require "rails/generators"
 require "nandi/formatting"
+require "nandi/multi_db_generator"
 
 module Nandi
   class ForeignKeyGenerator < Rails::Generators::Base
     include Nandi::Formatting
+    include Nandi::MultiDbGenerator
 
     argument :table, type: :string
     argument :target, type: :string
@@ -68,10 +70,6 @@ def reference_name
       :"#{target.singularize}_id"
     end
 
-    def base_path
-      Nandi.config.migration_directory || "db/safe_migrations"
-    end
-
     def timestamp(offset = 0)
       (Time.now.utc + offset).strftime("%Y%m%d%H%M%S")
     end