dynamic-active-model-rails 0.11.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ff5e6fd6c5b29afc9e58143d52d5d43b39123423f1356fd4daa60cde68a5a5f1
+  data.tar.gz: c3909cdbe0d699072ece815f55372f482c8a10c3c436c44866e1f55c24e52f8d
+SHA512:
+  metadata.gz: a27b214728591ccf5fe23094287bb2486d86aace729b4efb330a9d87948d9e5a42eca19966990c1a2afb5076a82282d5a48d475c6a8d90da7bf357db4fc75206
+  data.tar.gz: 58590282a387c2fd6c1f10434e30875c43831797567726dfed8526a3c0da7f82d38bcb9a9a4e84f365637999f4bea68f7509c70b554f51536c339833664a0c8f

data/README.md

@@ -0,0 +1,120 @@
+# dynamic-active-model-rails
+
+Rails integration for [dynamic-active-model](https://github.com/dougyouch/dynamic-active-model). Declare your databases in one initializer, and their tables become ActiveRecord models in a `<Name>DB` namespace. Models are built on first use, rebuilt after migrations, and reloaded with the rest of the app in development.
+
+Requires Rails 7.1+ and Ruby 3.2+.
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'dynamic-active-model-rails'
+```
+
+`dynamic-active-model-rails` is released in lockstep with `dynamic-active-model` and pins the same version.
+
+## Configuration
+
+```ruby
+# config/initializers/dynamic_active_model.rb
+DynamicActiveModel::Rails.configure do |config|
+  # No connection: models subclass ApplicationRecord and share its connection pool
+  config.add_database :grant_db do |db|
+    db.skip_tables 'versions'
+  end
+
+  # 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.foreign_key :cars, :owner_id, :owner
+    db.table_class_name :status, 'StatusCode'
+  end
+end
+```
+
+```ruby
+GrantDB::User.find(1)
+CarsDB::Car.where(make: 'Honda')
+CarsDB.models # => [CarsDB::Car, CarsDB::Make, ...]
+```
+
+`schema_migrations` and `ar_internal_metadata` are always skipped.
+
+### Naming
+
+Namespaces always end in `DB`, so a database's namespace never collides with an application class:
+
+| Declaration | Namespace | Folder |
+|---|---|---|
+| `add_database :cars` | `CarsDB` | `app/models/cars_db/` |
+| `add_database :grant_db` | `GrantDB` | `app/models/grant_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.
+
+### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `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. |
+
+## Extending Models
+
+Add one `<table_name>.ext.rb` file per table to the database's folder:
+
+```ruby
+# app/models/cars_db/cars.ext.rb
+update_model do
+  scope :by_make, ->(name) { joins(:make).where(makes: { name: name }) }
+
+  def display_name
+    "#{make.name} #{model}"
+  end
+end
+```
+
+The autoloader ignores `.ext.rb` files. Other `.rb` files in the folder autoload into the namespace as usual, so you can keep related classes next to the models:
+
+```ruby
+# app/models/cars_db/search.rb
+module CarsDB
+  class Search
+    def self.for_make(name) = CarsDB::Car.by_make(name)
+  end
+end
+```
+
+## 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.
+- **Eager loading.** With `config.eager_load` (production), every database's models are built at boot, along with the rest of the app.
+- **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`.
+
+## 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`:
+
+```yaml
+development:
+  primary:
+    <<: *default
+    database: storage/development.sqlite3
+  cars:
+    <<: *default
+    database: storage/cars.sqlite3
+    migrations_paths: db/cars_migrate
+```
+
+## Development
+
+From this directory:
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+The specs boot a small Rails app in `spec/dummy` that has a primary and a `cars` SQLite database.

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+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.
+    class AutoloaderSetup
+      # @param autoloaders [Rails::Autoloaders]
+      # @param definition [DatabaseDefinition]
+      # @param root [Pathname, String] Application root
+      def initialize(autoloaders, definition, root)
+        @autoloaders = autoloaders
+        @definition = definition
+        @root = root
+      end
+
+      # Must run before the main autoloader is set up, i.e. from an initializer
+      # @return [void]
+      def apply
+        @autoloaders.main.inflector.inflect(@definition.folder => @definition.module_name)
+        @autoloaders.main.ignore(extension_glob)
+      end
+
+      private
+
+      # @return [String] Glob matching the database's extension files
+      def extension_glob
+        File.join(@definition.extensions_path(@root), '*.ext.rb')
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module DynamicActiveModel
+  module Rails
+    # Collects the databases declared in DynamicActiveModel::Rails.configure
+    class Configuration
+      # @return [Array<DatabaseDefinition>] Declared databases, in order
+      attr_reader :definitions
+
+      def initialize
+        @definitions = []
+      end
+
+      # Declares a database whose tables become models in a <Name>DB namespace
+      # @param name [Symbol, String] Database name, e.g. :cars => CarsDB, app/models/cars_db/
+      # @param connection [Symbol, String, Hash, nil] database.yml entry name, URL or
+      #   config hash; nil shares the parent class's connection
+      # @param ** [Hash] DatabaseDefinition options (module_name:, parent_class:)
+      # @yieldparam definition [DatabaseDefinition] For table-level settings
+      # @return [DatabaseDefinition]
+      # @raise [ArgumentError] If the namespace is already declared
+      def add_database(name, connection = nil, **)
+        definition = DatabaseDefinition.new(name, connection, **)
+        raise ArgumentError, "#{definition.module_name} is already declared" if declared?(definition.module_name)
+
+        yield definition if block_given?
+        @definitions << definition
+        definition
+      end
+
+      private
+
+      # @param module_name [String]
+      # @return [Boolean] Whether a database already uses the namespace
+      def declared?(module_name)
+        @definitions.any? { |definition| definition.module_name == module_name }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/string/inflections'
+
+module DynamicActiveModel
+  module Rails
+    # Settings for one declared database: its connection, namespace, folder and
+    # table-level options. Names always end in DB so a namespace never collides
+    # with an application class: :cars => CarsDB in app/models/cars_db/.
+    class DatabaseDefinition
+      # @return [Symbol, String, Hash, nil] Connection passed to establish_connection
+      attr_reader :connection
+
+      # @return [String] Name of the namespace module, e.g. "CarsDB"
+      attr_reader :module_name
+
+      # @return [String] Name of the base class's superclass, constantized at load time
+      attr_reader :parent_class_name
+
+      # @return [Array<String, Regexp>] Tables (or patterns) to skip
+      attr_reader :skipped_tables
+
+      # @return [Hash] Custom relationship names by table and foreign key
+      attr_reader :relationships
+
+      # @return [Hash] Custom class names by table name
+      attr_reader :table_class_names
+
+      # @param name [Symbol, String] Database name
+      # @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')
+        @connection = connection
+        @module_name = module_name || default_module_name(name)
+        @parent_class_name = parent_class.to_s
+        @skipped_tables = []
+        @relationships = {}
+        @table_class_names = {}
+      end
+
+      # @return [String] Folder under app/models for extensions, e.g. "cars_db"
+      def folder
+        module_name.underscore
+      end
+
+      # @param root [Pathname, String] Application root
+      # @return [String] Directory holding this database's .ext.rb files
+      def extensions_path(root)
+        File.join(root.to_s, 'app', 'models', folder)
+      end
+
+      # Skips tables; strings may use * wildcards
+      # @param tables [Array<String, Regexp>]
+      # @return [void]
+      def skip_tables(*tables)
+        @skipped_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
+      # @param relationship_name [String, Symbol]
+      # @return [void]
+      def foreign_key(table_name, foreign_key, relationship_name)
+        (@relationships[table_name.to_s] ||= {})[foreign_key.to_s] = relationship_name.to_s
+      end
+
+      # Overrides the model class name for a table
+      # @param table_name [String, Symbol]
+      # @param class_name [String]
+      # @return [void]
+      def table_class_name(table_name, class_name)
+        @table_class_names[table_name.to_s] = class_name.to_s
+      end
+
+      private
+
+      # :cars => "CarsDB", :grant_db => "GrantDB"
+      # @param name [Symbol, String]
+      # @return [String]
+      def default_module_name(name)
+        "#{name.to_s.underscore.delete_suffix('_db').camelize}DB"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'monitor'
+
+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.
+    class DatabaseLoader
+      # @return [DatabaseDefinition]
+      attr_reader :definition
+
+      # @param definition [DatabaseDefinition]
+      # @param root [Pathname, String] Application root, for the extensions folder
+      def initialize(definition, root)
+        @definition = definition
+        @root = root
+        @monitor = Monitor.new
+      end
+
+      # Builds the models unless already built
+      # @return [DynamicActiveModel::Database]
+      def load!
+        @monitor.synchronize { build unless @database }
+        @database
+      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
+      # @return [void]
+      def reset!
+        @monitor.synchronize do
+          @database&.reset!
+          @database = nil
+        end
+      end
+
+      private
+
+      # Creates models, relationships and extensions; undoes a partial build on error
+      # @return [void]
+      def build
+        @database = new_database
+        @database.create_models!
+        Explorer.build_relationships!(@database, definition.relationships)
+        load_extensions
+      rescue StandardError
+        reset!
+        raise
+      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|
+          definition.skipped_tables.each { |table| database.skip_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
+      # @return [void]
+      def load_extensions
+        path = definition.extensions_path(@root)
+        @database.update_all_models(path) if File.directory?(path)
+      end
+
+      # @return [Module] The namespace models are defined in
+      def namespace
+        Object.const_get(definition.module_name)
+      end
+
+      # @return [Class] The base class's superclass, resolved now so it can be reloaded
+      def parent_class
+        Object.const_get(definition.parent_class_name)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module DynamicActiveModel
+  module Rails
+    # Extended into a database's namespace module (e.g. CarsDB). The first
+    # reference to a missing constant builds the database's models.
+    module LazyNamespace
+      # @return [DatabaseLoader]
+      attr_accessor :dynamic_active_model_loader
+
+      # Defines (or reuses) a top-level namespace module and makes it lazy
+      # @param module_name [String]
+      # @param loader [DatabaseLoader]
+      # @return [Module]
+      def self.define(module_name, loader)
+        namespace =
+          if Object.const_defined?(module_name, false)
+            Object.const_get(module_name, false)
+          else
+            Object.const_set(module_name, Module.new)
+          end
+        namespace.extend(self)
+        namespace.dynamic_active_model_loader = loader
+        namespace
+      end
+
+      # @return [DynamicActiveModel::Database] The built database
+      def database
+        dynamic_active_model_loader.load!
+      end
+
+      # @return [Array<Class>] Every model in the namespace
+      def models
+        database.models
+      end
+
+      # Builds the models on first reference, then retries the lookup
+      # @param name [Symbol]
+      # @return [Object]
+      def const_missing(name)
+        return super if dynamic_active_model_loader.loaded?
+
+        dynamic_active_model_loader.load!
+        const_defined?(name, false) ? const_get(name, false) : super
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module DynamicActiveModel
+  module Rails
+    # Hooks declared databases into Rails: eager loading, code reloading and
+    # schema changes all rebuild models instead of leaving them stale.
+    class Railtie < ::Rails::Railtie
+      config.eager_load_namespaces << DynamicActiveModel::Rails
+
+      initializer 'dynamic_active_model.schema_change_hook' do
+        ActiveSupport.on_load(:active_record) { DynamicActiveModel::Rails::SchemaChangeHook.install }
+      end
+
+      initializer 'dynamic_active_model.reloader' do |app|
+        app.reloader.before_class_unload { DynamicActiveModel::Rails.reset! }
+        # a migration rewrites db/schema.rb (or structure.sql); reload so models rebuild
+        app.config.watchable_dirs[app.root.join('db').to_s] = %i[rb sql]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module DynamicActiveModel
+  module Rails
+    # Resets every database's models after migrations run or a schema is loaded,
+    # so models referenced later in the same process see the new schema. Covers
+    # db:migrate, db:rollback, db:prepare, db:schema:load and maintain_test_schema!.
+    module SchemaChangeHook
+      # Prepended to ActiveRecord::Migrator
+      module Migrator
+        def migrate
+          super
+        ensure
+          DynamicActiveModel::Rails.reset!
+        end
+
+        def run
+          super
+        ensure
+          DynamicActiveModel::Rails.reset!
+        end
+      end
+
+      # Prepended to ActiveRecord::Tasks::DatabaseTasks' singleton class
+      module DatabaseTasks
+        def load_schema(...)
+          super
+        ensure
+          DynamicActiveModel::Rails.reset!
+        end
+      end
+
+      # @return [void]
+      def self.install
+        ActiveRecord::Migrator.prepend(Migrator)
+        ActiveRecord::Tasks::DatabaseTasks.singleton_class.prepend(DatabaseTasks)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module DynamicActiveModel
+  # Rails integration for DynamicActiveModel. Declare each database once in an
+  # initializer; its models are built lazily on first reference, rebuilt after
+  # migrations, and reloaded with the rest of the app in development.
+  #
+  # @example config/initializers/dynamic_active_model.rb
+  #   DynamicActiveModel::Rails.configure do |config|
+  #     config.add_database :grant_db                # ApplicationRecord's connection
+  #     config.add_database :cars, :cars do |db|     # "cars" entry in database.yml
+  #       db.skip_tables 'legacy_*'
+  #     end
+  #   end
+  #
+  #   GrantDB::User.first
+  #   CarsDB::Car.where(make: 'Honda')
+  module Rails
+    autoload :AutoloaderSetup, 'dynamic-active-model/rails/autoloader_setup'
+    autoload :Configuration, 'dynamic-active-model/rails/configuration'
+    autoload :DatabaseDefinition, 'dynamic-active-model/rails/database_definition'
+    autoload :DatabaseLoader, 'dynamic-active-model/rails/database_loader'
+    autoload :LazyNamespace, 'dynamic-active-model/rails/lazy_namespace'
+    autoload :SchemaChangeHook, 'dynamic-active-model/rails/schema_change_hook'
+
+    class << self
+      # Declares databases. Each new database gets its namespace module and
+      # autoloader settings immediately, so call this from an initializer.
+      # @yieldparam config [Configuration]
+      # @return [Configuration]
+      def configure
+        yield configuration
+        configuration.definitions.each { |definition| register(definition) }
+        configuration
+      end
+
+      # @return [Configuration] The process-wide configuration
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      # @return [Array<DatabaseLoader>] A loader per declared database
+      def loaders
+        @loaders ||= []
+      end
+
+      # Builds every database's models. Rails calls this when eager loading.
+      # @return [void]
+      def eager_load!
+        loaders.each(&:load!)
+      end
+
+      # Forgets every database's models so they rebuild on next reference
+      # @return [void]
+      def reset!
+        loaders.each(&:reset!)
+      end
+
+      private
+
+      # Sets up the namespace and autoloader for a definition not seen before
+      # @param definition [DatabaseDefinition]
+      # @return [void]
+      def register(definition)
+        return if loaders.any? { |loader| loader.definition.equal?(definition) }
+
+        loader = DatabaseLoader.new(definition, ::Rails.root)
+        LazyNamespace.define(definition.module_name, loader)
+        AutoloaderSetup.new(::Rails.autoloaders, definition, ::Rails.root).apply
+        loaders << loader
+      end
+    end
+  end
+end

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

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'rails'
+require 'dynamic-active-model'
+require 'dynamic-active-model/rails'
+require 'dynamic-active-model/rails/railtie'

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: dynamic-active-model-rails
+version: !ruby/object:Gem::Version
+  version: 0.11.0
+platform: ruby
+authors:
+- Doug Youch
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: dynamic-active-model
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.11.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.11.0
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: 'Railtie for dynamic-active-model: declare databases in one initializer
+  and get lazily built, reloadable models in CarsDB-style namespaces, with extension
+  files in app/models/cars_db/ and automatic rebuilds after migrations.'
+email: dougyouch@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/dynamic-active-model-rails.rb
+- lib/dynamic-active-model/rails.rb
+- lib/dynamic-active-model/rails/autoloader_setup.rb
+- lib/dynamic-active-model/rails/configuration.rb
+- lib/dynamic-active-model/rails/database_definition.rb
+- lib/dynamic-active-model/rails/database_loader.rb
+- lib/dynamic-active-model/rails/lazy_namespace.rb
+- lib/dynamic-active-model/rails/railtie.rb
+- lib/dynamic-active-model/rails/schema_change_hook.rb
+homepage: https://github.com/dougyouch/dynamic-active-model/tree/master/dynamic-active-model-rails
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Rails integration for dynamic-active-model
+test_files: []