dynamic-active-model-rails 0.14.0 → 0.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e99654c467d82a550320a4952955c2ac035a218940ba178f4aab57ea6036c438
-  data.tar.gz: fc7f43e364ced45bd2d52e0ea918ae4498ea690d3414a1c830c20f03495dc836
+  metadata.gz: 72bf2f4e81912203cc8fa972baec98b8e25fbca4565272a9e5bd7a915bb5bbd3
+  data.tar.gz: be83fdc8eaa6cb83c83d6298d54be005779ecd4dc4931a2c3216d3a5c5aa2342
 SHA512:
-  metadata.gz: edd5f4bacf38a6a2e3fa610da7f6fe4aa01e781d7675feeb39164e97085842fbdaeb85d6ba8bc027b09672a58adaec9f875db1cdf352868a5c91b38ecece64cb
-  data.tar.gz: 6e5616c8bb2b5ca5c3fc7868f51d6b22b9c40ec0bfb6fd3d8c9942e57fc321eb7c445b1a09628416c71aee958b0c926c2cf7ca2239cce482fa9f5de48b5fcbbf
+  metadata.gz: 40a0d18557415731182cd67634f5dfac07e9394ce6a8715d437ab1c0a28f85f1dd0177d41b043bb3610f76aa1688dd58b49e9f5a9546508d8a0412c0b5466638
+  data.tar.gz: 3dc87829e2442bceb70c63127cc3a7ef00a43c3741166c721e4e8100a6468e6ad881dfc6b87dd4718dc30f2c984cadf76393d128d732cdb359e44f86e656a3ef

data/README.md

@@ -19,6 +19,7 @@ gem 'dynamic-active-model-rails'
 bin/rails generate dynamic_active_model:install                        # DB, app/models/db/
 bin/rails generate dynamic_active_model:install grant_db               # GrantDB, app/models/grant_db/
 bin/rails generate dynamic_active_model:database cars --connection cars
+bin/rails generate dynamic_active_model:database cars --connection cars --replica cars_replica
 bin/rails generate dynamic_active_model:extension grant_db users       # app/models/grant_db/users.ext.rb
 ```
 
@@ -26,7 +27,7 @@ bin/rails generate dynamic_active_model:extension grant_db users       # app/mod
 - **`database NAME`** adds another `add_database` line to the initializer and creates the folder. It refuses a namespace the app already declares.
 - **`extension DATABASE TABLE`** creates an extension file. `DATABASE` can be a name (`grant_db`) or a namespace (`GrantDB`). The generator uses the app's configuration, so a custom `extensions_path:` or `extensions_suffix:` is respected.
 
-`--connection NAME` points the database at a `database.yml` entry. The generators warn if the current environment has no such entry. Without `--connection`, the database shares `ApplicationRecord`'s connection.
+`--connection NAME` points the database at a `database.yml` entry. `--replica NAME` adds a reading role through `connects_to` and requires `--connection`. The generators warn if the current environment has no such entry. Without `--connection`, the database shares `ApplicationRecord`'s connection.
 
 ## Configuration
 
@@ -76,9 +77,41 @@ The `cars_db` → `CarsDB` mapping is registered with the Rails autoloader only,
 | `connection` (2nd argument) | `nil` | `nil` shares the parent class's connection. Otherwise it's passed to `establish_connection`: a database.yml entry name (Symbol), URL or hash. |
 | `module_name:` | `"<Name>DB"` | Namespace override. |
 | `parent_class:` | `'ApplicationRecord'` | Superclass of the generated abstract base class, given as a name so it can be reloaded. |
+| `connects_to:` | `nil` | Roles for Rails multi-database support, such as `{ writing: :cars, reading: :cars_replica }`, or `connects_to`'s own arguments (`{ database: ..., shards: ... }`). Can't be combined with a `connection`. |
 | `extensions_path:` | `app/models/<folder>` | Directory of extension files, absolute or relative to `Rails.root`. The default folder may be absent; a configured path must exist. |
 | `extensions_suffix:` | `'.ext.rb'` | Suffix of extension files. The autoloader ignores files with this suffix. |
 
+## Read Replicas
+
+`connects_to:` registers the database's roles with Rails' multi-database support:
+
+```ruby
+config.add_database :cars, connects_to: { writing: :cars, reading: :cars_replica }
+```
+
+```yaml
+# config/database.yml
+production:
+  cars:
+    <<: *default
+    database: cars
+  cars_replica:
+    <<: *default
+    database: cars
+    replica: true
+```
+
+Switch roles for one database through its namespace, or for every database with ActiveRecord:
+
+```ruby
+CarsDB.connected_to(role: :reading) { CarsDB::Car.count }       # only CarsDB
+ActiveRecord::Base.connected_to(role: :reading) { ... }          # all databases with roles
+```
+
+Writes inside the reading role raise `ActiveRecord::ReadOnlyError`. Rails' automatic role switching (`config.active_record.database_selector`) works too. Shards pass through as well: `connects_to: { shards: { one: { writing: :cars_one } } }`.
+
+A database that shares `ApplicationRecord`'s connection follows `ApplicationRecord`'s roles. `GrantDB.connected_to(...)` switches `ApplicationRecord`.
+
 ## Extending Models
 
 Add one `<table_name>.ext.rb` file per table to the database's folder:
@@ -125,6 +158,26 @@ Avoid `Rails.application.config.after_initialize { GrantDB.database... }`. It ru
 - **Migrations.** After migrations run or a schema is loaded (`db:migrate`, `db:rollback`, `db:prepare`, `db:schema:load`, `maintain_test_schema!`), models are reset and rebuild on next use. That means `bin/rails db:prepare` followed by seeding works in one process.
 - **Reloading.** In development, models are rebuilt whenever the app reloads, including after edits to `.ext.rb` files or to anything under `db/`, such as a migration rewriting `db/schema.rb`.
 
+## Schema Cache
+
+Models read columns, primary keys and indexes through Rails' schema cache. Dump it at deploy time, and building models no longer queries every table:
+
+```bash
+bin/rails db:schema:cache:dump   # db/schema_cache.yml, db/<name>_schema_cache.yml
+```
+
+| | Queries to build 5 tables (SQLite) |
+|---|---|
+| No dump | 28 |
+| Dump, Rails defaults | 4 |
+| Dump, `config.active_record.check_schema_cache_dump_version = false` | 2 |
+
+The table list is always one live query. The dump holds each table's indexes (name, uniqueness, columns), so associations come out the same as from live queries, including `has_one` from unique indexes and join tables.
+
+A dump is only as fresh as the last `db:schema:cache:dump`. By default, Rails compares the dump's schema version with the database, and ignores the dump after a migration. That version only tracks migrations, though. For a database whose schema changes outside Rails migrations, such as a legacy or externally managed database, regenerate the dump on every deploy or don't use one. Otherwise new columns, indexes and associations are missed. With `check_schema_cache_dump_version = false`, any stale dump is used.
+
+When models are reset after a code reload or schema change, the gem clears the database's schema cache too. That matters because Rails only clears the primary database's cache on reload.
+
 ## Migrations
 
 Migrations stay standard Rails. The gem reads the schema; it never owns it. For a secondary database, give its database.yml entry a `migrations_paths`:

data/lib/dynamic-active-model/rails/database_definition.rb

@@ -26,6 +26,9 @@ module DynamicActiveModel
       # @return [String] File suffix of extension files
       attr_reader :extensions_suffix
 
+      # @return [Hash, nil] Keyword arguments for the base class's connects_to
+      attr_reader :connects_to
+
       # @return [Hash] Custom relationship names by table and foreign key
       attr_reader :relationships
 
@@ -39,9 +42,15 @@ module DynamicActiveModel
       # @param extensions_path [String, nil] Extensions directory, absolute or relative to
       #   the app root; defaults to app/models/<folder>, which may be absent
       # @param extensions_suffix [String] File suffix of extension files
+      # @param connects_to [Hash, nil] Roles ({ writing: :cars, reading: :cars_replica }) or
+      #   connects_to's own arguments ({ database: ..., shards: ... })
+      # @raise [ArgumentError] If both a connection and connects_to are given
       def initialize(name, connection = nil, module_name: nil, parent_class: 'ApplicationRecord',
-                     extensions_path: nil, extensions_suffix: '.ext.rb')
+                     extensions_path: nil, extensions_suffix: '.ext.rb', connects_to: nil)
+        raise ArgumentError, 'pass either a connection or connects_to:, not both' if connection && connects_to
+
         @connection = connection
+        @connects_to = connects_to && normalize_connects_to(connects_to)
         @module_name = module_name || default_module_name(name)
         @parent_class_name = parent_class.to_s
         @extensions_path = extensions_path&.to_s
@@ -68,6 +77,12 @@ module DynamicActiveModel
         File.expand_path(@extensions_path || File.join('app', 'models', folder), root.to_s)
       end
 
+      # @return [Boolean] Whether the generated base class owns its connection, rather
+      #   than sharing the parent class's
+      def own_connection?
+        !(connection.nil? && connects_to.nil?)
+      end
+
       # @return [Boolean] Whether extensions_path was configured, so it must exist
       def custom_extensions_path?
         !@extensions_path.nil?
@@ -107,6 +122,13 @@ module DynamicActiveModel
 
       private
 
+      # Treats a hash of roles as connects_to's database: argument
+      # @param options [Hash]
+      # @return [Hash]
+      def normalize_connects_to(options)
+        options.key?(:database) || options.key?(:shards) ? options : { database: options }
+      end
+
       # :cars => "CarsDB", :grant_db => "GrantDB", :db => "DB"
       # @param name [Symbol, String]
       # @return [String]

data/lib/dynamic-active-model/rails/database_loader.rb

@@ -27,16 +27,28 @@ module DynamicActiveModel
         @database
       end
 
+      # The class that owns the database's connection, for role and shard switching:
+      # the generated base class, or the parent class when sharing its connection
+      # @return [Class]
+      def connection_class
+        base_class = load!.factory.base_class
+        definition.own_connection? ? base_class : base_class.superclass
+      end
+
       # @return [Boolean] Whether models are built (or being built)
       def loaded?
         !@database.nil?
       end
 
-      # Removes the built models so the next #load! rebuilds them
+      # Removes the built models, and the schema cache their columns and indexes
+      # came from, so the next #load! rebuilds them against the current schema
       # @return [void]
       def reset!
         @monitor.synchronize do
-          @database&.reset!
+          if @database
+            clear_schema_cache
+            @database.reset!
+          end
           @database = nil
         end
       end
@@ -57,9 +69,17 @@ module DynamicActiveModel
         raise
       end
 
+      # Clears the schema cache of the pool the models use. Rails clears only the
+      # primary pool on code reload, and nothing on schema changes outside migrations.
+      # @return [void]
+      def clear_schema_cache
+        @database.models.map(&:connection_pool).uniq.each { |pool| pool.schema_cache.clear! }
+      end
+
       # @return [DynamicActiveModel::Database] A database configured from the definition
       def new_database
         Database.new(namespace, definition.connection, parent_class: parent_class).tap do |database|
+          database.factory.base_class.connects_to(**definition.connects_to) if definition.connects_to
           definition.skipped_tables.each { |table| database.skip_table(Explorer.skip_table_matcher(table)) }
           definition.included_tables.each { |table| database.include_table(Explorer.skip_table_matcher(table)) }
           definition.table_class_names.each { |table, class_name| database.table_class_name(table, class_name) }

data/lib/dynamic-active-model/rails/lazy_namespace.rb

@@ -34,6 +34,13 @@ module DynamicActiveModel
         database.models
       end
 
+      # Switches role or shard for this database's models, like ActiveRecord's
+      # connected_to, e.g. CarsDB.connected_to(role: :reading) { CarsDB::Car.count }
+      # @return [Object] The block's result
+      def connected_to(**, &)
+        dynamic_active_model_loader.connection_class.connected_to(**, &)
+      end
+
       # Builds the models on first reference, then retries the lookup
       # @param name [Symbol]
       # @return [Object]

data/lib/generators/dynamic_active_model/database/database_generator.rb

@@ -14,6 +14,10 @@ module DynamicActiveModel
 
       argument :name, type: :string, banner: 'NAME'
 
+      def check_options
+        check_replica_has_connection
+      end
+
       def check_initializer
         return if File.exist?(File.join(destination_root, INITIALIZER))
 

data/lib/generators/dynamic_active_model/database_arguments.rb

@@ -2,7 +2,7 @@
 
 module DynamicActiveModel
   module Generators
-    # Shared --connection option and helpers for generators that declare a database
+    # Shared --connection/--replica options and helpers for generators that declare a database
     module DatabaseArguments
       INITIALIZER = 'config/initializers/dynamic_active_model.rb'
 
@@ -10,6 +10,9 @@ module DynamicActiveModel
         base.class_option :connection,
                           type: :string,
                           desc: "database.yml entry to connect to (default: share ApplicationRecord's connection)"
+        base.class_option :replica,
+                          type: :string,
+                          desc: 'database.yml entry for the reading role (requires --connection)'
       end
 
       private
@@ -20,10 +23,26 @@ module DynamicActiveModel
       end
 
       # @return [String] e.g. "config.add_database :cars, :cars"
+      # @raise [Thor::Error] If --replica is given without --connection
       def add_database_line
-        args = [name.underscore.to_sym.inspect]
-        args << options[:connection].to_sym.inspect if options[:connection]
-        "config.add_database #{args.join(', ')}"
+        "config.add_database #{[name.underscore.to_sym.inspect, *connection_args].join(', ')}"
+      end
+
+      # @return [Array<String>] Connection arguments for add_database
+      def connection_args
+        return [] unless options[:connection]
+        return [options[:connection].to_sym.inspect] unless options[:replica]
+
+        roles = { writing: options[:connection], reading: options[:replica] }
+        ["connects_to: { #{roles.map { |role, entry| "#{role}: #{entry.to_sym.inspect}" }.join(', ')} }"]
+      end
+
+      # Fails before anything is generated when --replica lacks --connection
+      # @return [void]
+      def check_replica_has_connection
+        return unless options[:replica] && !options[:connection]
+
+        raise Thor::Error, '--replica requires --connection (the writing database)'
       end
 
       # Creates the database's models folder for its extension files
@@ -32,13 +51,21 @@ module DynamicActiveModel
         create_file File.join(definition.extensions_path(destination_root), '.keep')
       end
 
-      # Warns when --connection names a database.yml entry the current environment lacks
+      # Warns when --connection or --replica names a database.yml entry the current environment lacks
       # @return [void]
       def warn_about_missing_connection
-        return unless options[:connection]
-        return if ActiveRecord::Base.configurations.configs_for(env_name: ::Rails.env, name: options[:connection])
+        options.values_at(:connection, :replica).compact.each do |entry|
+          next if configured?(entry)
+
+          say_status :warning, "config/database.yml has no #{entry} entry for #{::Rails.env}", :yellow
+        end
+      end
 
-        say_status :warning, "config/database.yml has no #{options[:connection]} entry for #{::Rails.env}", :yellow
+      # @param entry [String] database.yml entry name
+      # @return [Boolean] Whether the current environment has it; replica: true
+      #   entries are hidden unless asked for
+      def configured?(entry)
+        !ActiveRecord::Base.configurations.configs_for(env_name: ::Rails.env, name: entry, include_hidden: true).nil?
       end
     end
   end

data/lib/generators/dynamic_active_model/install/install_generator.rb

@@ -15,6 +15,10 @@ module DynamicActiveModel
 
       argument :name, type: :string, default: 'db', banner: 'NAME'
 
+      def check_options
+        check_replica_has_connection
+      end
+
       def create_initializer
         template 'dynamic_active_model.rb.tt', INITIALIZER
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dynamic-active-model-rails
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.1
 platform: ruby
 authors:
 - Doug Youch
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.14.0
+        version: 0.15.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.14.0
+        version: 0.15.1
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement