sequelizer 0.1.4 → 0.1.6

data/lib/sequel/extensions/usable.rb

@@ -1,15 +1,44 @@
 module Sequel
+
+  # = Usable
+  #
+  # Sequel extension that provides a convenient +use+ method for switching
+  # the current database/schema context. This is particularly useful for
+  # databases that support the USE statement like MySQL, SQL Server, and
+  # some big data engines.
+  #
+  # @example
+  #   db.extension :usable
+  #   db.use(:my_schema)
+  #   # Executes: USE `my_schema`
   module Usable
+
+    # Switches to the specified database or schema.
+    #
+    # Executes a USE statement to change the current database context.
+    # The schema name is properly quoted using the database's identifier
+    # quoting rules.
+    #
+    # @param schema_name [Symbol, String] the name of the schema/database to use
+    # @example
+    #   db.use(:production_db)
+    #   db.use('test_schema')
     def use(schema_name)
       run(use_sql(schema_name))
     end
 
     private
 
+    # Generates the USE SQL statement for the given schema name.
+    #
+    # @param schema_name [Symbol, String] the schema name to use
+    # @return [String] the USE SQL statement
     def use_sql(schema_name)
-      "USE #{quote_identifier(schema_name)}"
+      "USE #{literal(schema_name)}"
     end
+
   end
 
   Database.register_extension(:usable, Usable)
+
 end

data/lib/sequelizer/cli.rb

@@ -3,39 +3,75 @@ require 'pp'
 require_relative 'gemfile_modifier'
 
 module Sequelizer
+  # = CLI
+  #
+  # Command line interface for Sequelizer gem using Thor.
+  # Provides commands for:
+  #
+  # * Updating Gemfile with database adapters
+  # * Initializing .env files with database configuration
+  # * Displaying current configuration
+  #
+  # @example
+  #   sequelizer update_gemfile
+  #   sequelizer init_env --adapter postgres --host localhost
+  #   sequelizer config
   class CLI < Thor
-    desc 'update_gemfile', 'adds or replaces a line in your Gemfile to include the correct database adapter to work with Sequel'
+
+    desc 'update_gemfile',
+         'adds or replaces a line in your Gemfile to include the correct database adapter to work with Sequel'
     option 'dry-run', type: :boolean, desc: 'Only prints out what it would do, but makes no changes'
     option 'skip-bundle', type: :boolean, desc: "Don't run `bundle install` after modifying Gemfile"
+    # Updates the Gemfile to include the appropriate database adapter gem.
+    #
+    # This command analyzes your current database configuration and adds or updates
+    # the corresponding database adapter gem in your Gemfile. It supports various
+    # adapters including PostgreSQL, MySQL, SQLite, and JDBC-based adapters.
+    #
+    # @option options [Boolean] dry-run Only prints what would be done without making changes
+    # @option options [Boolean] skip-bundle Skip running `bundle install` after modification
     def update_gemfile
       GemfileModifier.new(options).modify
     end
 
     desc 'init_env', 'creates a .env file with the parameters listed'
     option :adapter,
-      aliases: :a,
-      desc: 'adapter for database'
+           aliases: :a,
+           desc: 'adapter for database'
     option :host,
-      aliases: :h,
-      banner: 'localhost',
-      desc: 'host for database'
+           aliases: :h,
+           banner: 'localhost',
+           desc: 'host for database'
     option :username,
-      aliases: :u,
-      desc: 'username for database'
+           aliases: :u,
+           desc: 'username for database'
     option :password,
-      aliases: :P,
-      desc: 'password for database'
+           aliases: :P,
+           desc: 'password for database'
     option :port,
-      aliases: :p,
-      type: :numeric,
-      banner: '5432',
-      desc: 'port for database'
+           aliases: :p,
+           type: :numeric,
+           banner: '5432',
+           desc: 'port for database'
     option :database,
-      aliases: :d,
-      desc: 'database for database'
+           aliases: :d,
+           desc: 'database for database'
     option :search_path,
-      aliases: :s,
-      desc: 'schema for database (PostgreSQL only)'
+           aliases: :s,
+           desc: 'schema for database (PostgreSQL only)'
+    # Creates a .env file with database configuration parameters.
+    #
+    # This command generates a .env file with SEQUELIZER_* environment variables
+    # based on the provided options. It will not overwrite an existing .env file.
+    #
+    # @option options [String] :adapter Database adapter (e.g., 'postgres', 'mysql2')
+    # @option options [String] :host Database host (default: 'localhost')
+    # @option options [String] :username Database username
+    # @option options [String] :password Database password
+    # @option options [Integer] :port Database port (default: 5432 for PostgreSQL)
+    # @option options [String] :database Database name
+    # @option options [String] :search_path PostgreSQL schema search path
+    # @raise [SystemExit] if .env file already exists
     def init_env
       if File.exist?('.env')
         puts ".env already exists!  I'm too cowardly to overwrite it!"
@@ -49,6 +85,11 @@ module Sequelizer
     end
 
     desc 'config', 'prints out the connection parameters'
+    # Displays the current database configuration and extensions.
+    #
+    # This command shows the resolved configuration options that would be used
+    # for database connections, including all merged sources and any Sequel
+    # extensions that would be loaded.
     def config
       opts = Options.new
       pp opts.to_hash
@@ -56,10 +97,12 @@ module Sequelizer
     end
 
     private
+
     def make_env(options)
       options.map do |key, value|
         "SEQUELIZER_#{key.upcase}=#{value}"
       end.join("\n")
     end
+
   end
 end

data/lib/sequelizer/connection_maker.rb

@@ -1,97 +1,79 @@
 require 'sequel'
-require 'cgi'
 require_relative 'options'
 
 module Sequelizer
-  # Class that handles loading/interpretting the database options and
-  # creates the Sequel connection
+  # = ConnectionMaker
+  #
+  # Class that handles loading/interpreting the database options and
+  # creates the Sequel connection. This class is responsible for:
+  #
+  # * Loading configuration from multiple sources
+  # * Creating standard Sequel database connections
+  #
+  # @example Basic usage
+  #   maker = ConnectionMaker.new(adapter: 'postgres', host: 'localhost')
+  #   db = maker.connection
   class ConnectionMaker
-    # The options for Sequel.connect
-    attr :options
 
-    # Accepts an optional set of database options
+    # @!attribute [r] options
+    #   @return [Options] the database connection options
+    attr_reader :options
+
+    # Creates a new ConnectionMaker instance.
     #
-    # If no options are provided, attempts to read options from
-    # config/database.yml
+    # If no options are provided, attempts to read options from multiple sources
+    # in order of precedence:
+    # 1. .env file
+    # 2. Environment variables
+    # 3. config/database.yml
+    # 4. ~/.config/sequelizer/database.yml
     #
-    # If config/database.yml doesn't exist, Dotenv is used to try to load a
-    # .env file, then uses any SEQUELIZER_* environment variables as
-    # database options
+    # @param options [Hash, nil] database connection options
+    # @option options [String] :adapter database adapter (e.g., 'postgres', 'mysql2')
+    # @option options [String] :host database host
+    # @option options [Integer] :port database port
+    # @option options [String] :database database name
+    # @option options [String] :username database username
+    # @option options [String] :password database password
+    # @option options [String] :search_path PostgreSQL schema search path
     def initialize(options = nil)
       @options = Options.new(options)
     end
 
-    # Returns a Sequel connection to the database
+    # Returns a Sequel connection to the database.
+    #
+    # This method creates a standard Sequel database connection
+    # using the configured options.
+    #
+    # @return [Sequel::Database] configured database connection
+    # @raise [Sequel::Error] if connection fails
+    #
+    # @example
+    #   connection = maker.connection
+    #   users = connection[:users].all
     def connection
       opts = options.to_hash
       extensions = options.extensions
 
-      conn = if url = (opts.delete(:uri) || opts.delete(:url))
-        Sequel.connect(url, opts)
-      else
-        # Kerberos related options
-        realm = opts[:realm]
-        host_fqdn = opts[:host_fqdn] || opts[:host]
-        principal = opts[:principal]
-
-        adapter = opts[:adapter]
-        if adapter =~ /\Ajdbc_/
-          user = opts[:user]
-          password = opts[:password]
-        end
-
-        case opts[:adapter] && opts[:adapter].to_sym
-        when :jdbc_hive2
-          opts[:adapter]  = :jdbc
-          auth = if realm
-            ";principal=#{e principal}/#{e host_fqdn}@#{e realm}"
-          elsif user
-            ";user=#{e user};password=#{e password}"
-          else
-            ';auth=noSasl'
-          end
-          opts[:uri] = "jdbc:hive2://#{e opts[:host]}:#{opts.fetch(:port, 21050).to_i}/#{e(opts[:database] || 'default')}#{auth}"
-        when :jdbc_impala
-          opts[:adapter]  = :jdbc
-          auth = if realm
-            ";AuthMech=1;KrbServiceName=#{e principal};KrbAuthType=2;KrbHostFQDN=#{e host_fqdn};KrbRealm=#{e realm}"
-          elsif user
-            if password
-              ";AuthMech=3;UID=#{e user};PWD=#{e password}"
-            else
-              ";AuthMech=2;UID=#{e user}"
-            end
-          end
-          opts[:uri] = "jdbc:impala://#{e opts[:host]}:#{opts.fetch(:port, 21050).to_i}/#{e(opts[:database] || 'default')}#{auth}"
-        when :jdbc_postgres
-          opts[:adapter]  = :jdbc
-          auth = "?user=#{user}#{"&password=#{password}" if password}" if user
-          opts[:uri] = "jdbc:postgresql://#{e opts[:host]}:#{opts.fetch(:port, 5432).to_i}/#{e(opts[:database])}#{auth}"
-        when :impala
-          opts[:database] ||= 'default'
-          opts[:port] ||= 21000
-          if principal
-            # realm doesn't seem to be used?
-            opts[:transport] = :sasl
-            opts[:sasl_params] = {
-              mechanism: "GSSAPI",
-              remote_host: host_fqdn,
-              remote_principal: principal
-            }
-          end
-        end
-
-        Sequel.connect(opts)
-      end
+      conn = create_sequel_connection(opts)
       conn.extension(*extensions)
       conn
     end
 
     private
 
-    def e(v)
-      CGI.escape(v.to_s)
+    def create_sequel_connection(opts)
+      if (url = opts.delete(:uri) || opts.delete(:url))
+        Sequel.connect(url, opts)
+      else
+        configure_adapter_specific_options(opts)
+        Sequel.connect(opts)
+      end
     end
+
+    def configure_adapter_specific_options(opts)
+      # No adapter-specific configuration needed currently
+    end
+
   end
 end
-

data/lib/sequelizer/env_config.rb

@@ -4,25 +4,25 @@ module Sequelizer
   # Creates a set of database configuration options from environment
   # variables
   class EnvConfig
+
     # Any environment variables in the .env file are loaded and then
     # any environment variable starting with SEQUELIZER_ will be used
     # as an option for the database
     def options
       Dotenv.load
 
-      seq_config = ENV.keys.select { |key| key =~ /^SEQUELIZER_/ }.inject({}) do |config, key|
+      seq_config = ENV.keys.grep(/^SEQUELIZER_/).each_with_object({}) do |key, config|
         new_key = key.gsub(/^SEQUELIZER_/, '').downcase
-        config[new_key] = ENV[key]
-        config
+        config[new_key] = ENV.fetch(key, nil)
       end
 
-      db_config = ENV.keys.select { |key| key =~ /_DB_OPT_/ }.inject({}) do |config, key|
+      db_config = ENV.keys.grep(/_DB_OPT_/).each_with_object({}) do |key, config|
         new_key = key.downcase
-        config[new_key] = ENV[key]
-        config
+        config[new_key] = ENV.fetch(key, nil)
       end
 
       db_config.merge(seq_config)
     end
+
   end
 end

data/lib/sequelizer/gemfile_modifier.rb

@@ -2,7 +2,8 @@ require_relative 'options'
 
 module Sequelizer
   class GemfileModifier
-    attr :options
+
+    attr_reader :options
 
     def initialize(options = {})
       @options = options
@@ -14,14 +15,14 @@ module Sequelizer
         modify_gemfile
         run_bundle unless options['skip-bundle']
       else
-        puts "Gemfile needs no modification"
+        puts 'Gemfile needs no modification'
       end
     end
 
     private
 
     def modify_gemfile
-      puts %Q|Adding "#{gem_line}" to Gemfile|
+      puts %(Adding "#{gem_line}" to Gemfile)
       return if options['dry-run']
 
       File.write(gemfile, modified_lines.join("\n"))
@@ -30,21 +31,21 @@ module Sequelizer
     def proper_gem
       opts = Options.new
       @proper_gem ||= case opts.adapter
-      when 'postgres'
-        'pg'
-      when 'sqlite'
-        'sqlite3'
-      when 'mysql'
-        'mysql2'
-      when 'tinytds'
-        'tiny_tds'
-      when 'oracle'
-        'ruby-oci8'
-      when nil
-        raise "No database adapter defined in your Sequelizer configuration"
-      else
-        raise "Don't know which database gem to use with adapter: #{opts.adapter}"
-      end
+                      when 'postgres'
+                        'pg'
+                      when 'sqlite'
+                        'sqlite3'
+                      when 'mysql'
+                        'mysql2'
+                      when 'tinytds'
+                        'tiny_tds'
+                      when 'oracle'
+                        'ruby-oci8'
+                      when nil
+                        raise 'No database adapter defined in your Sequelizer configuration'
+                      else
+                        raise "Don't know which database gem to use with adapter: #{opts.adapter}"
+                      end
     end
 
     def gem_line
@@ -68,22 +69,23 @@ module Sequelizer
     end
 
     def modified_lines
-      gemfile_lines.select { |l| l !~ Regexp.new(gem_line_comment) } + [full_gem_line]
+      gemfile_lines.grep_v(Regexp.new(gem_line_comment)) + [full_gem_line]
     end
 
     def check_for_gemfile
       return if gemfile.exist?
+
       raise "Could not find Gemfile in current directory: #{Pathname.pwd}"
     end
 
     def run_bundle
-      puts "Running `bundle install` to update dependencies"
+      puts 'Running `bundle install` to update dependencies'
       system('bundle install')
     end
 
     def gemfile
       @gemfile ||= Pathname.new('Gemfile')
     end
+
   end
 end
-

data/lib/sequelizer/monkey_patches/database_in_after_connect.rb

@@ -1,11 +1,12 @@
 module Sequel
   class ConnectionPool
+
     # Return a new connection by calling the connection proc with the given server name,
     # and checking for connection errors.
     def make_new(server)
       begin
         conn = @db.connect(server)
-        if ac = @after_connect
+        if (ac = @after_connect)
           case ac.arity
           when 3
             ac.call(conn, server, @db)
@@ -15,12 +16,13 @@ module Sequel
             ac.call(conn)
           end
         end
-      rescue Exception=>exception
-        raise Sequel.convert_exception_class(exception, Sequel::DatabaseConnectionError)
+      rescue StandardError => e
+        raise Sequel.convert_exception_class(e, Sequel::DatabaseConnectionError)
       end
-      raise(Sequel::DatabaseConnectionError, "Connection parameters not valid") unless conn
+      raise(Sequel::DatabaseConnectionError, 'Connection parameters not valid') unless conn
+
       conn
     end
+
   end
 end
-

data/lib/sequelizer/options.rb

@@ -3,18 +3,61 @@ require_relative 'env_config'
 require_relative 'options_hash'
 
 module Sequelizer
+  # = Options
+  #
+  # Manages database connection options from multiple configuration sources.
+  # This class is responsible for:
+  #
+  # * Loading configuration from various sources (YAML files, environment variables, .env files)
+  # * Applying precedence rules for configuration sources
+  # * Processing adapter-specific options (especially PostgreSQL schema handling)
+  # * Managing Sequel extensions
+  # * Setting up after_connect callbacks
+  #
+  # == Configuration Sources (in order of precedence)
+  #
+  # 1. Passed options (highest priority)
+  # 2. .env file
+  # 3. Environment variables
+  # 4. config/database.yml
+  # 5. ~/.config/sequelizer/database.yml (lowest priority)
+  #
+  # @example Basic usage
+  #   options = Options.new(adapter: 'postgres', host: 'localhost')
+  #   hash = options.to_hash
+  #
+  # @example Loading from environment
+  #   ENV['SEQUELIZER_ADAPTER'] = 'postgres'
+  #   options = Options.new
+  #   puts options.adapter  # => 'postgres'
   class Options
-    attr :extensions
+
+    # @!attribute [r] extensions
+    #   @return [Array<Symbol>] list of Sequel extensions to load
+    attr_reader :extensions
+
+    # Creates a new Options instance, processing configuration from multiple sources.
+    #
+    # @param options [Hash, String, nil] database connection options or connection URL
+    #   If a Hash is provided, it will be merged with configuration from other sources.
+    #   If a String is provided, it's treated as a database URL and returned as-is.
+    #   If nil, configuration is loaded entirely from external sources.
     def initialize(options = nil)
       opts = fix_options(options)
       @options, @extensions = filter_extensions(opts)
     end
 
+    # Returns the processed options as a hash suitable for Sequel.connect.
+    #
+    # @return [Hash] the database connection options
     def to_hash
       @options
     end
 
-    %w(adapter database username password search_path).each do |name|
+    # Define accessor methods for common database options
+    %w[adapter database username password search_path].each do |name|
+      # @!method #{name}
+      #   @return [String, nil] the #{name} option value
       define_method(name) do
         @options[name]
       end
@@ -22,9 +65,14 @@ module Sequelizer
 
     private
 
+    # Creates an after_connect callback proc that handles custom callbacks
+    # and applies database-specific options.
+    #
+    # @param opts [Hash] options hash that may contain an :after_connect callback
+    # @return [Proc] callback to be executed after database connection
     def make_ac(opts)
-      Proc.new do |conn, server, db|
-        if ac = opts[:after_connect]
+      proc do |conn, server, db|
+        if (ac = opts[:after_connect])
           ac.arity == 2 ? ac.call(conn, server) : ac.call(conn)
         end
         db.extension :db_opts
@@ -32,19 +80,27 @@ module Sequelizer
       end
     end
 
+    # Processes and fixes the passed options, handling various input types
+    # and applying adapter-specific transformations.
+    #
     # If passed a hash, scans hash for certain options and sets up hash
-    # to be fed to Sequel.connect
+    # to be fed to Sequel.connect. Handles PostgreSQL schema setup and
+    # timeout conversion.
+    #
+    # If passed anything else (like a string that represents a database URL),
+    # the value is returned without modification.
     #
-    # If fed anything, like a string that represents the URL for a DB,
-    # the string is returned without modification
+    # @param passed_options [Hash, String, nil] the options to process
+    # @return [Hash, String] processed options or original string
     def fix_options(passed_options)
       return passed_options unless passed_options.nil? || passed_options.is_a?(Hash)
+
       opts = OptionsHash.new(passed_options || {}).to_hash
       sequelizer_options = db_config(opts).merge(opts)
 
       if sequelizer_options[:adapter] =~ /^postgres/
         sequelizer_options[:adapter] = 'postgres'
-        paths = %w(search_path schema_search_path schema).map { |key| sequelizer_options.delete(key) }.compact
+        paths = %w[search_path schema_search_path schema].map { |key| sequelizer_options.delete(key) }.compact
 
         unless paths.empty?
           sequelizer_options[:search_path] = paths.first
@@ -62,10 +118,14 @@ module Sequelizer
       sequelizer_options.merge(after_connect: make_ac(sequelizer_options))
     end
 
-    # Grabs the database options from
-    #  - ~/.config/sequelizer.yml if it exists
-    #  - config/database.yml if it exists
-    #  - environment variables (also reads from .env)
+    # Loads database configuration from external sources in order of precedence.
+    # Sources checked (in order):
+    # - ~/.config/sequelizer.yml (if it exists and not ignored)
+    # - config/database.yml (if it exists and not ignored)
+    # - environment variables (including .env file if not ignored)
+    #
+    # @param opts [Hash] base options that may contain ignore flags
+    # @return [OptionsHash] merged configuration from all sources
     def db_config(opts)
       @db_config ||= begin
         opts = OptionsHash.new(opts)
@@ -77,14 +137,19 @@ module Sequelizer
     end
 
     # Returns a proc that should be executed after Sequel connects to the
-    # datebase.
+    # database.
+    #
+    # For PostgreSQL connections with a search_path defined, this proc will:
+    # 1. Create each schema in the search path if it doesn't exist
+    # 2. Set the search_path for the connection
     #
-    # Right now, the only thing that happens is if we're connecting to
-    # PostgreSQL and the schema_search_path is defined, each schema
-    # is created if it doesn't exist, then the search_path is set for
-    # the connection.
+    # @param search_path [String] comma-separated list of PostgreSQL schemas
+    # @return [Proc] callback to execute after connection
+    # @example
+    #   callback = after_connect('public,app_schema')
+    #   # When called, creates schemas and sets search_path
     def after_connect(search_path)
-      Proc.new do |conn|
+      proc do |conn|
         search_path.split(',').map(&:strip).each do |schema|
           conn.execute("CREATE SCHEMA IF NOT EXISTS #{schema}")
         end
@@ -92,6 +157,19 @@ module Sequelizer
       end
     end
 
+    # Extracts Sequel extension configuration from options.
+    #
+    # Looks for keys starting with 'extension_' and converts them to
+    # extension names. The extension keys are removed from the options
+    # hash and returned separately.
+    #
+    # @param options [Hash] options hash that may contain extension keys
+    # @return [Array<Hash, Array>] tuple of [filtered_options, extensions]
+    # @example
+    #   opts = { adapter: 'postgres', extension_pg_json: true, extension_pg_array: true }
+    #   filtered_opts, exts = filter_extensions(opts)
+    #   # filtered_opts => { adapter: 'postgres' }
+    #   # exts => [:pg_json, :pg_array]
     def filter_extensions(options)
       extension_regexp = /^extension_/
       extension_keys = options.keys.select { |k| k.to_s =~ extension_regexp }
@@ -101,5 +179,6 @@ module Sequelizer
       end
       [options, extensions]
     end
+
   end
 end

data/lib/sequelizer/options_hash.rb

@@ -1,7 +1,9 @@
 require 'hashie'
 module Sequelizer
   class OptionsHash < Hash
+
     include Hashie::Extensions::IndifferentAccess
     include Hashie::Extensions::MergeInitializer
+
   end
 end

data/lib/sequelizer/version.rb

@@ -1,4 +1,6 @@
 module Sequelizer
+
   # Version for the gem
-  VERSION = "0.1.4"
+  VERSION = '0.1.6'.freeze
+
 end