nandi 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3c09dc76de1e4d072270551a10f9f244ea4e9b79f4cdc2bb21069764e722724
-  data.tar.gz: a6f9af91f0fd1012d8734c75ba1289d2afea7217dab6b1c4d0e0fbba6c6be052
+  metadata.gz: ec4e2b089c4336135b3899d3d01ac55fd0876fa5f76b22f1672fb494c2267fce
+  data.tar.gz: f66eac48b75fcf959bacc454197c6fb09c6332026ea08a2587e02f6fcc6049fe
 SHA512:
-  metadata.gz: 75284ae3b4f85e75fe0293e16ecef39db7cbd68098044066a1dd5c2e9222518871b2f194d9d4bc936663ae11bb76d5d4e5c13931bf3d530fb196efe6d0d88bb4
-  data.tar.gz: 0a4bba3b7bce0c6888f21d327522789ad5ccff683aa34356fc5733d18d9b3ad61512a7955dd310ebad48e652497b2310c199def599fb1d469cd01a2124733f79
+  metadata.gz: adc1220776ae8fb445ba59c7755e6b80e3449897211485804461a02ebace759d22d098955e67d3ded835f9ff8871c72116b62e4c6aa7f7f9bd5a2f5ecaff3766
+  data.tar.gz: 9d6d92342078cc00360874bc73b8a87407497ef0c694aaefbb5b465215b3965063fab62b9ad753c937110231de7b368c48cabb829b004a510e98c423e333e63a

data/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.

data/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

data/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 @@ module Nandi
 
     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

data/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

data/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 @@ module Nandi
                  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

data/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

data/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 @@ module Nandi
       :"#{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

data/lib/generators/nandi/index/USAGE

@@ -1,6 +1,8 @@
 Description:
     Generates new database indices
 
+    If no --database option is specified, uses the default database.
+
 Example:
     rails generate nandi:index table_name index_col
 
@@ -29,3 +31,10 @@ Example:
     This will create:
         db/safe_migrations/20190424123727_add_index_on_index_col_to_table_name.rb
     with the specified bespoke index name
+
+Multi-database examples:
+    rails generate nandi:index users email --database primary
+        creates index migration in primary database directory
+
+    rails generate nandi:index events created_at --database analytics
+        creates index migration in analytics database directory

data/lib/generators/nandi/index/index_generator.rb

@@ -2,10 +2,12 @@
 
 require "rails/generators"
 require "nandi/formatting"
+require "nandi/multi_db_generator"
 
 module Nandi
   class IndexGenerator < Rails::Generators::Base
     include Nandi::Formatting
+    include Nandi::MultiDbGenerator
 
     argument :tables, type: :string
     argument :columns, type: :string
@@ -42,10 +44,6 @@ module Nandi
       (Time.now.utc + offset).strftime("%Y%m%d%H%M%S")
     end
 
-    def base_path
-      Nandi.config.migration_directory || "db/safe_migrations"
-    end
-
     def override_index_name
       options["index_name"]&.to_sym
     end

data/lib/generators/nandi/migration/USAGE

@@ -1,9 +1,19 @@
 Description:
     Generates a new database migration which uses the
-    nandi DSL in db/nandi
+    nandi DSL. Supports both single and multi-database
+    configurations.
 
-Example:
+    If no --database option is specified, uses the default database.
+
+Examples:
     rails generate nandi:migration add_stuff_to_things
 
     This will create:
         db/safe_migrations/20190424123727_add_stuff_to_things.rb
+
+Multi-database examples:
+    rails generate nandi:migration add_stuff_to_things --database primary
+        creates migration in primary database directory
+
+    rails generate nandi:migration add_analytics_table --database analytics
+        creates migration in analytics database directory

data/lib/generators/nandi/migration/migration_generator.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
 require "rails/generators"
+require "nandi/multi_db_generator"
 
 module Nandi
   class MigrationGenerator < Rails::Generators::NamedBase
+    include Nandi::MultiDbGenerator
+
     source_root File.expand_path("templates", __dir__)
 
     def create_migration_file
@@ -14,11 +17,5 @@ module Nandi
         "#{base_path}/#{timestamp}_#{file_name.underscore}.rb",
       )
     end
-
-    private
-
-    def base_path
-      Nandi.config.migration_directory || "db/safe_migrations"
-    end
   end
 end

data/lib/generators/nandi/not_null_check/USAGE

@@ -2,6 +2,8 @@ Description:
     Generates two new database migrations which will safely add a check that
     a column is not null, and validate it separately.
 
+    If no --database option is specified, uses the default database.
+
 Example:
     rails generate nandi:not_null_check foos bar
 
@@ -17,3 +19,10 @@ Example:
         db/safe_migrations/20190424123728_validate_not_null_check_on_bar_to_foos.rb
 
     The statement timeout in the second migration will be set to 20,000ms.
+
+Multi-database examples:
+    rails generate nandi:not_null_check users email --database primary
+        creates not null check migrations in primary database directory
+
+    rails generate nandi:not_null_check events user_id --database analytics
+        creates not null check migrations in analytics database directory

data/lib/generators/nandi/not_null_check/not_null_check_generator.rb

@@ -2,10 +2,12 @@
 
 require "rails/generators"
 require "nandi/formatting"
+require "nandi/multi_db_generator"
 
 module Nandi
   class NotNullCheckGenerator < Rails::Generators::Base
     include Nandi::Formatting
+    include Nandi::MultiDbGenerator
 
     argument :table, type: :string
     argument :column, type: :string
@@ -41,10 +43,6 @@ module Nandi
 
     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

data/lib/nandi/compiled_migration.rb

@@ -6,15 +6,21 @@ module Nandi
   class CompiledMigration
     class InvalidMigrationError < StandardError; end
 
-    attr_reader :file_name, :source_file_path, :class_name
+    attr_reader :file_name, :source_file_path, :class_name, :db_config
 
-    def self.build(source_file_path)
-      new(source_file_path)
+    def db_name
+      @db_config.name
     end
 
-    def initialize(source_file_path)
-      @source_file_path = source_file_path
-      require source_file_path
+    def self.build(file_name:, db_name:)
+      new(file_name:, db_name:)
+    end
+
+    def initialize(file_name:, db_name:)
+      @file_name = file_name
+      @db_config = Nandi.config.database(db_name)
+      @source_file_path = File.join(@db_config.migration_directory, file_name)
+      require File.expand_path(source_file_path)
 
       @file_name, @class_name = /\d+_([a-z0-9_]+)\.rb\z/.match(source_file_path)[0..1]
     end
@@ -40,7 +46,7 @@ module Nandi
     end
 
     def output_path
-      "#{Nandi.compiled_output_directory}/#{file_name}"
+      "#{db_config.output_directory}/#{file_name}"
     end
 
     def migration
@@ -58,14 +64,16 @@ module Nandi
     def migration_unchanged?
       return false unless File.exist?(output_path)
 
+      lockfile = Nandi::Lockfile.for(db_config.name)
+
       source_migration_diff = Nandi::FileDiff.new(
         file_path: source_file_path,
-        known_digest: Nandi::Lockfile.get(file_name).fetch(:source_digest),
+        known_digest: lockfile.get(file_name).fetch(:source_digest),
       )
 
       compiled_migration_diff = Nandi::FileDiff.new(
         file_path: output_path,
-        known_digest: Nandi::Lockfile.get(file_name).fetch(:compiled_digest),
+        known_digest: lockfile.get(file_name).fetch(:compiled_digest),
       )
 
       source_migration_diff.unchanged? && compiled_migration_diff.unchanged?