gemstack-db 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4dfcb9cab762647a4a5b66a1b39a171654b2e90a4fa5fb51ce582a92866ec610
+  data.tar.gz: 11711623cf668ec45e2fc92e046e7fe8cf8592654e13cbbb334609bcbd103e51
+SHA512:
+  metadata.gz: 50f2dbc4310478ffc79f2239b0dcc630c169341be13a8f0189a8b977e74e226412c78be563cca57f0de862c7c31dde12169f6e14ce86e97f44bd65fb78e199b6
+  data.tar.gz: 64c0e1055cef2f98c087daf97f9a5890bf6aaf353ff6d3cf33f446fedaa6000fe59079dcd27f070b1cbe6a37f853682ad8419293a18dd7d19d50a2bcf9b2a4ff

data/CHANGELOG.md

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shoaib Malik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,28 @@
+# gemstack-db
+
+GemStack database: Sequel models, migrations and PostgreSQL defaults.
+
+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
+version.
+
+## Installation
+
+Optional module — added by `gemstack new` (unless --skip-database):
+
+```ruby
+gem "gemstack-db", "~> 0.1"
+```
+
+## Documentation
+
+- [Guide](https://github.com/gemstack-rb/gemstack/blob/main/docs/models.md)
+- [All guides](https://github.com/gemstack-rb/gemstack/tree/main/docs) ·
+  [Architecture](https://github.com/gemstack-rb/gemstack/blob/main/ARCHITECTURE.md)
+
+Source, issues and pull requests: [gemstack-rb/gemstack](https://github.com/gemstack-rb/gemstack)
+(this gem lives in `gems/gemstack-db`).
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/gemstack/db/errors.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module GemStack
+  module DB
+    # Gives Sequel/PostgreSQL errors their HTTP meaning via GemStack::ErrorMapping
+    # (no dependency on the HTTP layer):
+    #
+    #   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
+    #   row still referenced (FK)  → 409 conflict
+    #   database unreachable       → 503 service_unavailable
+    module Errors
+      KEY_DETAIL = /Key \(([^)]+)\)=/
+
+      module_function
+
+      def install!
+        install_record_errors!
+        install_constraint_errors!
+        ErrorMapping.register(Sequel::DatabaseConnectionError) { ServiceUnavailable.new("Database unavailable") }
+        ErrorMapping.register(Sequel::PoolTimeout) { ServiceUnavailable.new("Database busy, try again") }
+      end
+
+      def install_record_errors!
+        ErrorMapping.register(Sequel::NoMatchingRow) do |error|
+          model = error.respond_to?(:dataset) && error.dataset.respond_to?(:model) ? error.dataset.model : nil
+          RecordNotFound.new(model&.name ? "#{model.name} not found" : "Record not found")
+        end
+        ErrorMapping.register(Sequel::ValidationFailed) do |error|
+          ValidationError.new(errors: stringify(error.errors))
+        end
+        ErrorMapping.register(Sequel::InvalidValue) do |error|
+          ValidationError.new(error.message.sub(/\A.*?: /, "Invalid value: "), code: "invalid_value")
+        end
+        ErrorMapping.register(Sequel::MassAssignmentRestriction) do |error|
+          BadRequest.new(error.message, code: "unknown_attribute")
+        end
+      end
+
+      def install_constraint_errors!
+        ErrorMapping.register(Sequel::UniqueConstraintViolation) do |error|
+          field_error(columns(error), "is already taken") || Conflict.new("Record already exists")
+        end
+        ErrorMapping.register(Sequel::NotNullConstraintViolation) do |error|
+          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")
+            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")
+          end
+        end
+        ErrorMapping.register(Sequel::CheckConstraintViolation) do
+          ValidationError.new("A value violates a database constraint", code: "constraint_violation")
+        end
+      end
+
+      def stringify(errors) = errors.to_h { |key, messages| [Array(key).join(","), Array(messages)] }
+
+      def field_error(names, message)
+        return nil if names.empty?
+
+        ValidationError.new(errors: names.to_h { |name| [name, [message]] })
+      end
+
+      def pg_error(error) = error.respond_to?(:wrapped_exception) ? error.wrapped_exception : nil
+
+      def columns(error)
+        if defined?(PG::PG_DIAG_MESSAGE_DETAIL)
+          detail = pg_error(error)&.result&.error_field(PG::PG_DIAG_MESSAGE_DETAIL)
+        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]
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end
+
+GemStack::DB::Errors.install!

data/lib/gemstack/db/json_compat.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module GemStack
+  module DB
+    # Sequel (5.108 and earlier) parses JSON/JSONB columns with
+    # JSON.parse(json, create_additions: false), an option json 3.0 removed, so
+    # every jsonb read raises ArgumentError. JSON.parse never creates additions,
+    # so dropping the option keeps Sequel's behaviour (DECISIONS D-041).
+    module JSONCompat
+      def parse_json(json) = JSON.parse(json)
+
+      def self.install!
+        return unless Gem::Version.new(JSON::VERSION) >= Gem::Version.new("3.0")
+
+        Sequel.singleton_class.prepend(self)
+      end
+    end
+  end
+end
+
+GemStack::DB::JSONCompat.install!

data/lib/gemstack/db/migrator.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+Sequel.extension :migration
+
+module GemStack
+  module DB
+    # Timestamped Sequel migrations in db/migrations:
+    #
+    #   # db/migrations/20260928120000_create_products.rb
+    #   Sequel.migration do
+    #     change do
+    #       create_table(:products) do
+    #         primary_key :id, type: :Bignum
+    #         String :name, null: false
+    #         timestamptz :created_at, null: false
+    #       end
+    #     end
+    #   end
+    #
+    # Migrations are plain Sequel migrations; the full Sequel schema DSL applies.
+    class Migrator
+      Entry = Struct.new(:version, :name, :file, :applied, keyword_init: true)
+
+      attr_reader :db, :path
+
+      def initialize(database = DB.connection, path = GemStack.root.join(DB.config.migrations_path).to_s)
+        @db = database
+        @path = path.to_s
+      end
+
+      def files = Dir.glob(File.join(path, "*.rb"))
+
+      # Applies pending migrations (or migrates up/down to target). Returns the
+      # file names that were applied or reverted.
+      def migrate(target: nil)
+        before = applied
+        run(target)
+        after = applied
+        (after - before) + (before - after)
+      end
+
+      # Reverts the last `steps` applied migrations.
+      def rollback(steps: 1)
+        versions = applied.map { |file| version_of(file) }.sort
+        return [] if versions.empty?
+
+        target = versions[-(steps + 1)] || 0
+        migrate(target: target)
+      end
+
+      def status
+        done = applied
+        files.map do |file|
+          base = File.basename(file)
+          Entry.new(version: version_of(base), name: base.sub(/\A\d+_/, "").delete_suffix(".rb"), file: base,
+                    applied: done.include?(base))
+        end.sort_by(&:version)
+      end
+
+      def pending = status.reject(&:applied)
+      def pending? = !pending.empty?
+
+      def applied
+        return [] unless db.table_exists?(:schema_migrations)
+
+        db[:schema_migrations].select_map(:filename)
+      end
+
+      private
+
+      def run(target)
+        return unless File.directory?(path)
+
+        Sequel::TimestampMigrator.new(db, path, target: target).run
+      end
+
+      def version_of(file) = File.basename(file)[/\A\d+/].to_i
+    end
+  end
+end

data/lib/gemstack/db/model.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module GemStack
+  # Base class for models: Sequel::Model plus GemStack conventions.
+  #
+  #   class Product < GemStack::Model
+  #     field :name, :string, null: false, size: 120
+  #     field :price, :decimal, null: false, gt: 0
+  #     field :active, :boolean, null: false, default: true
+  #
+  #     validates :name, format: /\A\S/
+  #     belongs_to :category
+  #     has_many :reviews
+  #   end
+  #
+  # `field` declarations are metadata that drive validations, request
+  # schemas (Product.input_schema), serializer types and TypeScript. The
+  # database schema itself comes from migrations; everything Sequel offers
+  # (datasets, associations, hooks, plugins) is available unchanged.
+  #
+  # Created with Class.new on purpose: an *anonymous* subclass stops Sequel
+  # from binding GemStack::Model itself to a "models" table (which would need
+  # a database connection just to require this file).
+  Model = Class.new(Sequel::Model) # rubocop:disable Style/EmptyClassDefinition
+
+  class Model
+    Field = Struct.new(:name, :type, :options)
+
+    FIELD_RULES = %i[null default size gt gte lt lte in format].freeze
+
+    plugin :timestamps, update_on_create: true
+    plugin :validation_helpers
+
+    # A model may load before its migration has run (e.g. while generating the
+    # API contract right after `generate resource`); queries still fail
+    # clearly with "relation does not exist" (DECISIONS D-024).
+    self.require_valid_table = false
+
+    class << self
+      def gemstack_fields
+        @gemstack_fields ||= superclass.respond_to?(:gemstack_fields) ? superclass.gemstack_fields.dup : {}
+      end
+
+      # Declares a field. Options: null: false (required), default:, size:
+      # (max length), gt/gte/lt/lte, in:, format:. Types are GemStack::Types.
+      def field(name, type, **options)
+        Types.fetch(type)
+        unknown = options.keys - FIELD_RULES
+        raise ArgumentError, "unknown field option(s) #{unknown.inspect} for #{name}" unless unknown.empty?
+
+        @input_schemas = nil
+        gemstack_fields[name.to_sym] = Field.new(name.to_sym, Types::CLASS_ALIASES.fetch(type, type).to_sym,
+                                                 options.freeze)
+      end
+
+      def gemstack_validations
+        @gemstack_validations ||=
+          superclass.respond_to?(:gemstack_validations) ? superclass.gemstack_validations.dup : []
+      end
+
+      # validates :name, :sku, presence: true, length: { max: 40 }, format: /\A[A-Z]/,
+      #           inclusion: { in: %w[a b] }, numericality: { gt: 0 }, uniqueness: true
+      def validates(*names, **rules)
+        unknown = rules.keys - %i[presence length format inclusion numericality uniqueness]
+        raise ArgumentError, "unknown validation(s) #{unknown.inspect}" unless unknown.empty?
+
+        gemstack_validations << [names.map(&:to_sym), rules]
+      end
+
+      # A request schema derived from the field declarations (memoized):
+      #   accepts :create, with: Product.input_schema
+      def input_schema(only: nil, except: nil)
+        key = [only, except]
+        (@input_schemas ||= {})[key] ||= Schema.from_model(
+          self, only: only, except: except, type_name: "#{name.to_s.split("::").join}Input"
+        )
+      end
+
+      # find(42) raises GemStack::DB::RecordNotFound (404) when missing.
+      # With a Hash or block it behaves like Sequel's find (nil when missing).
+      def find(*args, &block)
+        return super if block || args.size != 1 || args.first.is_a?(Hash)
+
+        id = args.first
+        record = valid_primary_key?(id) ? with_pk(id) : nil
+        record || raise(DB::RecordNotFound, "#{name} #{id} not found")
+      end
+
+      def find_by(conditions) = first(conditions)
+      def find_by!(conditions) = first(conditions) || raise(DB::RecordNotFound, "#{name} not found")
+
+      alias create! create
+
+      # Associations with familiar names; the Sequel names work too.
+      def belongs_to(name, **) = many_to_one(name, **)
+      def has_many(name, **) = one_to_many(name, **) # rubocop:disable Naming/PredicatePrefix
+      def has_one(name, **) = one_to_one(name, **) # rubocop:disable Naming/PredicatePrefix
+      def has_and_belongs_to_many(name, **) = many_to_many(name, **) # rubocop:disable Naming/PredicatePrefix
+
+      private
+
+      # 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.
+      def get_db_schema(reload = reload_db_schema?)
+        return super unless missing_table?
+
+        set_columns(nil)
+        {}
+      end
+
+      def missing_table?
+        return false unless @dataset && db.database_type == :postgres
+
+        db.get(Sequel.function(:to_regclass, db.literal(dataset.first_source_table))).nil?
+      rescue Sequel::Error
+        false
+      end
+
+      def valid_primary_key?(id)
+        return true unless integer_primary_key?
+
+        id.is_a?(Integer) || (id.is_a?(String) && id.match?(/\A\d{1,19}\z/))
+      end
+
+      def integer_primary_key?
+        return @integer_primary_key if defined?(@integer_primary_key)
+
+        @integer_primary_key = primary_key.is_a?(Symbol) && db_schema.dig(primary_key, :type) == :integer
+      end
+    end
+
+    alias update! update
+
+    # Identifies this version of the record, for ETags (Controller#stale?) and
+    # cache keys: "product/42-1759052159.123456".
+    def cache_key
+      stamp = respond_to?(:updated_at) && updated_at ? "-#{updated_at.to_f}" : ""
+      "#{Inflector.underscore(self.class.name.to_s)}/#{pk}#{stamp}"
+    end
+
+    def validate
+      super
+      validate_fields
+      self.class.gemstack_validations.each { |names, rules| apply_validations(names, rules) }
+    end
+
+    # Models are never rendered implicitly: exposing every column is how
+    # APIs leak data. Define a serializer instead.
+    def as_json(*)
+      file = "#{Inflector.underscore(self.class.name)}_serializer.rb"
+      raise Error, "#{self.class.name} has no serializer. Create #{file} " \
+                   "in app/serializers (class #{self.class.name}Serializer < GemStack::Serializer)."
+    end
+
+    def to_json(*) = as_json
+
+    private
+
+    def validate_fields
+      self.class.gemstack_fields.each_value do |field|
+        opts = field.options
+        name = field.name
+        if opts[:null] == false && !opts.key?(:default)
+          if field.type == :boolean
+            validates_includes([true, false], name, message: "must be true or false")
+          else
+            validates_presence(name, message: "is required")
+          end
+        end
+        apply_rules(name, opts)
+      end
+    end
+
+    def apply_rules(name, opts)
+      if opts[:size].is_a?(Integer)
+        validates_max_length(opts[:size], name, message: "is too long (maximum #{opts[:size]} characters)",
+                                                allow_nil: true)
+      end
+      { gt: :>, gte: :>=, lt: :<, lte: :<= }.each do |key, operator|
+        next unless opts.key?(key)
+
+        words = { gt: "greater than", gte: "greater than or equal to", lt: "less than", lte: "less than or equal to" }
+        validates_operator(operator, opts[key], name, message: "must be #{words[key]} #{opts[key]}", allow_nil: true)
+      end
+      if opts[:in]
+        validates_includes(opts[:in], name, message: "must be one of: #{opts[:in].to_a.join(", ")}",
+                                            allow_nil: true)
+      end
+      validates_format(opts[:format], name, message: "is invalid", allow_nil: true) if opts[:format]
+    end
+
+    def apply_validations(names, rules)
+      names.each do |name|
+        validates_presence(name, message: "is required") if rules[:presence]
+        length = rules[:length]
+        if length
+          apply_rules(name, size: length[:max]) if length[:max]
+          if length[:min]
+            validates_min_length(length[:min], name, message: "is too short (minimum #{length[:min]} characters)",
+                                                     allow_nil: true)
+          end
+        end
+        apply_rules(name, format: rules[:format]) if rules[:format]
+        inclusion = rules[:inclusion]
+        apply_rules(name, in: inclusion.is_a?(Hash) ? inclusion[:in] : inclusion) if inclusion
+        numeric = rules[:numericality]
+        if numeric
+          validates_numeric(name, message: "must be a number", allow_nil: true)
+          apply_rules(name, numeric.slice(:gt, :gte, :lt, :lte)) if numeric.is_a?(Hash)
+        end
+        validates_unique(name, message: "is already taken") if rules[:uniqueness]
+      end
+    end
+  end
+end

data/lib/gemstack/db/tasks.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module GemStack
+  module DB
+    # Database lifecycle used by `gemstack db:*`.
+    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) }
+      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
+      end
+
+      def exists?(url = DB.config.url)
+        with_maintenance(url) { |db| db[:pg_database].where(datname: database_name(url)).any? }
+      end
+
+      # Returns :created or :exists.
+      def create(url = DB.config.url)
+        return :exists if exists?(url)
+
+        with_maintenance(url) { |db| db.run("CREATE DATABASE #{db.literal(Sequel.identifier(database_name(url)))}") }
+        :created
+      end
+
+      # Refuses outside development/test unless GEMSTACK_ALLOW_DB_DROP=1.
+      def drop(url = DB.config.url)
+        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)
+
+        DB.disconnect
+        with_maintenance(url) do |db|
+          db.run("DROP DATABASE #{db.literal(Sequel.identifier(database_name(url)))} WITH (FORCE)")
+        end
+        :dropped
+      end
+
+      def seed(path = GemStack.root.join(DB.config.seeds_path))
+        return false unless File.file?(path)
+
+        load path.to_s
+        true
+      end
+
+      def with_maintenance(url)
+        db = Sequel.connect(maintenance_url(url), max_connections: 1, test: true, keep_reference: false)
+        yield db
+      ensure
+        db&.disconnect
+      end
+    end
+  end
+end

data/lib/gemstack/db/testing.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "gemstack/db"
+require "securerandom"
+
+module GemStack
+  module DB
+    # Test support, used by the generated test/test_helper.rb:
+    #
+    #   require "gemstack/db/testing"
+    #   GemStack::DB::Testing.prepare!             # create + migrate the test database
+    #   GemStack::TestCase.include GemStack::DB::Testing::Transactions
+    module Testing
+      module_function
+
+      # Creates the test database if needed and applies pending migrations,
+      # so `gemstack test` works on a fresh checkout.
+      def prepare!
+        Tasks.create
+        Migrator.new.migrate
+      end
+
+      # Valid attribute values for a model, derived from its `field`
+      # declarations (types, size, gt/gte/lt/lte, in:). Unique-looking values
+      # use a sequence; `references` fields create the referenced record.
+      # Fields with a `format:` rule may need an override.
+      #
+      #   Product.create(GemStack::DB::Testing.sample_attributes(Product, name: "Lamp"))
+      def sample_attributes(model, overrides = {})
+        @sequence = (@sequence || 0) + 1
+        model.gemstack_fields.each_value.with_object({}) do |field, attrs|
+          attrs[field.name] = sample_value(model, field, @sequence)
+        end.merge(overrides)
+      end
+
+      # sample_attributes as JSON-ready values (for request bodies).
+      def sample_payload(model, overrides = {})
+        sample_attributes(model, overrides).transform_values do |value|
+          case value
+          when BigDecimal then value.to_s("F")
+          when Time then value.utc.iso8601
+          when Date then value.iso8601
+          else value
+          end
+        end
+      end
+
+      def sample_value(model, field, sequence)
+        opts = field.options
+        return Array(opts[:in]).first if opts[:in]
+
+        case field.type
+        when :string, :text then sample_string(field, opts, sequence)
+        when :integer, :bigint then bounded(opts, 1, step: 1).to_i
+        when :float then bounded(opts, 1.5, step: 1).to_f
+        when :decimal then BigDecimal(bounded(opts, BigDecimal("9.99"), step: 1).to_s)
+        when :boolean then true
+        when :date then Date.today
+        when :datetime then Time.now.utc.round
+        when :uuid then SecureRandom.uuid
+        when :json then { "sample" => true }
+        when :references then sample_reference(model, field)
+        end
+      end
+
+      def sample_string(field, opts, sequence)
+        value = "#{Inflector.humanize(field.name)} #{sequence}"
+        opts[:size].is_a?(Integer) ? value[0, opts[:size]] : value
+      end
+
+      def bounded(opts, value, step:)
+        value = opts[:gt] + step if opts[:gt] && value <= opts[:gt]
+        value = opts[:gte] if opts[:gte] && value < opts[:gte]
+        value = opts[:lt] - step if opts[:lt] && value >= opts[:lt]
+        value = opts[:lte] if opts[:lte] && value > opts[:lte]
+        value
+      end
+
+      def sample_reference(model, field)
+        reflection = model.association_reflections.values.find { |r| r[:key] == field.name }
+        target = reflection&.associated_class ||
+                 Object.const_get(Inflector.camelize(field.name.to_s.delete_suffix("_id")))
+        target.create(sample_attributes(target)).pk
+      end
+
+      # Runs every test inside a transaction that is rolled back afterwards.
+      # Requests made through rack-test run on the same thread, so they see
+      # (and roll back) the same data. Nested GemStack.transaction calls
+      # become savepoints.
+      module Transactions
+        def run(...)
+          result = nil
+          DB.connection.transaction(rollback: :always, auto_savepoint: true) { result = super }
+          result
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/db.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "sequel"
+require "json"
+require "gemstack/core"
+require "gemstack/schema"
+
+require_relative "db/json_compat"
+
+module GemStack
+  # PostgreSQL through Sequel (DECISIONS D-018). Optional: add
+  # `gem "gemstack-db"` to the Gemfile (new apps include it by default).
+  #
+  #   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.
+      setting :pool_size, default: lambda {
+        Integer(ENV.fetch("GEMSTACK_DB_POOL") { ENV.fetch("GEMSTACK_MAX_THREADS", 5) })
+      }
+      setting :pool_timeout, default: 5
+      setting :migrations_path, default: "db/migrations"
+      setting :seeds_path, default: "db/seeds.rb"
+      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).
+      setting :statement_timeout, default: nil
+      setting :extensions, default: %i[pg_json pg_array]
+      # Extra options passed to Sequel.connect.
+      setting :options, default: {}
+    end
+
+    class RecordNotFound < NotFound; end
+
+    # 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/
+
+      def initialize(logger, queries:)
+        @logger = logger
+        @queries = queries
+      end
+
+      def debug(message) = (@logger.debug(message) if @queries)
+      def info(message) = @logger.info(message)
+      def warn(message) = @logger.warn(message)
+      def error(message) = (@logger.error(message) unless PROBE.match?(message.to_s))
+    end
+
+    @mutex = Mutex.new
+
+    class << self
+      def config = GemStack.config.db
+
+      def connection
+        @connection || @mutex.synchronize { @connection ||= connect }
+      end
+
+      def connected? = !@connection.nil?
+
+      # 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
+        Sequel::Model.db = db
+        db
+      end
+
+      # Closes pooled connections (e.g. before Puma forks workers). The
+      # Database object stays in place and reconnects lazily: models hold a
+      # reference to it, so replacing it would split them from GemStack.db.
+      def disconnect
+        @connection&.disconnect
+      end
+
+      def transaction(**, &) = connection.transaction(**, &)
+    end
+  end
+
+  # A model base class bound to an explicit table, like Sequel::Model(:table):
+  #   class Item < GemStack::Model(:inventory_items)
+  def self.Model(source) = Model.Model(source) # rubocop:disable Naming/MethodName
+
+  class << self
+    def db = DB.connection
+    def transaction(**, &) = DB.transaction(**, &)
+  end
+end
+
+require_relative "db/model"
+require_relative "db/errors"
+require_relative "db/migrator"
+require_relative "db/tasks"
+
+GemStack::Config.namespace(:db, GemStack::DB::Config)
+
+GemStack::Plugins.register(:db) do |app|
+  GemStack::DB.connection
+  app.on_shutdown { GemStack::DB.disconnect } if app.respond_to?(:on_shutdown)
+
+  # A friendly nudge in development; never blocks boot.
+  if GemStack.env.development?
+    begin
+      pending = GemStack::DB::Migrator.new.pending
+      unless pending.empty?
+        GemStack.logger.warn("#{pending.size} pending migration(s) — run `gemstack db:migrate`",
+                             first: pending.first.file)
+      end
+    rescue Sequel::Error
+      nil # database not reachable yet; requests will report it
+    end
+  end
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: gemstack-db
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shoaib Malik
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gemstack-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: gemstack-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  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'
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.80'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.80'
+email:
+- gemstack26@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/gemstack/db.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/tasks.rb
+- lib/gemstack/db/testing.rb
+homepage: https://github.com/gemstack-rb/gemstack
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/gemstack-rb/gemstack/tree/main/gems/gemstack-db
+  changelog_uri: https://github.com/gemstack-rb/gemstack/blob/main/gems/gemstack-db/CHANGELOG.md
+  bug_tracker_uri: https://github.com/gemstack-rb/gemstack/issues
+  documentation_uri: https://github.com/gemstack-rb/gemstack/tree/main/docs
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'GemStack database: Sequel models, migrations and PostgreSQL defaults'
+test_files: []