automodel-sqlserver 0.1.0

data/lib/automodel.rb

@@ -0,0 +1,132 @@
+require 'active_record'
+require 'active_support/all'
+require 'securerandom'
+
+require 'automodel/automodel'
+require 'automodel/connectors'
+require 'automodel/helpers'
+require 'automodel/version'
+
+## The main (really *only*) entrypoint for the **automodel-sqlserver** gem. This is the method the
+## end-user calls to trigger a database scrape and model generation.
+##
+##
+## @param spec [Symbol, String, Hash]
+##   The Symbol/String/Hash to pass through to the ActiveRecord connection resolver, as detailed in
+##   [ActiveRecord::ConnectionHandling#establish_connection](http://bit.ly/2JQdA8c). Whether the
+##   given "spec" value is a Hash or is a Symbol/String to run through the ActiveRecord resolver,
+##   the resulting Hash may include the following options (in addition to the actual connection
+##   parameters).
+##
+## @option spec [String] :subschema
+##   The name of an additional namespace with which tables in the target database are prefixed.
+##   Intended for use with SQL Server, where a table's fully-qualified name may have an additional
+##   level of namespacing between the database name and the base table name (e.g.
+##   `database.dbo.table`, in which case the subschema would be `"dbo"`).
+##
+## @option spec [String] :namespace
+##   A String representing the desired namespace for the generated model classes (e.g. `"NewDB"` or
+##   `"WeirdDB::Models"`). If not given, the generated models will fall under `Kernel` so they are
+##   always available without namespacing, like standard user-defined model classes.
+##
+##
+## @raise [Automodel::ModelNameCollisionError]
+##
+## @return [ActiveRecord::Base]
+##   The returned value is an instance of an ActiveRecord::Base subclass. This is the class that
+##   serves as superclass to all of the generated model classes, so that a list of all models can be
+##   easily compiled by calling `#subclasses` on this value.
+##
+def automodel(spec)
+  ## Build out a connection spec Hash from the given value.
+  ##
+  resolver = ActiveRecord::ConnectionAdapters::ConnectionSpecification::Resolver
+  connection_spec = resolver.new(ActiveRecord::Base.configurations).resolve(spec).symbolize_keys
+
+  ## We need a base class for all of the models we're about to create, but don't want to pollute
+  ## ActiveRecord::Base's own connection pool, so we'll need a subclass. This will serve as both
+  ## our base class for new models and as the connection pool handler. We're defining it with names
+  ## that reflect both uses just to keep the code more legible.
+  ##
+  connection_handler_name = "CH_#{SecureRandom.uuid.delete('-')}"
+  base_class_for_new_models = connection_handler = Class.new(ActiveRecord::Base)
+  Automodel::Helpers.register_class(connection_handler, as: connection_handler_name,
+                                                        within: :'Automodel::Connectors')
+
+  ## Establish a connection with the given params.
+  ##
+  connection_handler.establish_connection(connection_spec)
+
+  ## Map out the table structures.
+  ##
+  tables = Automodel::Helpers.map_tables(connection_handler, subschema: connection_spec[:subschema])
+
+  ## Safeguard against class name collisions.
+  ##
+  defined_names = Array((connection_spec[:namespace] || :Kernel).to_s.safe_constantize&.constants)
+  potential_names = tables.map { |table| table[:model_name].to_sym }
+  name_collisions = defined_names & potential_names
+  if name_collisions.present?
+    connection_handler.connection_pool.disconnect!
+    Automodel::Connectors.send(:remove_const, connection_handler_name)
+    raise Automodel::NameCollisionError, name_collisions
+  end
+
+  ## Define the table models.
+  ##
+  tables.each do |table|
+    table[:model] = Class.new(base_class_for_new_models) do
+      ## We can't assume table properties confom to any standard.
+      ##
+      self.table_name = table[:name]
+      self.primary_key = table[:primary_key]
+
+      ## Don't allow `#find` for tables with a composite primary key.
+      ##
+      def find(*args)
+        raise Automodel::FindOnCompoundPrimaryKeyError if table[:composite_primary_key]
+        super
+      end
+
+      ## Create railsy column name aliases whenever possible.
+      ##
+      table[:columns].each do |column|
+        railsy_name = Automodel::Helpers.railsy_column_name(column)
+        unless table[:column_aliases].key? railsy_name
+          table[:column_aliases][railsy_name] = column
+          alias_attribute(railsy_name, column.name)
+        end
+      end
+    end
+
+    ## Register the model class.
+    ##
+    Automodel::Helpers.register_class(table[:model], as: table[:model_name],
+                                                     within: connection_spec[:namespace])
+  end
+
+  ## With all models registered, we can safely declare relationships.
+  ##
+  tables.map { |table| table[:foreign_keys] }.flatten.each do |fk|
+    from_table = tables.find { |table| table[:base_name] == fk.from_table.delete('"') }
+    next unless from_table.present?
+
+    to_table = tables.find { |table| table[:base_name] == fk.to_table.delete('"') }
+    next unless to_table.present?
+
+    association_setup = <<~END_OF_HEREDOC
+      belongs_to #{to_table[:base_name].to_sym.inspect},
+                 class_name: #{to_table[:model].to_s.inspect},
+                 primary_key: #{fk.options[:primary_key].to_sym.inspect},
+                 foreign_key: #{fk.options[:column].to_sym.inspect}
+
+      alias #{to_table[:model_name].underscore.to_sym.inspect} #{to_table[:base_name].to_sym.inspect}
+    END_OF_HEREDOC
+    from_table[:model].class_eval(association_setup, __FILE__, __LINE__)
+  end
+
+  ## There's no obvious value we can return that would be of any use, except maybe the base class,
+  ## in case the end user wants to procure a list of all the models (via `#subclasses`).
+  ##
+  base_class_for_new_models
+end

data/lib/automodel/automodel.rb

@@ -0,0 +1,4 @@
+## The root module for the **automodel-sqlserver** gem.
+##
+module Automodel
+end

data/lib/automodel/connectors.rb

@@ -0,0 +1,8 @@
+require 'automodel/automodel'
+
+module Automodel
+  ## The module within which all {::automodel}-generated connection handlers are registered.
+  ##
+  module Connectors
+  end
+end

data/lib/automodel/errors.rb

@@ -0,0 +1,24 @@
+require 'automodel/automodel'
+
+module Automodel
+  ## The base Error class for all **automodel-sqlserver** gem issues.
+  ##
+  class Error < ::StandardError
+  end
+
+  ## An error resulting from an attempt to register the same adapter name with
+  ## {Automodel::SchemaInspector.register_adapter} multiple times.
+  ##
+  class AdapterAlreadyRegisteredError < Error
+  end
+
+  ## An error resulting from an aborted Automodel due to a class name collision.
+  ##
+  class NameCollisionError < Error
+  end
+
+  ## An error resulting from calling `#find` on a table with a compound primary key.
+  ##
+  class FindOnCompoundPrimaryKeyError < Error
+  end
+end

data/lib/automodel/helpers.rb

@@ -0,0 +1,141 @@
+require 'automodel/automodel'
+require 'automodel/schema_inspector'
+
+module Automodel
+  ## Houses some helper methods used directly by {::automodel}.
+  ##
+  module Helpers
+    class << self
+      ## Takes a connection handler (an object that implements ActiveRecord::ConnectionHandling),
+      ## scrapes the target database, and returns a list of the tables' metadata.
+      ##
+      ##
+      ## @param connection_handler [ActiveRecord::ConnectionHandling]
+      ##   The connection pool/handler to inspect and map out.
+      ##
+      ## @param subschema [String]
+      ##   The name of an additional namespace with which tables in the target database are
+      ##   prefixed, as eplained in {::automodel}.
+      ##
+      ##
+      ## @return [Array<Hash>]
+      ##   An Array where each value is a Hash representing a table in the target database. Each
+      ##   such Hash will define the following keys:
+      ##
+      ##   - `:name` (String) -- The table name, prefixed with the subschema name (if one is given).
+      ##   - `:columns` (Array<ActiveRecord::ConnectionAdapters::Column>)
+      ##   - `:primary_key` (String, Array<String>)
+      ##   - `:foreign_keys` (Array<ActiveRecord::ConnectionAdapters::ForeignKeyDefinition>)
+      ##   - `:base_name` (String) -- The table name, with no subschema.
+      ##   - `:model_name` (String) -- A Railsy class name for the corresponding model.
+      ##   - `:composite_primary_key` (true, false)
+      ##   - `:column_aliases` (Hash<String, ActiveRecord::ConnectionAdapters::Column>)
+      ##
+      def map_tables(connection_handler, subschema: '')
+        ## Normalize the "subschema" name.
+        ##
+        subschema = "#{subschema}.".sub(%r{\.+$}, '.').sub(%r{^\.}, '')
+
+        ## Prep the Automodel::SchemaInspector we'll be using.
+        ##
+        schema_inspector = Automodel::SchemaInspector.new(connection_handler)
+
+        ## Get as much metadata as possible out of the Automodel::SchemaInspector.
+        ##
+        schema_inspector.tables.map do |table_name|
+          table = {}
+
+          table[:name] = "#{subschema}#{table_name}"
+          table[:columns] = schema_inspector.columns(table[:name])
+          table[:primary_key] = schema_inspector.primary_key(table[:name])
+          table[:foreign_keys] = schema_inspector.foreign_keys(table[:name])
+
+          table[:base_name] = table[:name].split('.').last
+          table[:model_name] = table[:base_name].underscore.classify
+          table[:composite_primary_key] = table[:primary_key].is_a? Array
+          table[:column_aliases] = table[:columns].map { |column| [column.name, column] }.to_h
+
+          table
+        end
+      end
+
+      ## Returns a Railsy name for the given column.
+      ##
+      ##
+      ## @param column [ActiveRecord::ConnectionAdapters::Column]
+      ##   The column for which we want to generate a Railsy name.
+      ##
+      ##
+      ## @return [String]
+      ##   The given column's name, in Railsy form.
+      ##
+      ##   Note Date/Datetime columns are not suffixed with "_on" or "_at" per Rails norm, as this
+      ##   can work against you sometimes ("BirthDate" turns into "birth_on"). A future release will
+      ##   address this by building out a comprehensive list of such names and their correct Railsy
+      ##   representation, but that is not currently the case.
+      ##
+      def railsy_column_name(column)
+        name = railsy_name(column.name)
+        name = name.sub(%r{^is_}, '') if column.type == :boolean
+
+        name
+      end
+
+      ## Returns the given name in Railsy form.
+      ##
+      ##
+      ## @param name [String, Symbol]
+      ##   The column name for which we want to generate a Railsy name.
+      ##
+      ##
+      ## @return [String]
+      ##   The given name, in Railsy form.
+      ##
+      def railsy_name(name)
+        name.to_s.gsub(%r{[^a-z0-9]+}i, '_').underscore
+      end
+
+      ## Registers the given class **as** the given name and **within** the given namespace (if any).
+      ##
+      ##
+      ## @param class_object [Class]
+      ##   The class to register.
+      ##
+      ## @param as [String]
+      ##   The name with which to register the class. Note this should be a base name (no "::").
+      ##
+      ## @param within [String, Symbol, Module, Class]
+      ##   The module/class under which the given class should be registered. If the named module or
+      ##   class does not exist, as many nested modules as needed are declared so the class can be
+      ##   registered as requested.
+      ##
+      ##   e.g. Calling this method with an "as" value of `"Sample"` and a "within" value of
+      ##        `"Many::Levels::Deep"` will: check for module/class "Many" and create one as a
+      ##        Module if it doesn't already exist; then check for a module/class "Many::Levels" and
+      ##        create a "Levels" Module within `Many` if it doesn't already exist; then check for a
+      ##        module/class "Many::Levels::Deep" and create a "Deep" Module within `Many::Levels`
+      ##        if it doesn't already exist; and finally register the given class as "Sample" within
+      ##        `Many::Levels::Deep`.
+      ##
+      ##
+      ## @return [Class]
+      ##   The newly-registered class (the same value as the originally-submitted "class_object").
+      ##
+      def register_class(class_object, as:, within: nil)
+        components = within.to_s.split('::').compact.map(&:to_sym)
+        components.unshift(:Kernel) unless components.first.to_s.safe_constantize.present?
+
+        namespace = components.shift.to_s.constantize
+        components.each do |component|
+          namespace = if component.in? namespace.constants
+                        namespace.const_get(component)
+                      else
+                        namespace.const_set(component, Module.new)
+                      end
+        end
+
+        namespace.const_set(as, class_object)
+      end
+    end
+  end
+end

data/lib/automodel/schema_inspector.rb

@@ -0,0 +1,218 @@
+require 'active_support/all'
+require 'securerandom'
+
+require 'automodel/automodel'
+require 'automodel/errors'
+
+module Automodel
+  ## A utility object that issues the actual database inspection commands and returns the table,
+  ## column, primary-key, and foreign-key data.
+  ##
+  class SchemaInspector
+    ## rubocop:disable all
+
+    ## Class-Instance variable: `known_adapters` is a Hash of adapters registered via
+    ## {Automodel::SchemaInspector.register_adapter}.
+    ##
+    @known_adapters = {}
+    def self.known_adapters; @known_adapters; end
+    def known_adapters; self.class.known_adapters; end
+    ## rubocop:enable all
+
+    ## "Registers" an adapter with the Automodel::SchemaInspector. This allows for alternate
+    ## mechanisms of procuring lists of tables, columns, primary keys, and/or foreign keys from an
+    ## adapter that may not itself support `#tables`/`#columns`/`#primary_key`/`#foreign_keys`.
+    ##
+    ##
+    ## @param adapter [String, Symbol]
+    ##   The "adapter" value used to match that given in the connection spec. It is with this value
+    ##   that the adapter being registered is matched to an existing database pool/connection.
+    ##
+    ## @param tables [Proc]
+    ##   The Proc to `#call` to request a list of table names. The Proc will be called with one
+    ##   parameter: a database connection.
+    ##
+    ## @param columns [Proc]
+    ##   The Proc to `#call` to request a list of columns for a specific table. The Proc will be
+    ##   called with two parameters: a database connection and a table name.
+    ##
+    ## @param primary_key [Proc]
+    ##   The Proc to `#call` to request the primary key for a specific table. The Proc will be
+    ##   called with two parameters: a database connection and a table name.
+    ##
+    ## @param foreign_keys [Proc]
+    ##   The Proc to `#call` to request a list of foreign keys for a specific table. The Proc will
+    ##   be called with two parameters: a database connection and a table name.
+    ##
+    ##
+    ## @raise [Automodel::AdapterAlreadyRegisteredError]
+    ##
+    def self.register_adapter(adapter:, tables:, columns:, primary_key:, foreign_keys: nil)
+      adapter = adapter.to_sym.downcase
+      raise Automodel::AdapterAlreadyRegisteredError, adapter if known_adapters.key? adapter
+
+      known_adapters[adapter] = { tables: tables,
+                                  columns: columns,
+                                  primary_key: primary_key,
+                                  foreign_keys: foreign_keys }
+    end
+
+    ## @param connection_handler [ActiveRecord::ConnectionHandling]
+    ##   The connection pool/handler (an object that implements ActiveRecord::ConnectionHandling) to
+    ##   inspect and map out.
+    ##
+    def initialize(connection_handler)
+      @connection = connection_handler.connection
+      adapter = connection_handler.connection_pool.spec.config[:adapter]
+
+      @registration = known_adapters[adapter.to_sym] || {}
+    end
+
+    ## Returns a list of table names in the target database.
+    ##
+    ## If a matching Automodel::SchemaInspector registration is found for the connection's adapter,
+    ## and that registration specified a `:tables` Proc, the Proc is called. Otherwise, the standard
+    ## connection `#tables` is returned.
+    ##
+    ##
+    ## @return [Array<String>]
+    ##
+    def tables
+      @tables ||= if @registration[:tables].present?
+                    @registration[:tables].call(@connection)
+                  else
+                    @connection.tables
+                  end
+    end
+
+    ## Returns a list of columns for the given table.
+    ##
+    ## If a matching Automodel::SchemaInspector registration is found for the connection's adapter,
+    ## and that registration specified a `:columns` Proc, the Proc is called. Otherwise, the
+    ## standard connection `#columns` is returned.
+    ##
+    ##
+    ## @param table_name [String]
+    ##   The table whose columns should be fetched.
+    ##
+    ##
+    ## @return [Array<ActiveRecord::ConnectionAdapters::Column>]
+    ##
+    def columns(table_name)
+      table_name = table_name.to_s
+
+      @columns ||= {}
+      @columns[table_name] ||= if @registration[:columns].present?
+                                 @registration[:columns].call(@connection, table_name)
+                               else
+                                 @connection.columns(table_name)
+                               end
+    end
+
+    ## Returns the primary key for the given table.
+    ##
+    ## If a matching Automodel::SchemaInspector registration is found for the connection's adapter,
+    ## and that registration specified a `:primary_key` Proc, the Proc is called. Otherwise, the
+    ## standard connection `#primary_key` is returned.
+    ##
+    ##
+    ## @param table_name [String]
+    ##   The table whose primary key should be fetched.
+    ##
+    ##
+    ## @return [String, Array<String>]
+    ##
+    def primary_key(table_name)
+      table_name = table_name.to_s
+
+      @primary_keys ||= {}
+      @primary_keys[table_name] ||= if @registration[:primary_key].present?
+                                      @registration[:primary_key].call(@connection, table_name)
+                                    else
+                                      @connection.primary_key(table_name)
+                                    end
+    end
+
+    ## Returns a list of foreign keys for the given table.
+    ##
+    ## If a matching Automodel::SchemaInspector registration is found for the connection's adapter,
+    ## and that registration specified a `:foreign_keys` Proc, the Proc is called. Otherwise, the
+    ## standard connection `#foreign_keys` is attempted. If that call to ``#foreign_keys` raises a
+    ## ::NoMethodError or ::NotImplementedError, a best-effort attempt is made to build a list of
+    ## foreign keys based on table and column names.
+    ##
+    ##
+    ## @param table_name [String]
+    ##   The table whose foreign keys should be fetched.
+    ##
+    ##
+    ## @return [Array<ActiveRecord::ConnectionAdapters::ForeignKeyDefinition>]
+    ##
+    def foreign_keys(table_name)
+      table_name = table_name.to_s
+
+      @foreign_keys ||= {}
+      @foreign_keys[table_name] ||= begin
+        if @registration[:foreign_keys].present?
+          @registration[:foreign_keys].call(@connection, table_name)
+        else
+          begin
+            @connection.foreign_keys(table_name)
+          rescue ::NoMethodError, ::NotImplementedError
+            ## Not all ActiveRecord adapters support `#foreign_keys`. When this happens, we'll make
+            ## a best-effort attempt to intuit relationships from the table and column names.
+            ##
+            columns(table_name).map do |column|
+              id_pattern = %r{(?:_id|Id)$}
+              next unless column.name =~ id_pattern
+
+              target_table = column.name.sub(id_pattern, '')
+              next unless target_table.in? tables
+
+              target_column = primary_key(qualified_name(target_table, context: table_name))
+              next unless target_column.in? ['id', 'Id', 'ID', column.name]
+
+              ActiveRecord::ConnectionAdapters::ForeignKeyDefinition.new(
+                table_name.split('.').last,
+                target_table,
+                name: "FK_#{SecureRandom.uuid.delete('-')}",
+                column:  column.name,
+                primary_key: target_column,
+                on_update: nil,
+                on_delete: nil
+              )
+            end.compact
+          end
+        end
+      end
+    end
+
+    private
+
+    ## Returns a qualified table name.
+    ##
+    ##
+    ## @param table_name [String]
+    ##   The name to qualify.
+    ##
+    ## @param context [String]
+    ##   The name of an existing table from whose namespace we want to be able to reach the first
+    ##   table.
+    ##
+    ##
+    ## @return [String]
+    ##
+    def qualified(table_name, context:)
+      return table_name if table_name['.'].present?
+      return table_name if context['.'].blank?
+
+      "#{context.sub(%r{[^.]*$}, '')}#{table_name}"
+    end
+
+    ## Returns an unqualified table name.
+    ##
+    def unqualified(table_name)
+      table_name.split('.').last
+    end
+  end
+end