gemstack-db 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4dfcb9cab762647a4a5b66a1b39a171654b2e90a4fa5fb51ce582a92866ec610
-  data.tar.gz: 11711623cf668ec45e2fc92e046e7fe8cf8592654e13cbbb334609bcbd103e51
+  metadata.gz: cf134933c7903511b62c753226076a98b1ae0d927167ae8007d32f9afb6abc27
+  data.tar.gz: e69ef13d0fc8014792dcf4a64dfd6757c33cd7dea1774bfbb54194f5cfacdb1d
 SHA512:
-  metadata.gz: 50f2dbc4310478ffc79f2239b0dcc630c169341be13a8f0189a8b977e74e226412c78be563cca57f0de862c7c31dde12169f6e14ce86e97f44bd65fb78e199b6
-  data.tar.gz: 64c0e1055cef2f98c087daf97f9a5890bf6aaf353ff6d3cf33f446fedaa6000fe59079dcd27f070b1cbe6a37f853682ad8419293a18dd7d19d50a2bcf9b2a4ff
+  metadata.gz: 6a992b442bdaf429cb43393330c3c65fc74fe8f60e4803939b74dc7911cb43d6411152563a0022859af4fa06daf1861b8b67bc12073249a471744d2c7e5bba0e
+  data.tar.gz: f4e38958524c13c1da10e6a20c6834b5840e2a6feeeac09d33c73766b1445e730eea79b9e7920ae39d9a9dec1e58e22ad6d2a21c2981d51a5850323906df2d54

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.1
+
+See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
+
+## 0.2.0
+
+See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
+
 ## 0.1.0
 
 First release. See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/README.md

@@ -1,6 +1,6 @@
 # gemstack-db
 
-GemStack database: Sequel models, migrations and PostgreSQL defaults.
+GemStack database: Sequel models and migrations for SQLite, PostgreSQL and MySQL.
 
 Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
 applications. All GemStack gems are developed together in that repository and released with the same
@@ -16,7 +16,7 @@ gem "gemstack-db", "~> 0.1"
 
 ## Documentation
 
-- [Guide](https://github.com/gemstack-rb/gemstack/blob/main/docs/models.md)
+- [Guide](https://github.com/gemstack-rb/gemstack/blob/main/docs/database.md)
 - [All guides](https://github.com/gemstack-rb/gemstack/tree/main/docs) ·
   [Architecture](https://github.com/gemstack-rb/gemstack/blob/main/ARCHITECTURE.md)
 

data/lib/gemstack/db/configuration.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "erb"
+require "uri"
+require "yaml"
+
+module GemStack
+  module DB
+    # Where the connection settings come from, first match wins (DECISIONS D-062):
+    #
+    #   1. config.db.url, set in config/app.rb or config/environments/*.rb
+    #   2. DATABASE_URL (TEST_DATABASE_URL in the test environment)
+    #   3. config/database.yml — the section for the current environment
+    #   4. PostgreSQL on this machine, database <app>_<env> (apps without database.yml)
+    #
+    # config/database.yml works like Rails' (ERB allowed):
+    #
+    #   default: &default
+    #     adapter: postgresql          # postgresql, mysql2, trilogy or sqlite3
+    #     pool: <%= ENV.fetch("GEMSTACK_MAX_THREADS", 5) %>
+    #   development:
+    #     <<: *default
+    #     database: shop_development
+    #   test:
+    #     <<: *default
+    #     database: shop_test
+    #   production:
+    #     <<: *default
+    #     url: <%= ENV["DATABASE_URL"] %>
+    #
+    # The result is a Hash for Sequel.connect: { adapter: "postgres", database:, host:, … }.
+    module Configuration
+      # Rails-style names (and URL schemes) → Sequel adapters.
+      ADAPTERS = {
+        "postgresql" => "postgres", "postgres" => "postgres", "postgis" => "postgres",
+        "mysql2" => "mysql2", "mysql" => "mysql2", "trilogy" => "trilogy",
+        "sqlite3" => "sqlite", "sqlite" => "sqlite"
+      }.freeze
+      # The gem each adapter needs in the application's Gemfile.
+      DRIVER_GEMS = { "postgres" => "pg", "mysql2" => "mysql2", "trilogy" => "trilogy", "sqlite" => "sqlite3" }.freeze
+      # database.yml keys with another name in Sequel.
+      RENAMED = { "username" => :user, "pool" => :max_connections }.freeze
+      # database.yml keys Rails uses that mean nothing to Sequel.
+      IGNORED = %w[schema_search_path migrations_paths reaping_frequency idle_timeout checkout_timeout].freeze
+
+      module_function
+
+      def resolve(config: DB.config, env: GemStack.env, root: GemStack.config.root)
+        return from_url(config.url, root: root).merge(source: "config.db.url") if config.url
+
+        variable = env.test? ? "TEST_DATABASE_URL" : "DATABASE_URL"
+        url = ENV.fetch(variable, "").strip
+        yaml = yaml_settings(root, env)
+        return from_url(url, root: root).merge(pool_from(yaml)).merge(source: variable) unless url.empty?
+        return yaml.merge(source: "config/database.yml (#{env})") if yaml
+
+        name = "#{GemStack.config.name.to_s.tr("-", "_")}_#{env}"
+        { adapter: "postgres", database: name, source: "default (no config/database.yml)" }
+      end
+
+      # The section of config/database.yml for this environment, normalized; nil without the file.
+      def yaml_settings(root, env)
+        path = File.join(root.to_s, "config", "database.yml")
+        return nil unless File.file?(path)
+
+        data = YAML.safe_load(ERB.new(File.read(path)).result, aliases: true, filename: path) || {}
+        section = data[env.to_s] or raise ConfigurationError, "config/database.yml has no #{env} section"
+        raise ConfigurationError, "config/database.yml: #{env} must be a mapping" unless section.is_a?(Hash)
+
+        from_hash(section, root: root)
+      rescue Psych::Exception => e
+        raise ConfigurationError, "config/database.yml: #{e.message}"
+      end
+
+      def from_hash(section, root:)
+        url = section["url"].to_s.strip
+        base = url.empty? ? {} : from_url(url, root: root)
+        settings = section.each_with_object({}) do |(key, value), out|
+          next if key == "url" || IGNORED.include?(key) || value.nil?
+
+          out[RENAMED.fetch(key, key.to_sym)] = value
+        end
+        settings = base.merge(settings) { |_, from_url, from_keys| from_keys || from_url }
+        settings[:adapter] = adapter!(settings[:adapter]) if settings[:adapter]
+        raise ConfigurationError, "config/database.yml: set adapter (or url)" unless settings[:adapter]
+
+        settings[:max_connections] = Integer(settings[:max_connections]) if settings[:max_connections]
+        settings[:port] = Integer(settings[:port]) if settings[:port]
+        sqlite_path(settings, root)
+      end
+
+      # postgres://user:pass@host:5432/name?sslmode=require, mysql2://…, trilogy://…,
+      # sqlite3:db/development.sqlite3 (relative to the app), sqlite3:///abs/path.db, sqlite3::memory:
+      def from_url(url, root:)
+        scheme = url[/\A([a-z0-9+.-]+):/i, 1].to_s.downcase
+        adapter = adapter!(scheme)
+        if adapter == "sqlite"
+          path = url.sub(/\A[^:]+:/, "").sub(%r{\A//}, "").sub(/\?.*\z/, "")
+          return sqlite_path({ adapter: adapter, database: path }, root)
+        end
+
+        uri = URI.parse(url)
+        settings = { adapter: adapter, host: uri.host, port: uri.port,
+                     database: decode(uri.path.to_s.delete_prefix("/")), user: decode(uri.user),
+                     password: decode(uri.password) }
+        URI.decode_www_form(uri.query.to_s).each { |key, value| settings[key.to_sym] = value }
+        settings.reject { |_, value| value.nil? || value == "" }
+      rescue URI::InvalidURIError => e
+        raise ConfigurationError, "invalid database URL: #{e.message}"
+      end
+
+      def adapter!(name)
+        ADAPTERS.fetch(name.to_s.downcase) do
+          raise ConfigurationError, "unsupported database adapter #{name.inspect} " \
+                                    "(use postgresql, mysql2, trilogy or sqlite3)"
+        end
+      end
+
+      def pool_from(yaml) = yaml && yaml[:max_connections] ? { max_connections: yaml[:max_connections] } : {}
+
+      def sqlite_path(settings, root)
+        return settings unless settings[:adapter] == "sqlite"
+
+        database = settings[:database].to_s
+        if database.empty?
+          raise ConfigurationError,
+                "sqlite3 needs a database file (e.g. database: db/development.sqlite3)"
+        end
+
+        settings[:database] = File.expand_path(database, root.to_s) unless database == ":memory:"
+        settings
+      end
+
+      def decode(value) = value && URI.decode_www_form_component(value)
+
+      # For logs and `gemstack doctor`: no passwords.
+      def describe(settings)
+        if settings[:adapter] == "sqlite"
+          return "sqlite3 #{settings[:database].to_s.delete_prefix("#{GemStack.config.root}/")}"
+        end
+
+        host = settings[:host] || "localhost"
+        user = settings[:user] ? "#{settings[:user]}@" : ""
+        "#{settings[:adapter]}://#{user}#{host}#{":#{settings[:port]}" if settings[:port]}/#{settings[:database]}"
+      end
+    end
+  end
+end

data/lib/gemstack/db/errors.rb

@@ -2,20 +2,25 @@
 
 module GemStack
   module DB
-    # Gives Sequel/PostgreSQL errors their HTTP meaning via GemStack::ErrorMapping
-    # (no dependency on the HTTP layer):
+    # Gives Sequel errors their HTTP meaning via GemStack::ErrorMapping (no
+    # dependency on the HTTP layer), for PostgreSQL, MySQL and SQLite:
     #
     #   record not found           → 404 not_found
     #   model validation failed    → 422 validation_failed + field errors
-    #   unique / not-null / FK     → 422 with the offending column when PostgreSQL reports it
+    #   unique / not-null / FK     → 422 with the offending column when the database names it
     #   row still referenced (FK)  → 409 conflict
     #   database unreachable       → 503 service_unavailable
     module Errors
-      KEY_DETAIL = /Key \(([^)]+)\)=/
+      KEY_DETAIL = /Key \(([^)]+)\)=/ # PostgreSQL
+      MYSQL_KEY = /Duplicate entry .* for key '(?:[^.']+\.)?([^']+)'/   # MySQL 8 names table.index
+      SQLITE_COLUMNS = /constraint failed: ((?:[\w.]+(?:, )?)+)/i       # UNIQUE / NOT NULL
+      FK_COLUMN = /FOREIGN KEY \(`?([^`)]+)`?\)/                        # MySQL
 
       module_function
 
       def install!
+        # Registered first: the specific classes below take precedence.
+        ErrorMapping.register(Sequel::DatabaseError) { |error| mysql_missing_value(error) }
         install_record_errors!
         install_constraint_errors!
         ErrorMapping.register(Sequel::DatabaseConnectionError) { ServiceUnavailable.new("Database unavailable") }
@@ -46,7 +51,7 @@ module GemStack
           field_error([column(error)].compact, "is required") || ValidationError.new("A required value is missing")
         end
         ErrorMapping.register(Sequel::ForeignKeyConstraintViolation) do |error|
-          if error.message.include?("is not present")
+          if referenced_missing?(error)
             field_error(columns(error), "does not exist") || ValidationError.new("A referenced record does not exist")
           else
             Conflict.new("Record is still referenced by other records", code: "still_referenced")
@@ -57,6 +62,13 @@ module GemStack
         end
       end
 
+      # MySQL (strict mode) reports an omitted NOT NULL column without a
+      # default as a plain error: "Field 'name' doesn't have a default value".
+      def mysql_missing_value(error)
+        name = error.message[/Field '([^']+)' doesn't have a default value/, 1]
+        name && ValidationError.new(errors: { name => ["is required"] })
+      end
+
       def stringify(errors) = errors.to_h { |key, messages| [Array(key).join(","), Array(messages)] }
 
       def field_error(names, message)
@@ -67,23 +79,57 @@ module GemStack
 
       def pg_error(error) = error.respond_to?(:wrapped_exception) ? error.wrapped_exception : nil
 
+      # PostgreSQL: "is not present in table"; MySQL: "Cannot add or update a child row".
+      # SQLite doesn't say which side failed, so it is reported as a conflict.
+      def referenced_missing?(error)
+        message = error.message
+        message.include?("is not present") || message.include?("Cannot add or update a child row")
+      end
+
+      # The columns named by a unique or foreign-key violation, when the database says.
       def columns(error)
-        if defined?(PG::PG_DIAG_MESSAGE_DETAIL)
-          detail = pg_error(error)&.result&.error_field(PG::PG_DIAG_MESSAGE_DETAIL)
+        message = error.message
+        if (detail = pg_detail(error) || message[KEY_DETAIL]) && (match = KEY_DETAIL.match(detail))
+          match[1].split(",").map(&:strip).map { |c| c.delete('"') }
+        elsif (match = SQLITE_COLUMNS.match(message))
+          match[1].split(", ").map { |name| name.split(".").last }
+        elsif (match = FK_COLUMN.match(message))
+          [match[1]]
+        elsif (match = MYSQL_KEY.match(message))
+          index_column(match[1])
+        else
+          []
         end
-        detail ||= error.message
-        match = KEY_DETAIL.match(detail.to_s)
-        match ? match[1].split(",").map(&:strip).map { |c| c.delete('"') } : []
       rescue StandardError
         []
       end
 
       def column(error)
-        pg_error(error)&.result&.error_field(PG::PG_DIAG_COLUMN_NAME) ||
-          error.message[/column "([^"]+)"/, 1]
+        message = error.message
+        (defined?(PG::PG_DIAG_COLUMN_NAME) && pg_error(error)&.result&.error_field(PG::PG_DIAG_COLUMN_NAME)) ||
+          message[/column "([^"]+)"/, 1] || message[/Column '([^']+)' cannot be null/, 1] ||
+          sqlite_column(message)
       rescue StandardError
         nil
       end
+
+      def sqlite_column(message)
+        list = message[SQLITE_COLUMNS, 1] or return nil
+        list.split(", ").first.split(".").last
+      end
+
+      def pg_detail(error)
+        return nil unless defined?(PG::PG_DIAG_MESSAGE_DETAIL)
+
+        pg_error(error)&.result&.error_field(PG::PG_DIAG_MESSAGE_DETAIL)
+      end
+
+      # MySQL reports the index, not the column. `unique: true` on a column
+      # (what the generators write) names the index after the column; other
+      # indexes (table_column_index, composite) can't be mapped to one field.
+      def index_column(name)
+        name == "PRIMARY" || name.match?(/_(?:key|unique|uniq|index)\z/) ? [] : [name]
+      end
     end
   end
 end

data/lib/gemstack/db/migrator.rb

@@ -61,7 +61,7 @@ module GemStack
       def pending? = !pending.empty?
 
       def applied
-        return [] unless db.table_exists?(:schema_migrations)
+        return [] if DB.table_missing?(db, :schema_migrations)
 
         db[:schema_migrations].select_map(:filename)
       end

data/lib/gemstack/db/model.rb

@@ -49,6 +49,7 @@ module GemStack
         raise ArgumentError, "unknown field option(s) #{unknown.inspect} for #{name}" unless unknown.empty?
 
         @input_schemas = nil
+        serialize_json(name) if Types::CLASS_ALIASES.fetch(type, type).to_sym == :json
         gemstack_fields[name.to_sym] = Field.new(name.to_sym, Types::CLASS_ALIASES.fetch(type, type).to_sym,
                                                  options.freeze)
       end
@@ -99,6 +100,15 @@ module GemStack
 
       private
 
+      # PostgreSQL's jsonb comes back as Hash/Array (pg_json); MySQL JSON and
+      # SQLite text come back as strings, so those fields are (de)serialized.
+      def serialize_json(name)
+        return if db.database_type == :postgres
+
+        plugin :serialization unless respond_to?(:serialization_map)
+        serialize_attributes :json, name unless serialization_map.key?(name.to_sym)
+      end
+
       # For a table that doesn't exist yet, skip Sequel's schema queries: they
       # would fail and log two errors per model (e.g. while `gemstack contract`
       # runs before `db:migrate`). One cheap catalog lookup decides.
@@ -110,9 +120,9 @@ module GemStack
       end
 
       def missing_table?
-        return false unless @dataset && db.database_type == :postgres
+        return false unless @dataset
 
-        db.get(Sequel.function(:to_regclass, db.literal(dataset.first_source_table))).nil?
+        DB.table_missing?(db, dataset.first_source_table)
       rescue Sequel::Error
         false
       end

data/lib/gemstack/db/schema_types.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module GemStack
+  module DB
+    # Migrations may use PostgreSQL's type names — the generators write
+    # `column :created_at, :timestamptz` — and still run on MySQL and SQLite,
+    # where each maps to the closest native type (DECISIONS D-062). Everything
+    # else in the Sequel schema DSL is untouched.
+    module SchemaTypes
+      MAPPINGS = {
+        mysql: { "timestamptz" => "datetime(6)", "timestamp" => "datetime(6)", "jsonb" => "json",
+                 "uuid" => "char(36)", "inet" => "varchar(45)", "citext" => "varchar(255)" },
+        sqlite: { "timestamptz" => "timestamp", "jsonb" => "json", "uuid" => "varchar(36)",
+                  "inet" => "varchar(45)", "citext" => "varchar(255)" }
+      }.freeze
+
+      private
+
+      def type_literal_specific(column)
+        type = column[:type]
+        mapped = MAPPINGS.dig(database_type, type.to_s.downcase) if type.is_a?(Symbol) || type.is_a?(String)
+        mapped || super
+      end
+    end
+  end
+end
+
+Sequel::Database.prepend(GemStack::DB::SchemaTypes)

data/lib/gemstack/db/tasks.rb

@@ -1,46 +1,74 @@
 # frozen_string_literal: true
 
-require "uri"
+require "fileutils"
 
 module GemStack
   module DB
-    # Database lifecycle used by `gemstack db:*`.
+    # Database lifecycle used by `gemstack db:*`, for every adapter:
+    # PostgreSQL and MySQL through a server connection without the database,
+    # SQLite by creating or deleting the file.
+    #
+    # Each method takes resolved settings (DB.settings, the default) or a URL.
     module Tasks
       module_function
 
-      def database_name(url = DB.config.url)
-        URI.parse(url).path.delete_prefix("/").then { |n| URI.decode_www_form_component(n) }
+      def settings_for(target)
+        target.is_a?(String) ? Configuration.from_url(target, root: GemStack.config.root) : target.except(:source)
       end
 
-      # The same server with the "postgres" maintenance database.
-      def maintenance_url(url = DB.config.url)
-        uri = URI.parse(url)
-        uri.path = "/postgres"
-        uri.to_s
+      # The database name (SQLite: the file, relative to the app).
+      def database_name(target = DB.settings)
+        name = settings_for(target)[:database].to_s
+        name.delete_prefix("#{GemStack.config.root}/")
       end
 
-      def exists?(url = DB.config.url)
-        with_maintenance(url) { |db| db[:pg_database].where(datname: database_name(url)).any? }
+      def exists?(target = DB.settings)
+        settings = settings_for(target)
+        name = settings[:database].to_s
+        case settings[:adapter]
+        when "sqlite" then name == ":memory:" || File.file?(name)
+        when "postgres" then with_server(settings) { |db| db[:pg_database].where(datname: name).any? }
+        else with_server(settings) { |db| db[Sequel[:information_schema][:schemata]].where(schema_name: name).any? }
+        end
       end
 
       # Returns :created or :exists.
-      def create(url = DB.config.url)
-        return :exists if exists?(url)
+      def create(target = DB.settings)
+        settings = settings_for(target)
+        return :exists if exists?(settings)
 
-        with_maintenance(url) { |db| db.run("CREATE DATABASE #{db.literal(Sequel.identifier(database_name(url)))}") }
+        name = settings[:database].to_s
+        case settings[:adapter]
+        when "sqlite"
+          FileUtils.mkdir_p(File.dirname(name))
+          Sequel.connect(**settings, test: true, keep_reference: false).disconnect # creates the file
+        when "postgres"
+          with_server(settings) { |db| db.run("CREATE DATABASE #{db.literal(Sequel.identifier(name))}") }
+        else
+          with_server(settings) do |db|
+            db.run("CREATE DATABASE #{db.literal(Sequel.identifier(name))} " \
+                   "CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci")
+          end
+        end
         :created
       end
 
       # Refuses outside development/test unless GEMSTACK_ALLOW_DB_DROP=1.
-      def drop(url = DB.config.url)
+      def drop(target = DB.settings)
         unless GemStack.env.local? || ENV["GEMSTACK_ALLOW_DB_DROP"] == "1"
           raise Error, "refusing to drop the #{GemStack.env} database; set GEMSTACK_ALLOW_DB_DROP=1 to confirm"
         end
-        return :missing unless exists?(url)
+
+        settings = settings_for(target)
+        return :missing unless exists?(settings)
 
         DB.disconnect
-        with_maintenance(url) do |db|
-          db.run("DROP DATABASE #{db.literal(Sequel.identifier(database_name(url)))} WITH (FORCE)")
+        name = settings[:database].to_s
+        case settings[:adapter]
+        when "sqlite" then FileUtils.rm_f(["", "-wal", "-shm", "-journal"].map { |suffix| "#{name}#{suffix}" })
+        when "postgres"
+          with_server(settings) { |db| db.run("DROP DATABASE #{db.literal(Sequel.identifier(name))} WITH (FORCE)") }
+        else with_server(settings) { |db| db.run("DROP DATABASE #{db.literal(Sequel.identifier(name))}") }
         end
         :dropped
       end
@@ -52,8 +80,11 @@ module GemStack
         true
       end
 
-      def with_maintenance(url)
-        db = Sequel.connect(maintenance_url(url), max_connections: 1, test: true, keep_reference: false)
+      # A connection to the server itself: PostgreSQL's "postgres" maintenance
+      # database, or MySQL without a default database.
+      def with_server(settings)
+        server = settings.merge(database: settings[:adapter] == "postgres" ? "postgres" : nil).compact
+        db = Sequel.connect(**server, max_connections: 1, test: true, keep_reference: false)
         yield db
       ensure
         db&.disconnect

data/lib/gemstack/db.rb

@@ -6,23 +6,24 @@ require "gemstack/core"
 require "gemstack/schema"
 
 require_relative "db/json_compat"
+require_relative "db/configuration"
+require_relative "db/schema_types"
 
 module GemStack
-  # PostgreSQL through Sequel (DECISIONS D-018). Optional: add
-  # `gem "gemstack-db"` to the Gemfile (new apps include it by default).
+  # SQL databases through Sequel (DECISIONS D-018, D-062): PostgreSQL, MySQL
+  # (mysql2 or trilogy) and SQLite, configured by config/database.yml or
+  # DATABASE_URL. Optional: add `gem "gemstack-db"` and the driver gem
+  # (pg, mysql2, trilogy or sqlite3) to the Gemfile — `gemstack new` does.
   #
   #   GemStack.db[:products].where(active: true).count     # the Sequel::Database
   #   GemStack.transaction { order.save; payment.save }
   module DB
     class Config < Settings
-      # Test uses TEST_DATABASE_URL so a DATABASE_URL meant for development
-      # (e.g. from .env) can never be used by the test suite.
-      setting :url, default: lambda {
-        env = GemStack.env
-        name = "#{GemStack.config.name.tr("-", "_")}_#{env}"
-        (env.test? ? ENV.fetch("TEST_DATABASE_URL", nil) : ENV.fetch("DATABASE_URL", nil)) || "postgres:///#{name}"
-      }
-      # One connection per server thread by default.
+      # An explicit database URL; wins over DATABASE_URL and config/database.yml
+      # (see DB::Configuration). Test uses TEST_DATABASE_URL, never DATABASE_URL,
+      # so a development database from .env can't be wiped by the test suite.
+      setting :url, default: nil
+      # One connection per server thread by default (database.yml `pool:` wins).
       setting :pool_size, default: lambda {
         Integer(ENV.fetch("GEMSTACK_DB_POOL") { ENV.fetch("GEMSTACK_MAX_THREADS", 5) })
       }
@@ -32,21 +33,27 @@ module GemStack
       setting :log_queries, default: -> { GemStack.env.development? }
       # Queries slower than this are logged at WARN in every environment.
       setting :slow_query_ms, default: 500
-      # Server-side statement timeout in ms (nil = PostgreSQL default).
+      # Server-side statement timeout in ms (nil = the database's default).
+      # PostgreSQL: statement_timeout; MySQL: max_execution_time (SELECTs); SQLite: none.
       setting :statement_timeout, default: nil
-      setting :extensions, default: %i[pg_json pg_array]
+      # Sequel extensions to load; nil = pg_json + pg_array on PostgreSQL, none elsewhere.
+      setting :extensions, default: nil
       # Extra options passed to Sequel.connect.
       setting :options, default: {}
     end
 
     class RecordNotFound < NotFound; end
 
+    # Stored and compared in UTC on every adapter (MySQL DATETIME and SQLite
+    # text have no time zone); PostgreSQL timestamptz is unaffected.
+    Sequel.database_timezone = :utc
+
     # Adapts Sequel's logging to the GemStack logger: SQL at DEBUG only when
     # config.db.log_queries is on, slow queries at WARN, and failures of the
     # existence probes Sequel runs on purpose (table_exists?, model setup
     # before a migration) are not reported as errors.
     class QueryLogger
-      PROBE = /: SELECT (?:NULL AS "nil" FROM \S+ LIMIT 1|\* FROM \S+ LIMIT 0)\z/
+      PROBE = /: SELECT (?:NULL AS [`"']nil[`"'] FROM \S+ LIMIT 1|\* FROM \S+ LIMIT 0)\z/
 
       def initialize(logger, queries:)
         @logger = logger
@@ -70,18 +77,34 @@ module GemStack
 
       def connected? = !@connection.nil?
 
+      # The resolved connection settings (a Hash; see DB::Configuration).
+      def settings = @settings ||= Configuration.resolve
+
+      # "postgres", "mysql2", "trilogy" or "sqlite".
+      def adapter = settings[:adapter]
+      def postgres?(db = nil) = type(db) == :postgres
+      def mysql?(db = nil) = type(db) == :mysql
+      def sqlite?(db = nil) = type(db) == :sqlite
+
+      # Sequel's database type (:postgres, :mysql, :sqlite) — from the
+      # connection when there is one, so no query is needed.
+      def type(db = nil)
+        db ||= @connection
+        return db.database_type if db
+
+        { "postgres" => :postgres, "mysql2" => :mysql, "trilogy" => :mysql, "sqlite" => :sqlite }.fetch(adapter)
+      end
+
       # Builds the Sequel::Database. Connections are opened lazily, so an
       # unavailable database doesn't prevent the application from booting.
-      def connect(url = config.url)
-        options = { max_connections: config.pool_size, pool_timeout: config.pool_timeout, test: false,
-                    keep_reference: false }
-        timeout = config.statement_timeout
-        options[:after_connect] = ->(conn) { conn.exec("SET statement_timeout = #{Integer(timeout)}") } if timeout
-        db = Sequel.connect(url, **options, **config.options)
-        db.extension(*config.extensions) unless config.extensions.empty?
-        db.log_warn_duration = config.slow_query_ms / 1000.0 if config.slow_query_ms
-        db.loggers << QueryLogger.new(GemStack.logger, queries: config.log_queries)
-        db.sql_log_level = :debug
+      def connect(target = settings)
+        target = Configuration.from_url(target, root: GemStack.config.root) if target.is_a?(String)
+        opts = target.except(:source)
+        options = { max_connections: opts.delete(:max_connections) || config.pool_size,
+                    pool_timeout: config.pool_timeout, test: false, keep_reference: false }
+        options.merge!(adapter_options(opts[:adapter], opts[:database]))
+        db = open_database(opts.merge(options).merge(config.options))
+        configure(db)
         Sequel::Model.db = db
         db
       end
@@ -94,6 +117,60 @@ module GemStack
       end
 
       def transaction(**, &) = connection.transaction(**, &)
+
+      # Forgets the resolved settings and the connection (tests, console).
+      def reset!
+        @connection&.disconnect
+        @connection = nil
+        @settings = nil
+      end
+
+      # True when the table isn't there — one catalog query, nothing logged
+      # (Sequel's table_exists? probes with a failing SELECT).
+      def table_missing?(db, table)
+        name = table.to_s
+        case db.database_type
+        when :postgres then db.get(Sequel.function(:to_regclass, db.literal(table))).nil?
+        when :mysql
+          db[Sequel[:information_schema][:tables]].where(table_schema: Sequel.function(:database),
+                                                         table_name: name).empty?
+        when :sqlite then db[:sqlite_master].where(type: %w[table view], name: name).empty?
+        else !db.table_exists?(table)
+        end
+      end
+
+      private
+
+      def configure(db)
+        extensions = config.extensions || (postgres?(db) ? %i[pg_json pg_array] : [])
+        db.extension(*extensions) unless extensions.empty?
+        db.log_warn_duration = config.slow_query_ms / 1000.0 if config.slow_query_ms
+        db.loggers << QueryLogger.new(GemStack.logger, queries: config.log_queries)
+        db.sql_log_level = :debug
+      end
+
+      def open_database(options)
+        Sequel.connect(**options)
+      rescue Sequel::AdapterNotFound, LoadError => e
+        gem_name = Configuration::DRIVER_GEMS.fetch(options[:adapter], options[:adapter])
+        raise ConfigurationError, "#{options[:adapter]} needs gem \"#{gem_name}\" in the Gemfile (#{e.message})"
+      end
+
+      def adapter_options(adapter, database)
+        timeout = config.statement_timeout && Integer(config.statement_timeout)
+        case adapter
+        when "postgres" then timeout ? { connect_sqls: ["SET statement_timeout = #{timeout}"] } : {}
+        when "mysql2", "trilogy"
+          sqls = timeout ? ["SET SESSION max_execution_time = #{timeout}"] : []
+          { encoding: "utf8mb4", connect_sqls: sqls }
+        when "sqlite"
+          # Several Puma threads share the file: wait for the write lock instead
+          # of failing, and let readers work while one connection writes.
+          sqls = database == ":memory:" ? [] : ["PRAGMA journal_mode = WAL", "PRAGMA synchronous = NORMAL"]
+          { timeout: 5_000, connect_sqls: sqls }
+        else {}
+        end
+      end
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gemstack-db
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Shoaib Malik
@@ -15,42 +15,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.2.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.2.1
 - !ruby/object:Gem::Dependency
   name: gemstack-schema
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.2.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
-- !ruby/object:Gem::Dependency
-  name: pg
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.5'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.5'
+        version: 0.2.1
 - !ruby/object:Gem::Dependency
   name: sequel
   requirement: !ruby/object:Gem::Requirement
@@ -75,10 +61,12 @@ files:
 - LICENSE.txt
 - README.md
 - lib/gemstack/db.rb
+- lib/gemstack/db/configuration.rb
 - lib/gemstack/db/errors.rb
 - lib/gemstack/db/json_compat.rb
 - lib/gemstack/db/migrator.rb
 - lib/gemstack/db/model.rb
+- lib/gemstack/db/schema_types.rb
 - lib/gemstack/db/tasks.rb
 - lib/gemstack/db/testing.rb
 homepage: https://github.com/gemstack-rb/gemstack
@@ -106,5 +94,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.20
 specification_version: 4
-summary: 'GemStack database: Sequel models, migrations and PostgreSQL defaults'
+summary: 'GemStack database: Sequel models and migrations for SQLite, PostgreSQL and
+  MySQL'
 test_files: []