dynamic-active-model-rails 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aade59eb21651ddf7c6c7f50de964e3d3e1e6809e82e9d832cb05cfe6917df65
-  data.tar.gz: a0a3e87f460a462d3096193fdb4b2c405799903bf347c74944ce83b258c76afb
+  metadata.gz: e99654c467d82a550320a4952955c2ac035a218940ba178f4aab57ea6036c438
+  data.tar.gz: fc7f43e364ced45bd2d52e0ea918ae4498ea690d3414a1c830c20f03495dc836
 SHA512:
-  metadata.gz: 562618b697479ecfcd9aff7cd04c8e9e40488064925dba63d76828ea5255c337355d0272d8e666d2f69b2b8e22f0fc5a67ffee86153075501ee34aab18b52de1
-  data.tar.gz: eb5fe6bbd793f081d53f2dfd5826226ffc10806a3e6afb922e9eeffc49f1f391b2009246049f72506b27d38b3982ebbb79ab4d193be0567958c42738e1b5a91f
+  metadata.gz: edd5f4bacf38a6a2e3fa610da7f6fe4aa01e781d7675feeb39164e97085842fbdaeb85d6ba8bc027b09672a58adaec9f875db1cdf352868a5c91b38ecece64cb
+  data.tar.gz: 6e5616c8bb2b5ca5c3fc7868f51d6b22b9c40ec0bfb6fd3d8c9942e57fc321eb7c445b1a09628416c71aee958b0c926c2cf7ca2239cce482fa9f5de48b5fcbbf

data/README.md

@@ -13,6 +13,21 @@ 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: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. The generators warn if the current environment has no such entry. Without `--connection`, the database shares `ApplicationRecord`'s connection.
+
 ## Configuration
 
 ```ruby
@@ -26,6 +41,7 @@ DynamicActiveModel::Rails.configure do |config|
   # A Symbol names a database.yml entry; a URL string or config hash also works
   config.add_database :cars, :cars do |db|
     db.skip_tables 'legacy_*', /^tmp_/
+    db.include_tables 'cars', 'makes', 'owner*'   # whitelist; default is every table
     db.foreign_key :cars, :owner_id, :owner
     db.table_class_name :status, 'StatusCode'
   end
@@ -48,6 +64,7 @@ Namespaces always end in `DB`, so a database's namespace never collides with an
 |---|---|---|
 | `add_database :cars` | `CarsDB` | `app/models/cars_db/` |
 | `add_database :grant_db` | `GrantDB` | `app/models/grant_db/` |
+| `add_database :db` | `DB` | `app/models/db/` |
 | `add_database :cars, module_name: 'Inventory'` | `Inventory` | `app/models/inventory/` |
 
 The `cars_db` → `CarsDB` mapping is registered with the Rails autoloader only, not with the global inflector, so `'cars_db'.camelize` elsewhere in your app is unaffected.
@@ -59,6 +76,8 @@ 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. |
+| `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. |
 
 ## Extending Models
 
@@ -121,6 +140,37 @@ development:
     migrations_paths: db/cars_migrate
 ```
 
+## Migrating from the Setup DSL
+
+If your app followed the core gem's [manual setup](../docs/manual-rails-setup.md):
+
+1. Replace `gem 'dynamic-active-model'` with `gem 'dynamic-active-model-rails'`.
+2. Delete `app/models/db.rb`. Move its settings into an initializer:
+
+   ```ruby
+   # config/initializers/dynamic_active_model.rb
+   DynamicActiveModel::Rails.configure do |config|
+     config.add_database :db do |db|      # DB, app/models/db/
+       db.skip_tables 'versions'
+     end
+   end
+   ```
+
+   | Setup DSL | Rails gem |
+   |---|---|
+   | `parent_class ApplicationRecord` | default (omit) |
+   | `connection_options 'secondary'` | `add_database :db, :secondary` |
+   | `extensions_path '...'` | default for `app/models/db/`; otherwise `extensions_path:` |
+   | `extensions_suffix '.x.rb'` | `extensions_suffix:` |
+   | `skip_tables [...]` / `skip_table` | `db.skip_tables` |
+   | `foreign_key t, col, name` | `db.foreign_key t, col, name` |
+   | `table_class_name t, name` | `db.table_class_name t, name` |
+
+3. Remove the `DB` inflection and the `app/models/db` ignore from `config/application.rb`. The gem registers both.
+4. Move setup that ran after `create_models!` into `ActiveSupport.on_load(:db) { ... }`.
+
+`.ext.rb` files stay where they are.
+
 ## Development
 
 From this directory:

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

@@ -3,8 +3,8 @@
 module DynamicActiveModel
   module Rails
     # Teaches the Rails autoloader about a database's folder: cars_db/ maps to
-    # CarsDB (only in Zeitwerk, not the global inflector), and .ext.rb files are
-    # left to DynamicActiveModel instead of being autoloaded.
+    # CarsDB (only in Zeitwerk, not the global inflector), and extension files
+    # (*.ext.rb by default) are left to DynamicActiveModel instead of being autoloaded.
     class AutoloaderSetup
       # @param autoloaders [Rails::Autoloaders]
       # @param definition [DatabaseDefinition]
@@ -26,7 +26,7 @@ module DynamicActiveModel
 
       # @return [String] Glob matching the database's extension files
       def extension_glob
-        File.join(@definition.extensions_path(@root), '*.ext.rb')
+        File.join(@definition.extensions_path(@root), "*#{@definition.extensions_suffix}")
       end
     end
   end

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

@@ -20,6 +20,12 @@ module DynamicActiveModel
       # @return [Array<String, Regexp>] Tables (or patterns) to skip
       attr_reader :skipped_tables
 
+      # @return [Array<String, Regexp>] Tables (or patterns) to model; empty means all
+      attr_reader :included_tables
+
+      # @return [String] File suffix of extension files
+      attr_reader :extensions_suffix
+
       # @return [Hash] Custom relationship names by table and foreign key
       attr_reader :relationships
 
@@ -30,11 +36,18 @@ module DynamicActiveModel
       # @param connection [Symbol, String, Hash, nil] See Configuration#add_database
       # @param module_name [String, nil] Namespace override, e.g. "Inventory"
       # @param parent_class [String] Superclass for the generated base class
-      def initialize(name, connection = nil, module_name: nil, parent_class: 'ApplicationRecord')
+      # @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
+      def initialize(name, connection = nil, module_name: nil, parent_class: 'ApplicationRecord',
+                     extensions_path: nil, extensions_suffix: '.ext.rb')
         @connection = connection
         @module_name = module_name || default_module_name(name)
         @parent_class_name = parent_class.to_s
+        @extensions_path = extensions_path&.to_s
+        @extensions_suffix = extensions_suffix
         @skipped_tables = []
+        @included_tables = []
         @relationships = {}
         @table_class_names = {}
       end
@@ -50,9 +63,14 @@ module DynamicActiveModel
       end
 
       # @param root [Pathname, String] Application root
-      # @return [String] Directory holding this database's .ext.rb files
+      # @return [String] Absolute directory holding this database's extension files
       def extensions_path(root)
-        File.join(root.to_s, 'app', 'models', folder)
+        File.expand_path(@extensions_path || File.join('app', 'models', folder), root.to_s)
+      end
+
+      # @return [Boolean] Whether extensions_path was configured, so it must exist
+      def custom_extensions_path?
+        !@extensions_path.nil?
       end
 
       # Skips tables; strings may use * wildcards
@@ -62,6 +80,14 @@ module DynamicActiveModel
         @skipped_tables.concat(tables.flatten)
       end
 
+      # Models only these tables; strings may use * wildcards. ActiveRecord's
+      # internal tables still need their exact name.
+      # @param tables [Array<String, Regexp>]
+      # @return [void]
+      def include_tables(*tables)
+        @included_tables.concat(tables.flatten)
+      end
+
       # Names the relationship for a foreign key column
       # @param table_name [String, Symbol]
       # @param foreign_key [String, Symbol] Column name
@@ -81,11 +107,11 @@ module DynamicActiveModel
 
       private
 
-      # :cars => "CarsDB", :grant_db => "GrantDB"
+      # :cars => "CarsDB", :grant_db => "GrantDB", :db => "DB"
       # @param name [Symbol, String]
       # @return [String]
       def default_module_name(name)
-        "#{name.to_s.underscore.delete_suffix('_db').camelize}DB"
+        "#{name.to_s.underscore.sub(/(?:\A|_)db\z/, '').camelize}DB"
       end
     end
   end

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

@@ -61,15 +61,22 @@ module DynamicActiveModel
       def new_database
         Database.new(namespace, definition.connection, parent_class: parent_class).tap do |database|
           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) }
         end
       end
 
-      # Applies the .ext.rb files in the database's models folder
+      # Applies the database's extension files. The default folder is optional;
+      # a configured extensions_path must exist.
       # @return [void]
+      # @raise [DynamicActiveModel::Error] If a configured extensions_path is missing
       def load_extensions
         path = definition.extensions_path(@root)
-        @database.update_all_models(path) if File.directory?(path)
+        if File.directory?(path)
+          @database.update_all_models(path, definition.extensions_suffix)
+        elsif definition.custom_extensions_path?
+          raise DynamicActiveModel::Error, "extensions_path #{path} for #{definition.module_name} does not exist"
+        end
       end
 
       # @return [Module] The namespace models are defined in

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

@@ -0,0 +1,47 @@
+# 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_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,45 @@
+# frozen_string_literal: true
+
+module DynamicActiveModel
+  module Generators
+    # Shared --connection option 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)"
+      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"
+      def add_database_line
+        args = [name.underscore.to_sym.inspect]
+        args << options[:connection].to_sym.inspect if options[:connection]
+        "config.add_database #{args.join(', ')}"
+      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 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])
+
+        say_status :warning, "config/database.yml has no #{options[:connection]} entry for #{::Rails.env}", :yellow
+      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,31 @@
+# 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 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.12.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Doug Youch
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: 0.14.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: 0.14.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