dynamic-active-model-rails 0.13.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8515d28d9394768614fb8cd2f4cf49173ab1d5f97c905debbf3f9dc85d21f21
-  data.tar.gz: 33388b8956cc6106da4d6d94d0255a15b66d6156be30a49cfa9c941f31f3ed4e
+  metadata.gz: c00e8c89d4f3d145711f0ec10472dda48b3dfd38ab11e921a2efa26641cf71e3
+  data.tar.gz: 13900a4926179764ed30e642f44fd19dca06cbbe5742226292aafc8c06537ebb
 SHA512:
-  metadata.gz: ed7b1653b8ea5643e50b797a0cad76714958d204052ee97ba44cd10eed2e3f2103e20bcad4c16ee7277a12886ef85cceb6421a8ca41c485dec72dbac67b89fc4
-  data.tar.gz: 42a9e8a11125f32d8e9ea403662e232d602595c776c7829a05f7759fd14f4c9fa88822100fd92dd52c2e2188fb39c1d95082eb62c0bef16f6f5c2c17ba13beed
+  metadata.gz: 1d0a57c73c5976963edec4c2d9b9c928907a95476219085cca20ab8d2a57b8399f329b29c67e91ae00ca885da623f8a36680e025199e21aaab032066e10c124b
+  data.tar.gz: 5dd9266a94e120c327f54a2677a42a88094bbb6caf54a66b1e129641352048609d9dd56bdcd43b44ecf74a9941597c9b08b5dee5a6e8e04de57cdccca6d0b709

data/README.md

@@ -13,6 +13,22 @@ gem 'dynamic-active-model-rails'
 
 `dynamic-active-model-rails` is released in lockstep with `dynamic-active-model` and pins the same version.
 
+## Generators
+
+```bash
+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
+```
+
+- **`install [NAME]`** creates `config/initializers/dynamic_active_model.rb`, declaring the first database (default `db`), and its models folder.
+- **`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. `--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
 
 ```ruby
@@ -61,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:

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,6 +27,14 @@ 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?
@@ -60,6 +68,7 @@ module DynamicActiveModel
       # @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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require_relative '../database_arguments'
+
+module DynamicActiveModel
+  module Generators
+    # rails g dynamic_active_model:database NAME [--connection=NAME]
+    class DatabaseGenerator < ::Rails::Generators::Base
+      include DatabaseArguments
+
+      desc 'Declares another database in config/initializers/dynamic_active_model.rb ' \
+           '(e.g. cars => CarsDB in app/models/cars_db/).'
+
+      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))
+
+        raise Thor::Error, "#{INITIALIZER} not found; run rails g dynamic_active_model:install first"
+      end
+
+      def check_not_declared
+        raise Thor::Error, "#{definition.module_name} is already declared" if declared?
+      end
+
+      def add_database
+        inject_into_file INITIALIZER, "  #{add_database_line}\n", before: /^end\b/
+      end
+
+      def create_models_folder
+        create_extensions_folder
+      end
+
+      def check_connection
+        warn_about_missing_connection
+      end
+
+      private
+
+      # @return [Boolean] Whether the app already declares this namespace
+      def declared?
+        DynamicActiveModel::Rails.configuration.definitions.any? { |db| db.module_name == definition.module_name }
+      end
+    end
+  end
+end

data/lib/generators/dynamic_active_model/database_arguments.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module DynamicActiveModel
+  module Generators
+    # Shared --connection/--replica options and helpers for generators that declare a database
+    module DatabaseArguments
+      INITIALIZER = 'config/initializers/dynamic_active_model.rb'
+
+      def self.included(base)
+        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
+
+      # @return [DynamicActiveModel::Rails::DatabaseDefinition] Naming for the NAME argument
+      def definition
+        @definition ||= DynamicActiveModel::Rails::DatabaseDefinition.new(name)
+      end
+
+      # @return [String] e.g. "config.add_database :cars, :cars"
+      # @raise [Thor::Error] If --replica is given without --connection
+      def add_database_line
+        "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
+      # @return [void]
+      def create_extensions_folder
+        create_file File.join(definition.extensions_path(destination_root), '.keep')
+      end
+
+      # Warns when --connection or --replica names a database.yml entry the current environment lacks
+      # @return [void]
+      def warn_about_missing_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
+
+      # @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
+end

data/lib/generators/dynamic_active_model/extension/extension_generator.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module DynamicActiveModel
+  module Generators
+    # rails g dynamic_active_model:extension DATABASE TABLE
+    class ExtensionGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+      desc 'Creates an extension file for a table of a declared database ' \
+           '(e.g. grant_db users => app/models/grant_db/users.ext.rb).'
+
+      argument :database, type: :string, banner: 'DATABASE'
+      argument :table, type: :string, banner: 'TABLE'
+
+      def create_extension
+        template 'extension.rb.tt', File.join(definition.extensions_path(destination_root), file_name)
+      end
+
+      private
+
+      # The declared database named by DATABASE, as a name (grant_db) or namespace (GrantDB)
+      # @return [DynamicActiveModel::Rails::DatabaseDefinition]
+      # @raise [Thor::Error] If no such database is declared
+      def definition
+        @definition ||= declared.find { |db| [database, default_module_name].include?(db.module_name) } ||
+                        raise(Thor::Error, "no database #{database} is declared " \
+                                           "(declared: #{declared.map(&:module_name).join(', ')})")
+      end
+
+      # @return [Array<DynamicActiveModel::Rails::DatabaseDefinition>]
+      def declared
+        DynamicActiveModel::Rails.configuration.definitions
+      end
+
+      # @return [String] Namespace DATABASE maps to by default, e.g. "GrantDB"
+      def default_module_name
+        DynamicActiveModel::Rails::DatabaseDefinition.new(database).module_name
+      end
+
+      # @return [String] e.g. "users.ext.rb"
+      def file_name
+        "#{table}#{definition.extensions_suffix}"
+      end
+
+      # @return [String] e.g. "GrantDB::User"
+      def model_name
+        "#{definition.module_name}::#{definition.table_class_names[table] || table.classify}"
+      end
+    end
+  end
+end

data/lib/generators/dynamic_active_model/extension/templates/extension.rb.tt

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Extends <%= model_name %> (table <%= table %>). Columns and associations that
+# follow foreign key conventions are detected from the schema; add the rest here:
+# through/polymorphic associations, validations, scopes and methods.
+update_model do
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require_relative '../database_arguments'
+
+module DynamicActiveModel
+  module Generators
+    # rails g dynamic_active_model:install [NAME] [--connection=NAME]
+    class InstallGenerator < ::Rails::Generators::Base
+      include DatabaseArguments
+
+      source_root File.expand_path('templates', __dir__)
+      desc 'Creates config/initializers/dynamic_active_model.rb declaring a first database ' \
+           '(default: db, i.e. DB in app/models/db/).'
+
+      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
+
+      def create_models_folder
+        create_extensions_folder
+      end
+
+      def check_connection
+        warn_about_missing_connection
+      end
+    end
+  end
+end

data/lib/generators/dynamic_active_model/install/templates/dynamic_active_model.rb.tt

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Each database's tables become ActiveRecord models in a <Name>DB namespace. Models
+# are built on first use and rebuilt after code reloads and migrations. Per-table
+# extensions go in app/models/<name>_db/<table_name>.ext.rb.
+# https://github.com/dougyouch/dynamic-active-model/tree/master/dynamic-active-model-rails
+#
+# Add databases with bin/rails g dynamic_active_model:database NAME, or by hand:
+#   config.add_database :cars, :cars do |db|  # CarsDB, "cars" entry in database.yml
+#     db.skip_tables 'legacy_*'
+#   end
+DynamicActiveModel::Rails.configure do |config|
+  <%= add_database_line %>
+end
+
+# Setup that touches the models (e.g. has_paper_trail) belongs in a load hook,
+# which runs after every build of <%= definition.module_name %>'s models:
+# ActiveSupport.on_load(<%= definition.load_hook.inspect %>) do
+#   get_model!(:users).has_paper_trail
+# end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dynamic-active-model-rails
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Doug Youch
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.13.0
+        version: 0.15.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.13.0
+        version: 0.15.0
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
@@ -69,6 +69,12 @@ files:
 - lib/dynamic-active-model/rails/lazy_namespace.rb
 - lib/dynamic-active-model/rails/railtie.rb
 - lib/dynamic-active-model/rails/schema_change_hook.rb
+- lib/generators/dynamic_active_model/database/database_generator.rb
+- lib/generators/dynamic_active_model/database_arguments.rb
+- lib/generators/dynamic_active_model/extension/extension_generator.rb
+- lib/generators/dynamic_active_model/extension/templates/extension.rb.tt
+- lib/generators/dynamic_active_model/install/install_generator.rb
+- lib/generators/dynamic_active_model/install/templates/dynamic_active_model.rb.tt
 homepage: https://github.com/dougyouch/dynamic-active-model/tree/master/dynamic-active-model-rails
 licenses:
 - MIT