dynamic-active-model-rails 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff5e6fd6c5b29afc9e58143d52d5d43b39123423f1356fd4daa60cde68a5a5f1
-  data.tar.gz: c3909cdbe0d699072ece815f55372f482c8a10c3c436c44866e1f55c24e52f8d
+  metadata.gz: a8515d28d9394768614fb8cd2f4cf49173ab1d5f97c905debbf3f9dc85d21f21
+  data.tar.gz: 33388b8956cc6106da4d6d94d0255a15b66d6156be30a49cfa9c941f31f3ed4e
 SHA512:
-  metadata.gz: a27b214728591ccf5fe23094287bb2486d86aace729b4efb330a9d87948d9e5a42eca19966990c1a2afb5076a82282d5a48d475c6a8d90da7bf357db4fc75206
-  data.tar.gz: 58590282a387c2fd6c1f10434e30875c43831797567726dfed8526a3c0da7f82d38bcb9a9a4e84f365637999f4bea68f7509c70b554f51536c339833664a0c8f
+  metadata.gz: ed7b1653b8ea5643e50b797a0cad76714958d204052ee97ba44cd10eed2e3f2103e20bcad4c16ee7277a12886ef85cceb6421a8ca41c485dec72dbac67b89fc4
+  data.tar.gz: 42a9e8a11125f32d8e9ea403662e232d602595c776c7829a05f7759fd14f4c9fa88822100fd92dd52c2e2188fb39c1d95082eb62c0bef16f6f5c2c17ba13beed

data/README.md

@@ -26,6 +26,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 +49,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 +61,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
 
@@ -86,6 +90,19 @@ module CarsDB
 end
 ```
 
+## Load Hooks
+
+Configuration that touches models at boot, like `has_paper_trail`, must be reapplied whenever the models are rebuilt. After every build, the gem runs an ActiveSupport load hook named after the database's folder. The block runs with the `DynamicActiveModel::Database` as `self`:
+
+```ruby
+# config/initializers/paper_trail.rb
+ActiveSupport.on_load(:grant_db) do
+  %w[users organizations].each { |table| get_model!(table).has_paper_trail }
+end
+```
+
+Avoid `Rails.application.config.after_initialize { GrantDB.database... }`. It runs once, so models rebuilt after a reload or migration would lose that setup.
+
 ## Lifecycle
 
 - **Lazy loading.** Nothing touches the database at boot. The first reference to a constant in a namespace builds that database's models. That's why `db:create`, `db:migrate` and `assets:precompile` don't need models to exist.
@@ -108,6 +125,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
@@ -44,10 +57,20 @@ module DynamicActiveModel
         module_name.underscore
       end
 
+      # @return [Symbol] ActiveSupport load hook run after each build, e.g. :cars_db
+      def load_hook
+        folder.to_sym
+      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
@@ -57,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
@@ -76,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

@@ -6,6 +6,8 @@ module DynamicActiveModel
   module Rails
     # Builds one declared database's models on demand and tears them down again.
     # Loading is synchronized so concurrent first references build only once.
+    # After every build it runs the database's ActiveSupport load hook, so
+    # ActiveSupport.on_load(:cars_db) { ... } reapplies after reloads and migrations.
     class DatabaseLoader
       # @return [DatabaseDefinition]
       attr_reader :definition
@@ -41,13 +43,15 @@ module DynamicActiveModel
 
       private
 
-      # Creates models, relationships and extensions; undoes a partial build on error
+      # Creates models, relationships and extensions, then runs load hooks;
+      # undoes a partial build on error
       # @return [void]
       def build
         @database = new_database
         @database.create_models!
         Explorer.build_relationships!(@database, definition.relationships)
         load_extensions
+        ActiveSupport.run_load_hooks(definition.load_hook, @database)
       rescue StandardError
         reset!
         raise
@@ -57,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

metadata

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