ardb 0.27.3 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
---- 
-SHA1: 
-  metadata.gz: efed4edb38eade9eaa2de6263e30f163b4ffa3db
-  data.tar.gz: 41bb43c7936a806124cdeb747d78c6a4de2393e4
-SHA512: 
-  metadata.gz: ba2ed871805feac6de258476b78dc906c63b6a4491b8ab24925dc87447e19f4e89f073b6642729d8ec863a3b760257293da95ed4aa7e8d2b3f7d09aedc86cefe
-  data.tar.gz: f521735072f0ce180c0073593af0aefc5ae16cc3bcab8ed5c0dcf7677f1da6d818fa8b051c1f91fa07b18626582b4beeec021810a51223f6ca538d503c9fb7bb
+---
+SHA256:
+  metadata.gz: 81b830715964b5aace51929da208df3bf357a35c42e5c38aea50b4d98d625d96
+  data.tar.gz: f4014e705ae352722d6a16f08061767d31c5851b7c3e0cdc5c6592abcd74d034
+SHA512:
+  metadata.gz: '08a7091251f11c2969aae47148185eae17efe0996b7dd0d79f63ac9648ba13c7d60694fe6b3f46ef43e77924e928f209d0f13cdbdbbd249578e143fc3f6d18a9'
+  data.tar.gz: 77f04eda98916783b4c1fb076a7bc461fd71f114547d62030f2379be7c5687219e2c5b3e3e925d42ead55d5e8b5e1a6651c0841710665d3313888b3c96935adc

data/Gemfile

@@ -1,9 +1,8 @@
 source "https://rubygems.org"
 
-gemspec
-
-gem 'pry',  "~> 0.9.0"
+ruby "~> 2.4"
 
-# Lock down gem versions because they require a newer version of ruby
-gem 'i18n', "< 0.7"
+gemspec
 
+gem "pg",  "~> 1.1.4"
+gem "pry", "~> 0.12.2"

data/README.md

@@ -1,16 +1,265 @@
 # Ardb
 
-Activerecord database tools.
+Tools for using ActiveRecord with or without Rails.
 
 ## Usage
 
-TODO: Write code samples and usage instructions here
+Given configured database connection parameters, Ardb provides a CLI and assorted tools for working with an ActiveRecord database. Ardb is designed to be used with or without Rails.
+
+### Configuration
+
+By default, Ardb looks for database configuration in the `config/db.rb` file. You can override this using the `ENV["ARDB_DB_FILE"]` env var.
+
+The configuration includes typical database configuration parameters:
+
+```ruby
+# in config/db.rb
+require "ardb"
+
+Ardb.configure do |c|
+  c.logger Logger.new($stdout)
+  c.root_path File.expand_path("../..", __FILE__)
+
+  c.db.adapter      "postgresql"
+  c.db.encoding     "unicode"
+  c.db.min_messages "WARNING"
+  c.db.url          "localhost:5432"
+  c.db.username     "testuser"
+  c.db.password     "secret"
+  c.db.database     "testdb"
+end
+```
+
+#### Rails configuration
+
+If using Ardb with Rails, add a `config/db.rb` file to have Ardb use Rails's configuration settings:
+
+```ruby
+# in config/db.rb
+require_relative "./environment"
+require "ardb"
+
+# This Ardb configuration matches Rails's settings.
+Ardb.configure do |c|
+  rails_db_config    = Rails.application.config_for("database")
+  c.root_path        = Rails.root
+  c.logger           = Rails.logger
+  c.schema_format    = Rails.application.config.active_record.schema_format || :ruby
+  c.default_timezone = :utc
+  c.adapter          = rails_db_config["adapter"]
+  c.host             = rails_db_config["host"]
+  c.port             = rails_db_config["port"]
+  c.username         = rails_db_config["username"]
+  c.password         = rails_db_config["password"]
+  c.database         = rails_db_config["database"]
+  c.encoding         = rails_db_config["encoding"]
+  c.min_messages     = rails_db_config["min_messages"]
+
+  c.migrations_path = "db/migrate"
+  c.schema_path = "db/schema"
+end
+```
+
+### CLI
+
+```
+$ ardb --help
+Usage: ardb [COMMAND] [options]
+
+Options:
+        --version
+        --help
+
+Commands:
+  connect            Connect to the configured DB
+  create             Create the configured DB
+  drop               Drop the configured DB
+  generate-migration Generate a MIGRATION-NAME migration file
+  migrate            Migrate the configured DB
+  migrate-up         Migrate the configured DB up
+  migrate-down       Migrate the configured DB down
+  migrate-forward    Migrate the configured DB forward
+  migrate-backward   Migrate the configured DB backward
+```
+
+#### `connect` command
+
+```
+$ ardb connect --help
+Usage: ardb connect [options]
+
+Options:
+        --version
+        --help
+
+Description:
+  Connect to the configured DB
+$ ardb connect
+error: database "some_database" does not exist
+$ ardb create
+created postgresql db "some_database"
+$ ardb connect
+connected to postgresql db "some_database"
+```
+
+Use this command to verify the connection parameter configuration is correct.
+
+#### `create` command
+
+```
+$ ardb create --help
+Usage: ardb create [options]
+
+Options:
+        --version
+        --help
+
+Description:
+  Create the configured DB
+$ ardb create
+created postgresql db "some_database"
+$ ardb create
+error: database "some_database" already exists
+```
+
+#### `drop` command
+
+```
+$ ardb drop --help
+Usage: ardb drop [options]
+
+Options:
+        --version
+        --help
+
+Description:
+  Drop the configured DB
+$ ardb drop
+dropped postgresql db "some_database"
+$ ardb drop
+error: database "some_database" does not exist
+```
+
+#### `generate-migration` command
+
+```
+$ ardb generate-migration add_projects --help
+Usage: ardb generate-migration MIGRATION-NAME [options]
+
+Options:
+        --version
+        --help
+
+Description:
+  Generate a MIGRATION-NAME migration file
+$ ardb generate-migration add_projects
+generated /path/to/app/db/migrate/20191222074043_add_projects.rb
+```
+
+#### `migrate` command
+
+```
+$ ardb migrate --help
+Usage: ardb migrate [options]
+
+Options:
+        --version
+        --help
+
+Description:
+  Migrate the configured DB
+$ ardb migrate
+== 20191222074043 AddProjects: migrating ======================================
+-- create_table(:projects)
+   -> 0.0276s
+== 20191222074043 AddProjects: migrated (0.0277s) =============================
+```
+
+#### `migrate-up` command
+
+```
+$ ardb migrate-up --help
+Usage: ardb migrate-up [options]
+
+Options:
+    -t, --target-version VALUE       version to migrate to
+        --version
+        --help
+
+Description:
+  Migrate the configured DB up
+$ ardb migrate-up
+== 20191222074043 AddProjects: migrating ======================================
+-- create_table(:projects)
+   -> 0.0510s
+== 20191222074043 AddProjects: migrated (0.0511s) =============================
+```
+
+#### `migrate-down` command
+
+```
+$ ardb migrate-down --help
+Usage: ardb migrate-down [options]
+
+Options:
+    -t, --target-version VALUE       version to migrate to
+        --version
+        --help
+
+Description:
+  Migrate the configured DB down
+$ ardb migrate-down
+== 20191222074043 AddProjects: reverting ======================================
+-- drop_table(:projects)
+   -> 0.0092s
+== 20191222074043 AddProjects: reverted (0.0132s) =============================
+```
+
+#### `migrate-forward` command
+
+```
+$ ardb migrate-forward --help
+Usage: ardb migrate-forward [options]
+
+Options:
+    -s, --steps VALUE                number of migrations to migrate
+        --version
+        --help
+
+Description:
+  Migrate the configured DB forward
+$ ardb migrate-forward
+== 20191222074043 AddProjects: migrating ======================================
+-- create_table(:projects)
+   -> 0.0510s
+== 20191222074043 AddProjects: migrated (0.0511s) =============================
+```
+
+#### `migrate-backward` command
+
+```
+$ ardb migrate-backward --help
+Usage: ardb migrate-backward [options]
+
+Options:
+    -s, --steps VALUE                number of migrations to migrate
+        --version
+        --help
+
+Description:
+  Migrate the configured DB backward
+$ ardb migrate-backward
+== 20191222074043 AddProjects: reverting ======================================
+-- drop_table(:projects)
+   -> 0.0092s
+== 20191222074043 AddProjects: reverted (0.0132s) =============================
+```
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'ardb'
+    gem "ardb"
 
 And then execute:
 

data/ardb.gemspec

@@ -1,5 +1,5 @@
 # -*- encoding: utf-8 -*-
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "ardb/version"
 
@@ -11,19 +11,19 @@ Gem::Specification.new do |gem|
   gem.summary     = %q{Activerecord database tools.}
   gem.description = %q{Activerecord database tools.}
   gem.homepage    = "http://github.com/redding/ardb"
-  gem.license     = 'MIT'
+  gem.license     = "MIT"
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
-  gem.add_development_dependency("assert", ["~> 2.15.1"])
+  gem.required_ruby_version = "~> 2.4"
 
-  gem.add_dependency('activerecord',  ["~> 3.2"])
-  gem.add_dependency('activesupport', ["~> 3.2"])
-  gem.add_dependency('much-plugin',   ["~> 0.1.0"])
-  gem.add_dependency('ns-options',    ["~> 1.1.6"])
-  gem.add_dependency('scmd',          ["~> 3.0.1"])
+  gem.add_development_dependency("assert", ["~> 2.18.1"])
 
+  gem.add_dependency("activerecord",  ["> 5.0", "< 7.0"])
+  gem.add_dependency("activesupport", ["> 5.0", "< 7.0"])
+  gem.add_dependency("much-plugin",   ["~> 0.2.1"])
+  gem.add_dependency("scmd",          ["~> 3.0.3"])
 end

data/bin/ardb

@@ -3,5 +3,5 @@
 # Copyright (c) 2013-Present Kelly Redding and Collin Redding
 #
 
-require 'ardb/cli'
+require "ardb/cli"
 Ardb::CLI.run ARGV

data/lib/ardb.rb

@@ -1,115 +1,198 @@
-require 'pathname'
-require 'singleton'
-require 'active_record'
-require 'ns-options'
+require "active_record"
+require "logger"
 
-require 'ardb/version'
-require 'ardb/root_path'
+require "ardb/version"
 
-ENV['ARDB_DB_FILE'] ||= 'config/db'
+ENV["ARDB_DB_FILE"] ||= "config/db"
 
 module Ardb
-  NotConfiguredError = Class.new(RuntimeError)
-
-  def self.config; Config; end
-  def self.configure(&block); Config.define(&block); end
+  def self.config
+    @config ||= Config.new
+  end
 
-  def self.adapter; Adapter.current; end
+  def self.configure(&block)
+    self.config.tap(&block)
+  end
 
-  def self.validate!
-    if !self.config.required_set?
-      raise NotConfiguredError, "missing required configs"
-    end
+  def self.adapter
+    @adapter || raise(NotInitializedError.new(caller))
   end
 
+  def self.reset_adapter; @adapter = nil; end
+
   def self.init(establish_connection = true)
-    require 'ardb/require_autoloaded_active_record_files'
-    require self.config.db_file
-    validate!
-    Adapter.init
+    require "ardb/require_autoloaded_active_record_files"
+    begin
+      require_db_file
+    rescue InvalidDBFileError => exception
+      exception.set_backtrace(caller)
+      raise exception
+    end
+
+    self.config.validate!
+    @adapter = Adapter.new(self.config)
 
     # setup AR
+    ActiveRecord::Base.default_timezone = self.config.default_timezone
     ActiveRecord::Base.logger = self.config.logger
-    if establish_connection
-      ActiveRecord::Base.establish_connection(self.config.db_settings)
-    end
+    self.adapter.connect_db if establish_connection
   end
 
   def self.escape_like_pattern(pattern, escape_char = nil)
     self.adapter.escape_like_pattern(pattern, escape_char)
+  rescue NotInitializedError => exception
+    exception.set_backtrace(caller)
+    raise exception
   end
 
-  class Config
-    include NsOptions::Proxy
-
-    namespace :db do
-      option :adapter,          String,  :required => true
-      option :database,         String,  :required => true
-      option :encoding,         String,  :required => false
-      option :host,             String,  :required => false
-      option :port,             Integer, :required => false
-      option :username,         String,  :required => false
-      option :password,         String,  :required => false
-      option :pool,             Integer, :required => false
-      option :checkout_timeout, Integer, :required => false
+  private
+
+  # try requiring the db file via the load path or as an absolute path, if
+  # that fails it tries requiring relative to the current working directory
+  def self.require_db_file
+    begin
+      require ENV["ARDB_DB_FILE"]
+    rescue LoadError
+      require File.expand_path(ENV["ARDB_DB_FILE"], ENV["PWD"])
     end
+  rescue LoadError
+    raise InvalidDBFileError, "can't require `#{ENV["ARDB_DB_FILE"]}`, " \
+                              "check that the ARDB_DB_FILE env var is set to " \
+                              "the file path of your db file"
+  end
 
-    option :db_file,         Pathname, :default => ENV['ARDB_DB_FILE']
-    option :root_path,       Pathname, :required => true
-    option :logger,                    :required => true
-    option :migrations_path, RootPath, :default => proc{ "db/migrations" }
-    option :schema_path,     RootPath, :default => proc{ "db/schema" }
-    option :schema_format,   Symbol,   :default => :ruby
-
-    def self.db_settings
-      db.to_hash.inject({}) do |settings, (k, v)|
-        settings[k.to_s] = v if !v.nil?
-        settings
-      end
+  class Config
+    ACTIVERECORD_ATTRS = [
+      :adapter,
+      :database,
+      :encoding,
+      :host,
+      :port,
+      :username,
+      :password,
+      :pool,
+      :checkout_timeout,
+      :min_messages
+    ].freeze
+
+    DEFAULT_MIGRATIONS_PATH = "db/migrations".freeze
+    DEFAULT_SCHEMA_PATH     = "db/schema".freeze
+    RUBY_SCHEMA_FORMAT      = :ruby.freeze
+    SQL_SCHEMA_FORMAT       = :sql.freeze
+    VALID_SCHEMA_FORMATS    = [RUBY_SCHEMA_FORMAT, SQL_SCHEMA_FORMAT].freeze
+
+    attr_accessor(*ACTIVERECORD_ATTRS)
+    attr_accessor :default_timezone, :logger, :root_path
+    attr_reader :schema_format
+    attr_writer :migrations_path, :schema_path
+
+    def initialize
+      @default_timezone = :utc
+      @logger           = Logger.new(STDOUT)
+      @root_path        = ENV["PWD"]
+      @migrations_path  = DEFAULT_MIGRATIONS_PATH
+      @schema_path      = DEFAULT_SCHEMA_PATH
+      @schema_format    = RUBY_SCHEMA_FORMAT
     end
 
-  end
+    def migrations_path
+      File.expand_path(@migrations_path.to_s, @root_path.to_s)
+    end
 
-  class Adapter
-    include Singleton
+    def schema_path
+      File.expand_path(@schema_path.to_s, @root_path.to_s)
+    end
 
-    attr_accessor :current
+    def schema_format=(new_value)
+      @schema_format = begin
+        new_value.to_sym
+      rescue NoMethodError
+        raise ArgumentError, "schema format must be a `Symbol`", caller
+      end
+    end
 
-    def init
-      @current = Adapter.send(Ardb.config.db.adapter)
+    def activerecord_connect_hash
+      ACTIVERECORD_ATTRS.inject({}) do |h, attr_name|
+        value = self.send(attr_name)
+        !value.nil? ? h.merge!(attr_name.to_s => value) : h
+      end
     end
 
-    def reset
-      @current = nil
+    def validate!
+      if self.adapter.to_s.empty? || self.database.to_s.empty?
+        raise ConfigurationError, "an adapter and database must be provided"
+      end
+
+      if !VALID_SCHEMA_FORMATS.include?(self.schema_format)
+        raise ConfigurationError, "schema format must be one of: " \
+                                  "#{VALID_SCHEMA_FORMATS.join(", ")}"
+      end
+
+      true
     end
 
-    def sqlite
-      require 'ardb/adapter/sqlite'
-      Adapter::Sqlite.new
+    def ==(other)
+      if other.kind_of?(self.class)
+        self.activerecord_connect_hash == other.activerecord_connect_hash &&
+        self.default_timezone          == other.default_timezone          &&
+        self.logger                    == other.logger                    &&
+        self.root_path                 == other.root_path                 &&
+        self.schema_format             == other.schema_format             &&
+        self.migrations_path           == other.migrations_path           &&
+        self.schema_path               == other.schema_path
+      else
+        super
+      end
     end
-    alias_method :sqlite3, :sqlite
+  end
 
-    def postgresql
-      require 'ardb/adapter/postgresql'
-      Adapter::Postgresql.new
+  module Adapter
+    VALID_ADAPTERS = [
+      "sqlite",
+      "sqlite3",
+      "postgresql",
+      "postgres",
+      "mysql",
+      "mysql2"
+    ].freeze
+
+    def self.new(config)
+      if !VALID_ADAPTERS.include?(config.adapter)
+        raise InvalidAdapterError, "invalid adapter: `#{config.adapter}`"
+      end
+      self.send(config.adapter, config)
     end
 
-    def mysql
-      require 'ardb/adapter/mysql'
-      Adapter::Mysql.new
+    def self.sqlite(config)
+      require "ardb/adapter/sqlite"
+      Adapter::Sqlite.new(config)
     end
-    alias_method :mysql2, :mysql
 
-    # nice singleton api
+    def self.sqlite3(config); self.sqlite(config); end
 
-    def self.method_missing(method, *args, &block)
-      self.instance.send(method, *args, &block)
+    def self.postgresql(config)
+      require "ardb/adapter/postgresql"
+      Adapter::Postgresql.new(config)
     end
 
-    def self.respond_to?(method)
-      super || self.instance.respond_to?(method)
+    def self.postgres(config); self.postgresql(config); end
+
+    def self.mysql(config)
+      require "ardb/adapter/mysql"
+      Adapter::Mysql.new(config)
     end
 
+    def self.mysql2(config); self.mysql(config); end
   end
 
+  InvalidDBFileError  = Class.new(ArgumentError)
+  ConfigurationError  = Class.new(ArgumentError)
+  InvalidAdapterError = Class.new(RuntimeError)
+
+  class NotInitializedError < RuntimeError
+    def initialize(backtrace)
+      super("ardb hasn't been initialized yet, run `Ardb.init`")
+      set_backtrace(backtrace)
+    end
+  end
 end