pgi 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 00a4f48d4d9337019f30a191e60474cb75ff45a19c1653d0bf8a1897dd6551bf
+  data.tar.gz: 2187c091a690e52b9d66efdbe7038932d6cc783aab8d95516246fe0ca564d48d
+SHA512:
+  metadata.gz: 2cd4e11c2341f5151ba6b09549221e6345f0f9d1442c36d9631b14242815b95b470096524229e94296bdc35811f966eb5ff4a7250c1de442678d73cd498f81b6
+  data.tar.gz: 267ba7b3dc84f507b6d47407cc77a42e6bc3a42fad1797c36494a90d672a2cf5a1dffed85ddf3953dc55666e00e37cdf8e08c9883fd1a8bce761a3b078897d6a

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# CHANGELOG
+
+## 1.0.0
+
+First public release.
+
+- `PGI::DB` — pooled PostgreSQL access with auto-healing: lost connections and
+  pool checkout timeouts share a configurable retry budget (`max_retries`,
+  `retry_wait`; `Float::INFINITY` rides out arbitrarily long outages)
+- `PGI::Connection` — thin `PG::Connection` wrapper with lazily auto-prepared
+  statements and typed results (uuid, json/jsonb with symbolized keys)
+- `PGI::Dataset` — super lightweight repository toolkit: CRUD, scoped queries
+  and keyset pagination with a scalar id cursor
+- `PGI::SchemaMigrator` — plain up/down SQL migrations tracked in a
+  `schema_migrations` table

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2022 Coherify ApS
+
+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,117 @@
+# PGI
+
+PGI is a simple and convenient interface for PostgreSQL with a few enhancements.
+
+## PGI::DB
+
+The `PGI::DB` handles connections to a PostgreSQL databases. It features...
+
+* Connection Pool
+* Connection auto-healing capabilities
+
+Usage:
+
+```ruby
+DB = PGI::DB.configure do |options|
+  options.pool_size = 1
+  options.pool_timeout = 5
+  options.pg_conn_uri = "postgresql://pgi:password@localhost:5432/pgi_test"
+  options.logger = Logger.new($stdout)
+  options.max_retries = 30 # optional (default: 30, ~1 min of patience) - shared retry budget for lost connections
+                           # and pool checkout timeouts; Float::INFINITY rides out any outage
+  options.retry_wait = 2   # optional (default: 2) - seconds between reconnection attempts
+end
+
+DB.exec_stmt("my_stmt", "SELECT 1+1")
+```
+
+## PGI::Dataset
+
+The `PGI::Dataset` is a super light weight ActiveRecord::Relation replacement. It delivers a clean and simple querying interface:
+
+* `#select(column1, ...)` allows you to limit the result set to only contain specified columns
+* `#where(...)` - can only be called once per query, so combine all conditions in a single call. Two forms:
+  * `#where("name = ? AND age > ?", ['joe', 21])` - a string clause with placeholders (`?` or `$1`)
+  * `#where(name: 'joe')` - as a Hash (multiple keys are concatenated with an ' AND ')
+* `#order(:column, <:asc|:desc>)` - sort result set by column and direction, can be invoked multiple times
+* `#limit(<num>)` - limits the result set to the specified number of records
+* `#first` - get the first record in a set
+* `#all`- get an array of records
+* `#count`- get the number of rows in a table
+* `#page(cursor, size, sort_by, sort_dir)` - keyset pagination; pass `nil` for the first page, then the **id of the last row** as the cursor for each subsequent page
+
+```ruby
+class Repository
+  extend PGI::Dataset[DB, :members, scope: "deleted_at IS NULL"]
+end
+```
+
+```sql
+-- Each column used as sort_by in page() needs a composite index on (column, id).
+-- Two separate single-column indexes are not sufficient — Postgres needs
+-- the combined (column, id) ordering to seek directly to the cursor position.
+CREATE INDEX ON members (name ASC, id ASC);
+CREATE INDEX ON members (created_at ASC, id ASC);
+```
+
+```ruby
+# First page — sorted by name
+page1 = Repository.page(nil, 20, :name, :asc)
+
+# Next page — pass the id of the last row as the cursor
+page2 = Repository.page(page1.last["id"], 20, :name, :asc)
+```
+
+Generated SQL for page 2 (`sort_by != :id`):
+```sql
+SELECT * FROM members
+WHERE deleted_at IS NULL
+  AND (name, id) > (SELECT name, id FROM members WHERE id = $1)
+ORDER BY name ASC, id ASC
+LIMIT 20
+```
+
+Generated SQL for page 2 (`sort_by == :id`):
+```sql
+SELECT * FROM members
+WHERE deleted_at IS NULL
+  AND id > $1
+ORDER BY id ASC
+LIMIT 20
+```
+
+### How keyset pagination works
+
+`#page` fetches rows at constant cost regardless of page depth. The cursor is always the scalar `id` of the last row from the previous page.
+
+- **Sorting by id** — `WHERE id > $cursor ORDER BY id`. Simple seek on the primary key index.
+- **Sorting by another column** — generates a composite subquery cursor so pages are globally sorted:
+  ```sql
+  WHERE (sort_col, id) > (SELECT sort_col, id FROM table WHERE id = $cursor)
+  ORDER BY sort_col, id
+  ```
+  Postgres resolves the subquery via the primary-key index (a single fast lookup), then uses the composite `(sort_col, id)` index to seek directly to that position and scan forward. The two separate single-column indexes are not equivalent — a composite B-tree index is required so that Postgres can seek to an exact `(sort_col, id)` position rather than scanning and filtering.
+
+`LIMIT/OFFSET` scans and discards all prior rows on every page request — cost grows linearly with depth. Keyset pagination does not.
+
+### Constraints
+
+- **`sort_by` columns must be `NOT NULL`.** SQL row comparison with NULL yields NULL, so rows with a NULL sort value are silently excluded from every cursor page — and if the anchor row itself has a NULL sort value, the next page comes back empty mid-stream.
+- **Hard-deleting an anchor row ends that pagination sequence.** The anchor lookup is by primary key; if the row is gone, the next page is empty and indistinguishable from the end of the result set. Soft deletion via a `scope:` (e.g. `deleted_at IS NULL`) is safe — the anchor lookup deliberately bypasses the scope, so a row that left the scope between pages still anchors correctly.
+- **Every table is expected to have a unique, totally ordered `id`** (SERIAL, UUIDv7, ...) — it is the tie-breaker that makes pages deterministic, and the whole `Dataset` interface assumes it.
+
+## Documentation
+
+Dependencies:
+
+* https://github.com/ged/ruby-pg
+* https://github.com/mperham/connection_pool
+
+Create developer/test DB:
+
+```
+sudo su - postgres
+psql -c "CREATE ROLE pgi WITH login password 'password';"
+createdb --owner pgi pgi_test
+psql pgi_test -c 'CREATE EXTENSION IF NOT EXISTS "pgcrypto";'
+```

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/pgi/connection.rb

@@ -0,0 +1,69 @@
+require "pg"
+
+module PGI
+  class Connection
+    class JSONDecoder < PG::SimpleDecoder
+      def decode(string, _tuple = nil, _field = nil)
+        ::JSON.parse(string, quirks_mode: true, symbolize_names: true)
+      end
+    end
+
+    # Create instance
+    #
+    # @param pool [ConnectionPool]
+    # @param logger [Logger]
+    def initialize(logger:, conn_uri: nil, conn: nil)
+      @logger = logger
+
+      @conn = conn || PG::Connection.new(conn_uri).tap do |new_conn|
+        regi = PG::BasicTypeRegistry.new.register_default_types
+
+        regi.register_type 0, "uuid", PG::TextEncoder::String, PG::TextDecoder::String
+        regi.register_type 0, "json", PG::TextEncoder::JSON, JSONDecoder
+        regi.alias_type(0, "jsonb", "json")
+
+        new_conn.type_map_for_results = PG::BasicTypeMapForResults.new(new_conn, registry: regi)
+        new_conn.type_map_for_queries = PG::BasicTypeMapForQueries.new(new_conn, registry: regi)
+      end || raise("no connection provided")
+    end
+
+    # Execute a prepared statement. Statements are auto-created with fallback to exec_params
+    #
+    # @example
+    #   .exec_stmt("users_by_name", "SELECT * FROM users WHERE name = $1", ["joe"])
+    #
+    # @param stmt_name [String] name of statement, must be unique for the query
+    # @param sql [String] SQL query
+    # @param params [Array] list of params
+    def exec_stmt(stmt_name, sql, params = [])
+      if [PG::PQTRANS_ACTIVE, PG::PQTRANS_INTRANS, PG::PQTRANS_INERROR].include?(@conn.transaction_status)
+        @logger&.debug "Unable to use statements within a transaction - falling back to #exec_params"
+        return @conn.exec_params(sql, params)
+      end
+
+      begin
+        @conn.exec_prepared(stmt_name, params)
+      rescue PG::InvalidSqlStatementName
+        @logger&.debug "Creating missing prepared statement: \"#{stmt_name}\""
+        @conn.prepare(stmt_name, sql)
+        retry
+      end
+    rescue PG::Error => e
+      # Log at the source so failures are traceable regardless of how the
+      # consumer handles the exception
+      @logger&.error(e)
+      raise
+    end
+
+    # Pass the remainder of methods on to a PG::Connection
+    #
+    # @See https://deveiate.org/code/pg/PG/Connection.html
+    def method_missing(name, ...)
+      @conn.__send__(name, ...)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @conn.respond_to?(name, include_private) || super
+    end
+  end
+end

data/lib/pgi/dataset/query.rb

@@ -0,0 +1,204 @@
+require "digest/md5"
+require "pgi/dataset/utils"
+
+module PGI
+  module Dataset
+    class Query
+      # Create instance of Query
+      #
+      # @param database [PGI::DB] a configured instance of DB
+      # @param table [Symbol] the name of the database table to operate on
+      # @param command [String] the command part of the query (default: `SELECT * FROM <table>`)
+      # @param options [Hash] hash of options: scope, where, params, limit, order, returning
+      # @return [Query] new instance of Query
+      def initialize(database, table, command, **options)
+        @database  = database
+        @table     = table
+        @command   = command || "SELECT * FROM #{@table}"
+        @scope     = options.fetch(:scope, nil)
+        @where     = options.fetch(:where, nil)
+        @params    = options.fetch(:params, [])
+        @order     = options.fetch(:order, {})
+        @limit     = options.fetch(:limit, 10)
+        @returning = options.fetch(:returning, nil)
+      end
+
+      # Adds a WHERE clause to the query - can only be called once per query,
+      # so combine all conditions in a single call
+      #
+      # @param clause [Hash, String] a Hash of table columns and values - or a string with placeholders
+      # @param params [Array] list of values for placeholder substitution
+      # @raise [RuntimeError] if a WHERE clause is already set
+      # @return [Query] return the Query instance (for method chaining)
+      def where(clause = nil, params = [])
+        return self unless clause
+        return self if clause.empty?
+
+        raise "WHERE clause already set - combine conditions in a single call" if @where
+
+        case clause
+        when Hash
+          clause = clause.map do |k, v|
+            @params << v
+            "#{Utils.sanitize_columns(k, @table).first} = $#{@params.size}"
+          end.join(" AND ")
+        when String
+          raise "Use placeholders in WHERE clause" if clause =~ /=(?!\s*[?$])/
+
+          offset = @params.size
+          @params += params
+          clause = clause.gsub(/([=<>]{1}\s{0,})(\?)/).with_index { |_, i| "#{Regexp.last_match(1)}$#{offset + i + 1}" }
+        else
+          raise "WHERE clause can either be a Hash or a String"
+        end
+
+        @where = clause
+
+        self
+      end
+
+      # Adds a ORDER BY clause to the query - suports multiple calls to the method
+      #
+      # @param column [Symbol] the columns
+      # @param direction [Symbol] the direction the sort should take - can be either `:desc` or `:asc`
+      # @raise [RuntimeError] if the direction param is invalid
+      # @return [Query] return the Query instance (for method chaining)
+      def order(column, direction = :asc)
+        raise "Invalid ORDER BY direction: #{direction.inspect}" unless %i[asc desc].include?(direction)
+
+        @order[Utils.sanitize_columns(column, @table)] = direction.to_s.upcase
+        self
+      end
+
+      # Adds a LIMIT clause to the query
+      #
+      # @param direction [Integer] the direction the sort should take - can be either `:desc` or `:asc`
+      # @raise [RuntimeError] if the direction param is invalid
+      # @return [Query] return the Query instance (for method chaining)
+      def limit(number)
+        raise "LIMIT must be an integer or nil" unless number.nil? || number.is_a?(Integer)
+
+        @limit = number
+        self
+      end
+
+      # Apply keyset pagination: orders by (sort_by, id) and, when a cursor id is
+      # given, seeks past that row. A nil cursor_id is the first page. The cursor
+      # predicate combines with any existing WHERE clause, so call it after #where.
+      # For sort_by == :id:    WHERE id > $cursor_id
+      # For sort_by != :id:    WHERE (sort_col, id) > (SELECT sort_col, id FROM table WHERE id = $cursor_id)
+      # Do not combine with a conflicting #order call — pages are only correct when
+      # the leading sort columns match the cursor predicate.
+      #
+      # @param sort_by [Symbol] the sort column
+      # @param cursor_id [*, nil] id of the last row from the previous page, or nil for the first page
+      # @param sort_dir [Symbol] :asc or :desc
+      # @return [Query] return the Query instance (for method chaining)
+      def keyset(sort_by, cursor_id, sort_dir)
+        order(sort_by, sort_dir)
+        order(:id, sort_dir) unless sort_by.to_sym == :id
+        return self unless cursor_id
+
+        op     = sort_dir == :asc ? ">" : "<"
+        id_col = Utils.sanitize_columns(:id, @table).first
+        @params << cursor_id
+
+        clause =
+          if sort_by.to_sym == :id
+            "#{id_col} #{op} $#{@params.size}"
+          else
+            sort_col = Utils.sanitize_columns(sort_by, @table).first
+            "(#{sort_col}, #{id_col}) #{op} (SELECT #{sort_col}, #{id_col} FROM #{@table} WHERE #{id_col} = $#{@params.size})"
+          end
+
+        @where = @where ? "#{clause} AND (#{@where})" : clause
+        self
+      end
+
+      # Get the Query SQL string prepared for execution
+      #
+      # @return [String] Query as a SQL string
+      def sql
+        # Simple Scope implementation
+        scope = @scope.dup
+        scope << " AND " if scope && @where
+
+        command = @command.dup
+        command << " WHERE #{scope}#{@where}" if @where || scope
+        command << " ORDER BY #{Array(@order).map { |x| x.join(" ") }.join(", ")}" unless @order.empty?
+        command << " LIMIT #{@limit}" if @limit
+        command << " RETURNING *" if @command =~ /^UPDATE|INSERT|DELETE/
+        command
+      end
+
+      # Get the params for placeholder substitution
+      #
+      # @return [Array] params
+      attr_reader :params
+
+      # Get the first record in a result set
+      #
+      # @return [Hash]
+      def first
+        limit(1)
+        @database
+          .exec_stmt(Utils.stmt_name(@table, sql), sql, params)
+          .first
+      end
+
+      # Get all the records in a result set
+      #
+      # @return [Array] Array of records as Hashes
+      def to_a
+        @database
+          .exec_stmt(Utils.stmt_name(@table, sql), sql, params)
+          .to_a
+      end
+
+      # Loop through records in a result set
+      def each(&)
+        @database
+          .exec_stmt(Utils.stmt_name(@table, sql), sql, params)
+          .each(&)
+      end
+
+      # Explain some query
+      #
+      # @return [String] Formatted string explaining query plan
+      def explain
+        explain_sql = "EXPLAIN " << sql.dup.tap do |s|
+          params.each_with_index do |x, i|
+            x =
+              case x
+              when String
+                "'#{x}'"
+              else
+                x
+              end
+
+            s.gsub!("$#{i + 1}", x.to_s)
+          end
+        end
+
+        @database.exec(explain_sql)&.values&.join("\n")
+      end
+
+      # Get the number of records in a result set
+      #
+      # @return [Integer]
+      def count
+        @command = "SELECT COUNT(*) FROM #{@table}"
+        @order   = {}
+        first&.fetch("count", 0)
+      end
+
+      # Get a string representation of the instance
+      #
+      # @return [String]
+      def to_s
+        "#<PGI::Dataset::Query:#{object_id} @sql=#{sql} @params=#{params}>"
+      end
+      alias inspect to_s
+    end
+  end
+end

data/lib/pgi/dataset/utils.rb

@@ -0,0 +1,67 @@
+require "digest/md5"
+
+module PGI
+  module Dataset
+    module Utils
+      class << self
+        # Strips the fields to not insert off a hash
+        #
+        # @param attr [Hash] input hash
+        # @return [Hash] stripped hash
+        def strip_uninsertable(attr)
+          attr.except(:id, :created_at, :updated_at)
+        end
+
+        # Strips the fields to not update off a hash
+        #
+        # @param attr [Hash] input hash
+        # @return [Hash] stripped hash
+        def strip_unupdateable(attr)
+          attr.except(:created_at, :updated_at)
+        end
+
+        # Get a unique statement name for the Query
+        #
+        # @param table [String] table name
+        # @param sql [String] SQL query
+        # @return [String] a statement name
+        def stmt_name(table, sql)
+          "#{table}_#{Digest::MD5.hexdigest(sql)}"
+        end
+
+        # Get a sanitized column name(s)
+        #
+        # @param columns [String|Array] the column name(s) to sanitize
+        # @param table [Symbol] the table name
+        # @return [Array] list of sanitized column names
+        def sanitize_columns(columns, table = nil)
+          Array(columns).map do |col|
+            sanitize_column(col, table)
+          end
+        end
+
+        # Get a sanitized column name
+        #
+        # @param columns [String|Array] the column name(s) to sanitize
+        # @param table [Symbol] the table name
+        # @return [Array] list of sanitized column names
+        def sanitize_column(col, table = nil)
+          raise "invalid column name: #{col.inspect}" unless valid_column?(col)
+
+          return "*" if col == "*"
+
+          table ? %("#{table}"."#{col}") : %("#{col}")
+        end
+
+        # Validates a column name
+        #
+        # @param columns [Symbol] the column name(s) to sanitize
+        # @return [Boolean] true if valid, otherwise false
+        def valid_column?(column)
+          col = column.to_s
+          col == "*" || col =~ /\A[a-z_][a-z0-9_]*\z/i
+        end
+      end
+    end
+  end
+end

data/lib/pgi/dataset.rb

@@ -0,0 +1,180 @@
+require "pgi/dataset/query"
+require "pgi/dataset/utils"
+
+module PGI
+  module Dataset
+    # Select specific columns
+    #
+    # @param args [String|Array] list of columns to include in result set
+    # @return [Query]
+    def select(*args)
+      columns = args.empty? ? "*" : Utils.sanitize_columns(args, @table).join(", ")
+      command = "SELECT #{columns} FROM #{@table}"
+      Query.new(@database, @table, command, **@options)
+    end
+
+    # Select specfic rows
+    #
+    # @param args [String|Array] conditions to search for
+    # @return [Query]
+    def where(*)
+      Query.new(@database, @table, nil, **@options).where(*)
+    end
+
+    # Insert new row
+    #
+    # @param args [Hash|Object] row data
+    # @return [Model,Hash]
+    def insert(**attributes)
+      attributes = Utils.strip_uninsertable(attributes)
+
+      insert!(**attributes)
+    end
+
+    def insert!(**attributes)
+      columns, placeholders, values = sql_params(attributes)
+      command = "INSERT INTO #{@table}"
+      command <<
+        if columns.empty?
+          " DEFAULT VALUES"
+        else
+          " (#{columns.join(", ")}) VALUES (#{placeholders.join(", ")}) "
+        end
+
+      _to_model Query.new(@database, @table, command, params: values).limit(nil).to_a.first
+    end
+
+    # Update row
+    #
+    # @param id [*] ID of row
+    # @param args [Hash] data for update
+    # @return [Model,Hash]
+    def update(id, **args)
+      args = Utils.strip_unupdateable(args)
+
+      update!(id, **args)
+    end
+
+    def update!(id, **args)
+      columns, placeholders, values = sql_params(args)
+      set_clause = columns.zip(placeholders).map { |c, p| "#{c} = #{p}" }.join(", ")
+      command = "UPDATE #{@table} SET #{set_clause} " \
+                "WHERE #{Utils.sanitize_column(:id)} = $#{values.size + 1} RETURNING *"
+
+      # TODO: Query throws `PG::IndeterminateDatatype: ERROR:  could not determine data type of parameter $2`
+      # _to_model Query.new(@database, @table, command, params: values + [id]).where(id: id).limit(nil)
+
+      _to_model @database.exec_stmt(Utils.stmt_name(@table, command), command, values + [id])&.first
+    end
+
+    # Delete row
+    #
+    # @param id [*] ID of row
+    # @return [Model,Hash]
+    def delete(id)
+      command = "DELETE FROM #{@table}"
+      _to_model Query.new(@database, @table, command, **@options).where(id: id).limit(nil).to_a.first
+    end
+
+    # Get a row by its id
+    #
+    # @param id [*] ID of row
+    # @return [Model,Hash]
+    def find(id)
+      _to_model Query.new(@database, @table, nil, **@options).where(id: id).first
+    end
+
+    # Get all rows
+    #
+    # @return [Array] list of Models, Hashes
+    def all
+      _to_models Query.new(@database, @table, nil, **@options).limit(nil).to_a
+    end
+
+    # Get first row by column (default: :id)
+    #
+    # @return [Model,Hash]
+    def first(sort_by = :id)
+      _to_model where.order(sort_by.to_sym, :asc).first
+    end
+
+    # Get last row by column (default: :id)
+    #
+    # @return [Model,Hash]
+    def last(sort_by = :id)
+      _to_model where.order(sort_by.to_sym, :desc).first
+    end
+
+    # Get number of rows
+    #
+    # @return [Integer] number of rows in the table
+    def count
+      Query.new(@database, @table, nil, **@options).count
+    end
+
+    # Get a page of results using keyset pagination.
+    #
+    # Sorting by a column other than :id requires a composite index on
+    # (sort_by, id) for seek performance — see README.
+    #
+    # @param cursor [*, nil] id of the last row from the previous page, or nil for the first page
+    # @param size [Integer] number of rows per page
+    # @param sort_by [Symbol] column to sort by
+    # @param sort_dir [Symbol] :asc or :desc
+    # @param where [Array] optional WHERE clause forwarded to Query#where
+    # @return [Array] list of Models or Hashes
+    def page(cursor = nil, size = 10, sort_by = :id, sort_dir = :asc, *where)
+      _to_models Query.new(@database, @table, nil, **@options).where(*where).limit(size).keyset(sort_by, cursor, sort_dir).to_a
+    end
+
+    private
+
+    # Build aligned column names, $N placeholders and values from an attributes
+    # hash. Sorted by key so identical attributes always produce identical SQL -
+    # the prepared-statement name is a digest of the SQL.
+    #
+    # @param attributes [Hash] column => value
+    # @return [Array(Array, Array, Array)] sanitized columns, placeholders, values
+    def sql_params(attributes)
+      attrs = attributes.sort.to_h
+      [Utils.sanitize_columns(attrs.keys), (1..attrs.size).map { |i| "$#{i}" }, attrs.values]
+    end
+
+    # Call #to_model on super class if defined
+    #
+    # @param obj [Hash]
+    # @return [Model, Hash] Model instance or a Hash
+    def _to_model(obj)
+      respond_to?(:to_model) ? obj && to_model(obj) : obj
+    end
+
+    # Call #to_models on super class if defined
+    #
+    # @param obj [Array]
+    # @return [Array] list of Model instance or a Hashes
+    def _to_models(obj)
+      respond_to?(:to_models) ? obj && to_models(obj) : obj
+    end
+
+    class << self
+      def [](database, table, **options)
+        raise "Invalid table name: #{table}" unless table.to_s =~ /\A[a-z_][a-z0-9_]*\z/
+
+        mod = clone
+        mod.instance_variable_set("@database", database)
+        mod.instance_variable_set("@table", table)
+        mod.instance_variable_set("@options", options)
+        mod
+      end
+
+      def extended(klass)
+        raise "Database table not specified" unless @table
+
+        klass.instance_variable_set("@database", @database)
+        klass.instance_variable_set("@table", @table)
+        klass.instance_variable_set("@options", @options)
+      end
+    end
+    # end Eigen class
+  end
+end

data/lib/pgi/db.rb

@@ -0,0 +1,105 @@
+require "pg"
+require "connection_pool"
+require "pgi/connection"
+
+module PGI
+  class DB
+    attr_reader :pool
+
+    # Create instance
+    #
+    # @param pool [ConnectionPool]
+    # @param logger [Logger]
+    # @param max_retries [Integer, Float] shared retry budget for lost connections and pool
+    #   checkout timeouts - use Float::INFINITY to ride out arbitrarily long outages
+    # @param retry_wait [Numeric] seconds to sleep between reconnection attempts
+    def initialize(pool, logger, max_retries: 30, retry_wait: 2)
+      @pool        = pool
+      @logger      = logger
+      @max_retries = max_retries
+      @retry_wait  = retry_wait
+    end
+
+    def self.configure
+      @options = Struct.new(
+        :pool_size, :pool_timeout, :pg_conn_uri, :logger, :max_retries, :retry_wait
+      ).new
+
+      yield @options
+
+      pool = ConnectionPool.new(size: @options.pool_size, timeout: @options.pool_timeout) do
+        Connection.new(conn_uri: @options.pg_conn_uri, logger: @options.logger)
+      end
+
+      retry_options = { max_retries: @options.max_retries, retry_wait: @options.retry_wait }.compact
+      new(pool, @options.logger, **retry_options)
+    end
+
+    # wrapper around ConnectionPool#with with auto-healing capabilities
+    #
+    # @yield PGI:Connection
+    def transaction
+      raise "Missing block" unless block_given?
+
+      with do |conn|
+        conn.transaction do |trans_conn|
+          yield Connection.new(conn: trans_conn, logger: @logger)
+        end
+      end
+    end
+
+    # wrapper around ConnectionPool#with with auto-healing capabilities
+    #
+    # Lost connections and pool checkout timeouts share the max_retries budget,
+    # so a genuinely stuck pool fails loudly instead of waiting forever.
+    #
+    # @yield PGI:Connection
+    def with
+      raise "Missing block" unless block_given?
+
+      retries = 0
+      begin
+        @pool.with do |conn| # rubocop:disable Style/ExplicitBlockArgument
+          yield conn
+        end
+      rescue PG::ConnectionBad, PG::UnableToSend => e
+        retries += 1
+        if retries > @max_retries
+          @logger&.error("DB connection was lost - unable to reconnect (#{e.class}: #{e.message})")
+          raise
+        end
+        @logger&.warn("DB connection was lost - reconnecting(#{retries}/#{@max_retries}) and retrying (#{e.class}: #{e.message})")
+        @pool.reload(&:close)
+        sleep @retry_wait
+        retry
+      rescue ConnectionPool::TimeoutError => e
+        retries += 1
+        if retries > @max_retries
+          @logger&.error("Timeout in checking out DB connection from pool - giving up (#{e.message})")
+          raise
+        end
+        @logger&.warn("Timeout in checking out DB connection from pool - retrying(#{retries}/#{@max_retries}) (#{e.message})")
+        retry
+      end
+    end
+
+    def exec(sql)
+      with do |conn|
+        conn.exec(sql)
+      end
+    end
+
+    # Pass the remainder of methods on to a PGI::Connection
+    #
+    # @See https://deveiate.org/code/pg/PG/Connection.html
+    def method_missing(name, ...)
+      with do |conn|
+        conn.__send__(name, ...)
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      PG::Connection.method_defined?(name) || super
+    end
+  end
+end

data/lib/pgi/schema_migrator.rb

@@ -0,0 +1,121 @@
+module PGI
+  class SchemaMigrator
+    @config     = Struct.new(:pg_conn, :migration_files, :seed_files).new
+    @migrations = Hash.new { |h, k| h[k] = {} }.merge(
+      # Default migration
+      0 => {
+        1 => "CREATE TABLE IF NOT EXISTS schema_migrations (version INTEGER," \
+             "created_at TIMESTAMP WITHOUT TIME ZONE DEFAULT CURRENT_TIMESTAMP);",
+        -1 => "DROP TABLE schema_migrations;"
+      }
+    )
+
+    def initialize(version)
+      raise "FATAL: version must be an integer > 0" unless version.is_a?(Integer) && version.positive?
+      raise "FATAL: Duplication migration version" if self.class.migrations.key?(version)
+      raise "FATAL: Broken migration ID sequence" unless version == self.class.migrations.keys.max + 1
+
+      @version = version
+    end
+
+    def up
+      self.class.migrations[@version][1] = yield
+    end
+
+    def down
+      self.class.migrations[@version][-1] = yield
+    end
+
+    class << self
+      attr_reader :config, :migrations
+
+      def configure
+        yield(config)
+
+        self
+      end
+
+      def migrate!(version = nil)
+        raise "FATAL: version must be an integer >= 0" unless version.nil? || (version.is_a?(Integer) && version >= 0)
+
+        config.migration_files.sort.each { |file| require file }
+
+        raise "FATAL: Migration version does not exist" unless version.nil? || migrations.key?(version)
+
+        to_version = version || latest_migration
+        current    = current_version
+
+        if current == to_version
+          puts "No migrations detected..."
+          return
+        end
+
+        config.pg_conn.transaction do
+          if to_version > current
+            ((current + 1)..to_version).each do |v|
+              config.pg_conn.exec(migrations[v][1])
+              add_version(v)
+            end
+          else
+            current.downto(to_version + 1) do |v|
+              delete_version(v)
+              config.pg_conn.exec(migrations[v][-1])
+            end
+          end
+        end
+      end
+
+      def version(version)
+        yield(new(version))
+      end
+
+      def current_version
+        current = config.pg_conn.exec(<<~SQL).first
+          SELECT * FROM schema_migrations
+          ORDER BY version DESC LIMIT 1
+        SQL
+
+        (current && current["version"].to_i) || 0
+      rescue PG::UndefinedTable => e
+        raise unless e.message =~ /relation "schema_migrations" does not exist/
+
+        -1
+      end
+
+      def destroy!
+        config.pg_conn.exec(<<~SQL)
+          DO $$ DECLARE
+            r RECORD;
+          BEGIN
+            FOR r IN (SELECT tablename FROM pg_tables WHERE schemaname = current_schema()) LOOP
+              EXECUTE 'DROP TABLE IF EXISTS ' || quote_ident(r.tablename) || ' CASCADE';
+            END LOOP;
+            FOR r IN (SELECT DISTINCT typname FROM pg_type INNER JOIN pg_enum ON pg_enum.enumtypid = pg_type.oid) LOOP
+              EXECUTE 'DROP TYPE IF EXISTS ' || quote_ident(r.typname) || ' CASCADE';
+            END LOOP;
+          END $$;
+        SQL
+      end
+
+      private
+
+      def latest_migration
+        migrations.keys.max || -1
+      end
+
+      def add_version(version)
+        config.pg_conn.exec_params(<<~SQL, [version])
+          INSERT INTO schema_migrations
+          (version) VALUES ($1)
+        SQL
+      end
+
+      def delete_version(version)
+        config.pg_conn.exec_params(<<~SQL, [version])
+          DELETE FROM schema_migrations
+          WHERE version = $1
+        SQL
+      end
+    end
+  end
+end

data/lib/pgi/tasks.rake

@@ -0,0 +1,55 @@
+namespace :db do
+  def current_version
+    PGI::SchemaMigrator.current_version
+  end
+
+  task :migration_env do
+    require "pgi/schema_migrator"
+  end
+
+  desc "Prints current schema version"
+  task version: [:migration_env] do
+    puts "Schema Version: #{current_version}"
+  end
+
+  desc "Perform migration up to latest migration available"
+  task migrate: [:migration_env] do
+    PGI::SchemaMigrator.migrate!
+    Rake::Task["db:version"].execute
+  end
+
+  # TODO: Don't rollback to version = 0 by default
+  desc "Perform rollback to specified target or full rollback as default"
+  task :rollback, [:target] => [:migration_env] do |_, args|
+    args.with_defaults(target: 0)
+
+    if args.target.to_i < current_version
+      puts "WARNING: You are about to rollback migration from version #{current_version} to #{args.target}"
+      5.downto(1) do |i|
+        print "\rI'm giving you #{i} seconds to regret and abort", ".. "
+        sleep 1
+      end
+      puts
+    end
+
+    PGI::SchemaMigrator.migrate! args[:target].to_i
+    Rake::Task["db:version"].execute
+  end
+
+  desc "Destroy all tables with and go back to empty DB"
+  task destroy: [:migration_env] do
+    unless %w[development test staging ci].include?(ENV.fetch("RACK_ENV", nil))
+      warn "Destroy not allowed for environment #{ENV.fetch("RACK_ENV", nil).inspect}"
+      exit 1
+    end
+
+    puts "Destroying all tables..."
+    PGI::SchemaMigrator.destroy!
+  end
+
+  desc "Seed database"
+  task seed: [:migration_env] do
+    puts "Seeding database with test data..."
+    PGI::SchemaMigrator.config.seed_files.each { |file| require file }
+  end
+end

data/lib/pgi/version.rb

@@ -0,0 +1,3 @@
+module PGI
+  VERSION = File.read("#{__dir__}/../../VERSION").split("\n").first&.freeze
+end

data/lib/pgi.rb

@@ -0,0 +1,4 @@
+module PGI
+  autoload(:Dataset, "pgi/dataset")
+  autoload(:DB, "pgi/db")
+end

data/pgi.gemspec

@@ -0,0 +1,27 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "pgi/version"
+
+Gem::Specification.new do |gem|
+  gem.name          = "pgi"
+  gem.version       = PGI::VERSION
+  gem.authors       = ["Coherify"]
+  gem.email         = ["hello@coherify.net"]
+  gem.description   = "Simple and convenient interface for PostgreSQL with a few enhancements"
+  gem.summary       = "Simple and convenient interface for PostgreSQL with a few enhancements"
+  gem.homepage      = "https://github.com/coherify/pgi"
+  gem.license       = "MIT"
+
+  gem.required_ruby_version = ">= 3.4.0"
+
+  gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
+  gem.require_paths = ["lib"]
+  gem.files         = Dir["lib/**/*", "CHANGELOG.md", "LICENSE", "README.md", "VERSION", "pgi.gemspec"]
+
+  gem.add_dependency "connection_pool", "~> 2.4"
+  gem.add_dependency "pg", "~> 1.5"
+
+  gem.metadata["rubygems_mfa_required"] = "true"
+  gem.metadata["source_code_uri"]       = "https://github.com/coherify/pgi"
+  gem.metadata["changelog_uri"]         = "https://github.com/coherify/pgi/blob/main/CHANGELOG.md"
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: pgi
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Coherify
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !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'
+description: Simple and convenient interface for PostgreSQL with a few enhancements
+email:
+- hello@coherify.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- VERSION
+- lib/pgi.rb
+- lib/pgi/connection.rb
+- lib/pgi/dataset.rb
+- lib/pgi/dataset/query.rb
+- lib/pgi/dataset/utils.rb
+- lib/pgi/db.rb
+- lib/pgi/schema_migrator.rb
+- lib/pgi/tasks.rake
+- lib/pgi/version.rb
+- pgi.gemspec
+homepage: https://github.com/coherify/pgi
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/coherify/pgi
+  changelog_uri: https://github.com/coherify/pgi/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.14
+specification_version: 4
+summary: Simple and convenient interface for PostgreSQL with a few enhancements
+test_files: []