active_postgrest 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cbb8484a4d524bbe396c3cb4a87dade05a3e8628aa2e0703c84b749287a86e67
+  data.tar.gz: 8640a588f4fac91e890575794632d154cec30ab699aea4057f3ce1d4245ea7fa
+SHA512:
+  metadata.gz: '097618ab9f67309599c73848566398f423c8d584f8844e603a9a25f845be8a359cb4f3e347de72c888c7b42b10ea30ded62e2f3418743394085d521b80d47fc7'
+  data.tar.gz: baef5f5829e50eef2d9f012a275d8391b73b4f269c5053c4286ff1290ca5593160da71cd6a12347a8fcd18151a82df7f6d1874b3f89ff2345d60f896b72254a3

data/LICENSE

@@ -0,0 +1,184 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and subsequently
+      incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any
+      Contribution embodied within the Work constitutes direct or contributory
+      patent infringement, then any patent licenses granted to You under
+      this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or as an addendum to
+          the NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Contribution, either on an as-is basis or with modifications, as You
+      see fit.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Liability. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a fee
+      for, acceptance of support, warranty, indemnity, or other liability
+      obligations and/or rights consistent with this License. However,
+      in accepting such obligations, You may offer such obligations only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Evgeny Sokolov (FastJoe)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

data/lib/active_postgrest/base.rb

@@ -0,0 +1,215 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Evgeny Sokolov (FastJoe)
+
+require 'bigdecimal'
+
+module ActivePostgrest
+  class Base
+    POSTGRES_TYPE_CAST = {
+      'date' => :date,
+      'timestamp' => :datetime,
+      'timestamp with time zone' => :datetime,
+      'timestamp without time zone' => :datetime,
+      'time' => :time,
+      'time with time zone' => :time,
+      'time without time zone' => :time,
+      'numeric' => :decimal,
+      'decimal' => :decimal,
+      'real' => :decimal,
+      'double precision' => :decimal
+    }.freeze
+
+    def self.table_name
+      @table_name ||= name.demodulize.underscore.pluralize
+    end
+
+    class << self
+      attr_writer :table_name, :schema_name
+    end
+
+    def self.schema_name
+      @schema_name || (superclass.schema_name if superclass.respond_to?(:schema_name))
+    end
+
+    def self.primary_key
+      @primary_key ||= 'id'
+    end
+
+    def self.primary_key=(key)
+      @primary_key = key.to_s
+    end
+
+    def self.establish_connection(url: ENV.fetch('POSTGREST_URL'), jwt_token: nil)
+      @connection = ActivePostgrest::Client.new(url, jwt_token)
+    end
+
+    def self.connection
+      @connection ||
+        if superclass.respond_to?(:connection)
+          superclass.connection
+        else
+          ActivePostgrest::Client.new
+        end
+    end
+
+    def self.attribute(name, type)
+      @attribute_types ||= {}
+      @attribute_types[name.to_s] = type
+    end
+
+    def self.attribute_types
+      @attribute_types || {}
+    end
+
+    def self.schema
+      connection.table_schema(table_name)
+    end
+
+    def self.attributes
+      schema['properties']&.transform_values { _1['format'] } || {}
+    end
+
+    def self.belongs_to(name, class_name: nil, foreign_key: nil)
+      assoc   = name.to_s
+      klass   = class_name&.to_s || assoc.camelize
+      table   = klass.underscore.pluralize
+      fk      = foreign_key&.to_s
+      aliased = fk || (klass.underscore != assoc)
+      key     = aliased ? assoc : table
+
+      define_method(assoc) do
+        val = @attributes[key]
+        return nil if val.nil? || (val.is_a?(Array) && val.empty?)
+
+        klass.constantize.new(val.is_a?(Array) ? val.first : val)
+      end
+
+      define_singleton_method(:"with_#{assoc}") do |fields: []|
+        if aliased
+          joins(table.to_sym, as: assoc.to_sym, foreign_key: fk&.to_sym, select: fields)
+        else
+          joins(table.to_sym, select: fields)
+        end
+      end
+    end
+
+    def self.has_one(name, class_name: nil)
+      assoc = name.to_s
+      klass = class_name&.to_s || assoc.camelize
+
+      define_method(assoc) do
+        val = @attributes[assoc]
+        return nil if val.nil? || (val.is_a?(Array) && val.empty?)
+
+        klass.constantize.new(val.is_a?(Array) ? val.first : val)
+      end
+
+      define_singleton_method(:"with_#{assoc}") do |fields: []|
+        embed(assoc.to_sym, fields: fields)
+      end
+    end
+
+    def self.has_many(name, class_name: nil)
+      assoc = name.to_s
+      klass = class_name&.to_s || assoc.singularize.camelize
+
+      define_method(assoc) do
+        val = @attributes[assoc]
+        return [] if val.nil?
+
+        Array(val).map { klass.constantize.new(_1) }
+      end
+
+      define_singleton_method(:"with_#{assoc}") do |fields: []|
+        embed(assoc.to_sym, fields: fields)
+      end
+    end
+
+    def self.scope(name, body)
+      define_singleton_method(name) { |*args, **kwargs| body.call(*args, **kwargs) }
+    end
+
+    def self.relation
+      rel = ActivePostgrest::Relation.new(table_name, connection, self)
+      schema_name ? rel.with_schema(schema_name) : rel
+    end
+
+    def self.all                   = relation
+    def self.none                  = relation.none
+    def self.anonymous             = relation.anonymous
+    def self.with_token(jwt)       = relation.with_token(jwt)
+    def self.with_schema(name)     = relation.with_schema(name)
+    def self.where(filters = nil)  = relation.where(filters)
+    def self.not_where(filters)    = relation.not_where(filters)
+    def self.or_where(conditions)  = relation.or_where(conditions)
+    def self.and_where(conditions) = relation.and_where(conditions)
+    def self.order(...)            = relation.order(...)
+    def self.reorder(...)          = relation.reorder(...)
+    def self.limit(n)              = relation.limit(n)
+    def self.offset(n)             = relation.offset(n)
+    def self.joins(...)            = relation.joins(...)
+    def self.embed(...)            = relation.embed(...)
+    def self.select(...)           = relation.select(...)
+    def self.spread(...)           = relation.spread(...)
+
+    def self.first(n = nil)       = n ? relation.limit(n).to_a : relation.first
+    def self.last(n = nil)        = n ? relation.order(primary_key, :desc).limit(n).to_a.reverse : relation.last
+    def self.find(id)             = relation.where(id: id).first
+    def self.find!(id)            = find(id) || raise(ActivePostgrest::RecordNotFound.new(self, id))
+    def self.find_by(filters)     = relation.where(filters).first
+    def self.find_by!(filters)    = find_by(filters) || raise(ActivePostgrest::RecordNotFound.new(self, filters))
+
+    def self.exists?(filters = {})
+      filters.empty? ? relation.any? : relation.where(filters).any?
+    end
+
+    def self.pluck(*cols) = relation.pluck(*cols)
+    def self.pick(*cols)  = relation.pick(*cols)
+    def self.count(mode = :exact) = relation.count(mode)
+    def self.any?         = relation.any?
+    def self.none?        = relation.none?
+    def self.one?         = relation.one?
+    def self.many?        = relation.many?
+
+    def initialize(attrs = {})
+      types = self.class.attribute_types
+      @attributes = attrs.to_h.transform_keys(&:to_s).to_h do |k, v|
+        [k, types[k] ? cast_attribute(v, types[k]) : v]
+      end
+    end
+
+    def [](key) = @attributes[key.to_s]
+    attr_reader :attributes
+
+    def to_h = @attributes
+
+    def inspect
+      "#<#{self.class.name} #{@attributes.map { "#{_1}: #{_2.inspect}" }.join(', ')}>"
+    end
+
+    def method_missing(name, *)
+      key = name.to_s
+      return @attributes[key] if @attributes.key?(key)
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @attributes.key?(name.to_s) || super
+    end
+
+    private
+
+    def cast_attribute(value, type)
+      return nil if value.nil?
+
+      case type
+      when :date then Date.parse(value.to_s)
+      when :datetime, :time then Time.parse(value.to_s)
+      when :decimal  then BigDecimal(value.to_s)
+      when :integer  then Integer(value)
+      else value
+      end
+    end
+  end
+end

data/lib/active_postgrest/client.rb

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Evgeny Sokolov (FastJoe)
+
+module ActivePostgrest
+  class Client
+    attr_reader :base_url
+
+    def initialize(base_url = ENV.fetch('POSTGREST_URL'), jwt_token = nil)
+      @base_url = base_url
+      @auth_header = "Bearer #{jwt_token}" if jwt_token
+      @conn = Faraday.new(base_url, request: { params_encoder: Faraday::FlatParamsEncoder }) do |f|
+        f.request :json
+        f.response :json
+      end
+    end
+
+    def openapi
+      @openapi ||= @conn.get('/').body
+    end
+
+    def tables
+      openapi['paths']&.keys&.filter_map { |p| p.delete_prefix('/').then { |s| s.empty? ? nil : s } } || []
+    end
+
+    def table_schema(table)
+      openapi.dig('definitions', table) || {}
+    end
+
+    def explain(resource, params = {}, schema: nil)
+      @conn.get(resource, params) do |req|
+        auth_headers(req)
+        req.headers['Accept']          = 'application/vnd.pgrst.plan+text; for="application/json"; options=verbose'
+        req.headers['Accept-Profile']  = schema if schema
+      end.body
+    end
+
+    def get(resource, params = {}, count: :exact, schema: nil)
+      response = @conn.get(resource, params) do |req|
+        auth_headers(req)
+        req.headers['Prefer']         = "count=#{count}"
+        req.headers['Accept-Profile'] = schema if schema
+      end
+      raise_on_error!(response)
+      response
+    end
+
+    def anonymous
+      self.class.new(@base_url)
+    end
+
+    def with_token(jwt)
+      self.class.new(@base_url, jwt)
+    end
+
+    private
+
+    def raise_on_error!(response)
+      klass = case response.status
+              when 400 then BadRequest
+              when 401 then Unauthorized
+              when 403 then Forbidden
+              when 404 then ResourceNotFound
+              when 409 then Conflict
+              when 422 then UnprocessableEntity
+              when 500..599 then ServerError
+              end
+      raise klass, response if klass
+    end
+
+    def auth_headers(req)
+      req.headers['Authorization'] = @auth_header if @auth_header
+    end
+  end
+end

data/lib/active_postgrest/errors.rb

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Evgeny Sokolov (FastJoe)
+
+module ActivePostgrest
+  class Error < StandardError
+    attr_reader :code, :details, :hint, :http_status
+
+    def initialize(response)
+      body         = response.body.is_a?(Hash) ? response.body : {}
+      @http_status = response.status
+      @code        = body['code']
+      @details     = body['details']
+      @hint        = body['hint']
+      super(body['message'] || "HTTP #{response.status}")
+    end
+  end
+
+  # 400
+  class BadRequest          < Error; end
+  # 401
+  class Unauthorized        < Error; end
+  # 403
+  class Forbidden           < Error; end
+  # 404 — таблица/схема не найдена
+  class ResourceNotFound    < Error; end
+  # 409 — unique violation
+  class Conflict            < Error; end
+  # 422 — FK, not null, check
+  class UnprocessableEntity < Error; end
+  # 5xx
+  class ServerError         < Error; end
+end

data/lib/active_postgrest/relation.rb

@@ -0,0 +1,328 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Evgeny Sokolov (FastJoe)
+
+module ActivePostgrest
+  class RecordNotFound < StandardError
+    def initialize(model, id)
+      super("#{model.name} not found: #{id.inspect}")
+    end
+  end
+
+  class CountNotAvailable < StandardError; end
+
+  class Relation
+    include Enumerable
+
+    class WhereChain
+      def initialize(relation)
+        @relation = relation
+      end
+
+      def not(filters)
+        @relation.not_where(filters)
+      end
+    end
+
+    def initialize(table, client, model_class)
+      @table = table
+      @client = client
+      @model_class = model_class
+      @selects = []
+      @joins = []
+      @filters = {}
+      @or_conditions = []
+      @and_conditions = []
+      @limit_val = nil
+      @offset_val = nil
+      @order_val = nil
+      @null = false
+      @schema = nil
+    end
+
+    def select(*cols)
+      clone_with { @selects.concat(cols.map(&:to_s)) }
+    end
+
+    def spread(*tables)
+      clone_with { @selects.concat(tables.map { "...#{_1}" }) }
+    end
+
+    # joins(:companies)                                      → INNER JOIN (excludes rows with no match)
+    # joins(:users, as: :mother, foreign_key: :mother_id)  → aliased FK join
+    def joins(table, as: nil, foreign_key: nil, select: [], where: {})
+      embed = build_embed(table.to_s, as&.to_s, foreign_key&.to_s, inner: true)
+      add_embed(embed, table.to_s, select.map(&:to_s), where)
+    end
+
+    # left_joins(:companies) → LEFT JOIN (includes rows even with no match)
+    def left_joins(table, as: nil, foreign_key: nil, select: [], where: {})
+      embed = build_embed(table.to_s, as&.to_s, foreign_key&.to_s, inner: false)
+      add_embed(embed, table.to_s, select.map(&:to_s), where)
+    end
+
+    # embed(:mother, fields: [:id, :first_name]) — computed relationship
+    def embed(name, fields: [])
+      add_embed(name.to_s, name.to_s, fields.map(&:to_s), {})
+    end
+
+    # where(name: "John")                         → name=eq.John
+    # where(name: nil)                             → name=is.null
+    # where(active: true)                          → active=is.true
+    # where(id: [1, 2, 3])                         → id=in.(1,2,3)
+    # where(age: 18..30)                           → age=gte.18&age=lte.30
+    # where(age: { gt: 18, lt: 65 })              → age=gt.18&age=lt.65
+    # where(companies: { name: "Acme" })           → companies.name=eq.Acme  (AR-style joins filter)
+    # where.not(name: "John")                      → name=not.eq.John
+    def where(filters = nil)
+      return WhereChain.new(self) if filters.nil?
+
+      clone_with { encode_filters!(filters) }
+    end
+
+    def not_where(filters)
+      clone_with { encode_filters!(filters, negate: true) }
+    end
+
+    # or_where([{ age: { lt: 18 } }, { status: "active" }]) → or=(age.lt.18,status.eq.active)
+    def or_where(conditions)
+      parts = Array(conditions).flat_map { |f| condition_parts(f) }
+      clone_with { @or_conditions.concat(parts) }
+    end
+
+    # and_where([{ age: { gt: 18 } }, { status: "active" }]) → and=(age.gt.18,status.eq.active)
+    def and_where(conditions)
+      parts = Array(conditions).flat_map { |f| condition_parts(f) }
+      clone_with { @and_conditions.concat(parts) }
+    end
+
+    def limit(n)       = clone_with { @limit_val = n }
+    def offset(n)      = clone_with { @offset_val = n }
+
+    def order(col, dir = :asc, nulls: nil)
+      clone_with { @order_val = build_order(col, dir, nulls) }
+    end
+
+    def reorder(col, dir = :asc, nulls: nil)
+      clone_with { @order_val = build_order(col, dir, nulls) }
+    end
+
+    def none                 = clone_with { @null = true }
+    def anonymous            = clone_with { @client = @client.anonymous }
+    def with_token(jwt)      = clone_with { @client = @client.with_token(jwt) }
+    def with_schema(name)    = clone_with { @schema = name }
+
+    def each(&)
+      to_a.each(&)
+    end
+
+    def to_a
+      return [] if @null
+
+      Array(@client.get(@table, build_params, schema: @schema).body).map { |attrs| @model_class.new(attrs) }
+    end
+
+    def first
+      limit(1).to_a.first
+    end
+
+    def last(n = nil)
+      pk = @model_class.primary_key
+      return order(pk, :desc).limit(n).to_a.reverse if n
+
+      order(pk, :desc).limit(1).to_a.first
+    end
+
+    def count(mode = :exact)
+      return 0 if @null
+
+      response = @client.get(@table, build_params.merge(limit: 0), count: mode, schema: @schema)
+      raw   = response.headers['content-range']&.split('/')&.last
+      total = raw&.delete_prefix('~')
+      if total.nil? || total == '*'
+        raise CountNotAvailable, "count=#{mode} not available (Content-Range: #{raw.inspect})"
+      end
+
+      total.to_i
+    end
+
+    def any?(&block)    = block ? super : count.positive?
+    def none?(&block)   = block ? super : count.zero?
+    def one?(&block)    = block ? super : count == 1
+    def many?           = count > 1
+    def exists?         = any?
+
+    def average(col)  = aggregate_value("#{col}.avg()", 'avg')
+    def sum(col)      = aggregate_value("#{col}.sum()", 'sum')
+    def minimum(col)  = aggregate_value("#{col}.min()", 'min')
+    def maximum(col)  = aggregate_value("#{col}.max()", 'max')
+
+    def pluck(*cols)
+      return [] if @null
+
+      select(*cols).to_a.map do |record|
+        cols.length == 1 ? record[cols.first] : cols.map { record[_1] }
+      end
+    end
+
+    def pick(*cols)
+      pluck(*cols).first
+    end
+
+    # Returns a human-readable SQL-like representation of the query reconstructed
+    # from the relation's internal state — no database call is made.
+    #
+    # Limitations vs actual SQL:
+    # - Embedded resources use PostgREST notation: companies(*) instead of
+    #   LEFT JOIN companies ON companies.id = users.company_id.
+    # - Parameters are shown as literal values, not PostgreSQL placeholders ($1, $2).
+    # - The actual query PostgREST sends is a CTE (WITH pgrst_source AS (...))
+    #   and may differ in structure. Use #explain to see the real execution plan.
+    def to_sql
+      clauses = ["SELECT #{sql_select}", "FROM #{@table}"]
+
+      wheres = sql_where_clauses
+      clauses << "WHERE #{wheres.join("\n  AND ")}" if wheres.any?
+
+      clauses << "ORDER BY #{sql_order}" if @order_val
+      clauses << "LIMIT #{@limit_val}"   if @limit_val
+      clauses << "OFFSET #{@offset_val}" if @offset_val
+
+      clauses.join("\n")
+    end
+
+    def explain
+      @client.explain(@table, build_params, schema: @schema)
+    end
+
+    def to_url
+      params = build_params
+      base   = "#{@client.base_url}/#{@table}"
+      return base if params.empty?
+
+      query  = params.flat_map { |k, v| Array(v).map { "#{k}=#{_1}" } }.join('&')
+      "#{base}?#{query}"
+    end
+
+    def method_missing(name, *, **)
+      return super unless @model_class.respond_to?(name)
+
+      scope = @model_class.public_send(name, *, **)
+      return super unless scope.is_a?(ActivePostgrest::Relation)
+
+      merge(scope)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @model_class.respond_to?(name) || super
+    end
+
+    def inspect
+      to_a.inspect
+    end
+
+    include SqlBuilder
+
+    private
+
+    def merge(other)
+      clone_with do
+        @selects.concat(other.instance_variable_get(:@selects))
+        @joins.concat(other.instance_variable_get(:@joins))
+        other.instance_variable_get(:@filters).each { |k, v| merge_filter!(k, v) }
+        @or_conditions.concat(other.instance_variable_get(:@or_conditions))
+        @and_conditions.concat(other.instance_variable_get(:@and_conditions))
+        @limit_val  = other.instance_variable_get(:@limit_val)  if other.instance_variable_get(:@limit_val)
+        @offset_val = other.instance_variable_get(:@offset_val) if other.instance_variable_get(:@offset_val)
+        @order_val  = other.instance_variable_get(:@order_val)  if other.instance_variable_get(:@order_val)
+        @null       = true if other.instance_variable_get(:@null)
+      end
+    end
+
+    def add_embed(embed_str, table, select, where)
+      clone_with { @joins << { embed: embed_str, select: select, where: where, table: table } }
+    end
+
+    def build_embed(table, as_name, foreign_key, inner: false)
+      embed = as_name ? "#{as_name}:#{table}" : table
+      embed += "!#{foreign_key}" if foreign_key
+      embed += '!inner' if inner
+      embed
+    end
+
+    def encode_filters!(filters, negate: false)
+      prefix = negate ? 'not.' : ''
+      filters.each do |col, val|
+        if table_condition?(val)
+          val.each do |sub_col, sub_val|
+            encoded = encode_value(sub_val, prefix: prefix)
+            merge_filter!("#{col}.#{sub_col}", encoded) unless encoded.nil?
+          end
+        else
+          encoded = encode_value(val, prefix: prefix)
+          merge_filter!(col.to_s, encoded) unless encoded.nil?
+        end
+      end
+    end
+
+    def aggregate_value(expr, key)
+      return nil if @null
+
+      clone_with do
+        @selects    = [expr]
+        @joins      = []
+        @limit_val  = nil
+        @offset_val = nil
+        @order_val  = nil
+      end.to_a.first&.[](key)
+    end
+
+    def condition_parts(filters)
+      filters.flat_map do |col, val|
+        Array(encode_value(val)).map { "#{col}.#{_1}" }
+      end
+    end
+
+    def build_params
+      params = {}
+      params[:select] = build_select if @selects.any? || @joins.any?
+      params[:order]  = @order_val if @order_val
+      params[:limit]  = @limit_val if @limit_val
+      params[:offset] = @offset_val if @offset_val
+      params[:or]     = "(#{@or_conditions.join(',')})" if @or_conditions.any?
+      params[:and]    = "(#{@and_conditions.join(',')})" if @and_conditions.any?
+      params.merge!(@filters)
+
+      @joins.each do |j|
+        j[:where].each do |col, val|
+          key = "#{j[:table]}.#{col}"
+          encoded = encode_value(val)
+          existing = params[key]
+          params[key] = existing ? [*Array(existing), *Array(encoded)] : encoded
+        end
+      end
+
+      params
+    end
+
+    def build_select
+      parts = @selects.empty? ? ['*'] : @selects.dup
+      @joins.each do |j|
+        inner = j[:select].any? ? j[:select].join(',') : '*'
+        parts << "#{j[:embed]}(#{inner})"
+      end
+      parts.join(',')
+    end
+
+    def clone_with(&block)
+      dup.tap do |copy|
+        copy.instance_variable_set(:@selects, @selects.dup)
+        copy.instance_variable_set(:@joins, @joins.dup)
+        copy.instance_variable_set(:@filters, @filters.dup)
+        copy.instance_variable_set(:@or_conditions, @or_conditions.dup)
+        copy.instance_variable_set(:@and_conditions, @and_conditions.dup)
+        copy.instance_variable_set(:@null, @null)
+        copy.instance_eval(&block)
+      end
+    end
+  end
+end

data/lib/active_postgrest/sql_builder.rb

@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Evgeny Sokolov (FastJoe)
+
+module ActivePostgrest
+  module SqlBuilder
+    FILTER_OPS = {
+      'eq' => '=', 'neq' => '!=', 'gt' => '>', 'gte' => '>=',
+      'lt' => '<', 'lte' => '<=', 'like' => 'LIKE', 'ilike' => 'ILIKE',
+      'fts' => '@@', 'cs' => '@>', 'cd' => '<@'
+    }.freeze
+
+    NEGATED_OPS = {
+      'eq' => '!=', 'neq' => '=', 'gt' => '<=', 'gte' => '<',
+      'lt' => '>=', 'lte' => '>', 'like' => 'NOT LIKE', 'ilike' => 'NOT ILIKE'
+    }.freeze
+
+    KNOWN_OP_KEYS = (FILTER_OPS.keys + %w[not in is]).freeze
+
+    private
+
+    def table_condition?(val)
+      val.is_a?(Hash) && val.keys.none? { KNOWN_OP_KEYS.include?(_1.to_s) }
+    end
+
+    def encode_value(val, prefix: '')
+      case val
+      when nil   then "#{prefix}is.null"
+      when true  then "#{prefix}is.true"
+      when false then "#{prefix}is.false"
+      when Array then "#{prefix}in.(#{val.map { encode_in_value(_1) }.join(',')})"
+      when Range
+        parts = []
+        parts << "#{prefix}gte.#{val.begin}" unless val.begin.nil?
+        parts << (val.exclude_end? ? "#{prefix}lt.#{val.end}" : "#{prefix}lte.#{val.end}") unless val.end.nil?
+        return nil if parts.empty?
+
+        parts.one? ? parts.first : parts
+      when Hash
+        parts = val.map { |op, v| "#{prefix}#{op}.#{v}" }
+        parts.one? ? parts.first : parts
+      else
+        "#{prefix}eq.#{val}"
+      end
+    end
+
+    def encode_in_value(v)
+      str = v.to_s
+      str.include?(',') ? %("#{str}") : str
+    end
+
+    def sql_select
+      parts = @selects.empty? ? ['*'] : @selects.dup
+      @joins.each do |j|
+        cols = j[:select].any? ? j[:select].join(', ') : '*'
+        parts << "#{j[:embed]}(#{cols})"
+      end
+      parts.join(', ')
+    end
+
+    def sql_where_clauses
+      clauses = @filters.flat_map { |col, encoded| Array(encoded).map { decode_filter(col, _1) } }
+      @joins.each do |j|
+        j[:where].each do |col, val|
+          Array(encode_value(val)).each { |encoded| clauses << decode_filter("#{j[:table]}.#{col}", encoded) }
+        end
+      end
+      clauses << "(#{@or_conditions.map  { decode_condition(_1) }.join(' OR ')})"  if @or_conditions.any?
+      clauses << "(#{@and_conditions.map { decode_condition(_1) }.join(' AND ')})" if @and_conditions.any?
+      clauses
+    end
+
+    def sql_order
+      col, dir, nulls = @order_val.split('.')
+      nulls_sql = { 'nullslast' => 'NULLS LAST', 'nullsfirst' => 'NULLS FIRST' }[nulls]
+      [col, dir&.upcase || 'ASC', nulls_sql].compact.join(' ')
+    end
+
+    def build_order(col, dir, nulls)
+      val = "#{col}.#{dir}"
+      val += ".nulls#{nulls}" if nulls
+      val
+    end
+
+    def merge_filter!(col, encoded)
+      existing = @filters[col]
+      @filters[col] = existing ? [*Array(existing), *Array(encoded)] : encoded
+    end
+
+    def decode_filter(col, encoded)
+      negated = encoded.start_with?('not.')
+      rest    = negated ? encoded[4..] : encoded
+      op, val = rest.split('.', 2)
+
+      case op
+      when 'is' then "#{col} IS#{' NOT' if negated} #{val.upcase}"
+      when 'in' then decode_in(col, val, negated)
+      else
+        sql_op = negated ? (NEGATED_OPS[op] || "NOT #{FILTER_OPS[op] || op}") : (FILTER_OPS[op] || op)
+        "#{col} #{sql_op} #{sql_quote(val)}"
+      end
+    end
+
+    def decode_in(col, val, negated)
+      vals = val.delete_prefix('(').delete_suffix(')').split(',').map { |v| sql_quote(v.strip.delete('"')) }
+      "#{col} #{'NOT ' if negated}IN (#{vals.join(', ')})"
+    end
+
+    def decode_condition(cond)
+      parts  = cond.split('.')
+      op_idx = parts.index { KNOWN_OP_KEYS.include?(_1) }
+      return cond unless op_idx
+
+      col     = parts[0...op_idx].join('.')
+      encoded = parts[op_idx..].join('.')
+      decode_filter(col, encoded)
+    end
+
+    def sql_quote(val)
+      return val if val&.match?(/\A-?\d+(\.\d+)?\z/)
+
+      "'#{val.to_s.gsub("'", "''")}'"
+    end
+  end
+end

data/lib/active_postgrest/version.rb

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Evgeny Sokolov (FastJoe)
+
+module ActivePostgrest
+  VERSION = '0.1.0'.freeze
+end

data/lib/active_postgrest.rb

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Evgeny Sokolov (FastJoe)
+
+require 'active_support'
+require 'active_support/core_ext/string'
+require 'faraday'
+require 'bigdecimal'
+
+require 'active_postgrest/version'
+require 'active_postgrest/errors'
+require 'active_postgrest/client'
+require 'active_postgrest/sql_builder'
+require 'active_postgrest/relation'
+require 'active_postgrest/base'

data/lib/generators/active_postgrest/model_generator.rb

@@ -0,0 +1,52 @@
+require 'rails/generators'
+
+module ActivePostgrest
+  module Generators
+    class ModelGenerator < Rails::Generators::Base
+      argument :name, type: :string, desc: 'Table name, e.g. users'
+
+      def generate_attributes_concern
+        klass = singular.camelize
+        defn  = ActivePostgrest::Base.connection.table_schema(table)
+        props = defn['properties'] || {}
+
+        attrs = props.filter_map do |col, info|
+          type = ActivePostgrest::Base::POSTGRES_TYPE_CAST[info['format']]
+          "    attribute :#{col}, :#{type}" if type
+        end
+
+        content = <<~RUBY
+          # Auto-generated by `rails g active_postgrest:model #{name}`. Do not edit manually.
+          module #{klass}Attributes
+            extend ActiveSupport::Concern
+            included do
+          #{attrs.any? ? attrs.join("\n") : '    # no type casts needed'}
+            end
+          end
+        RUBY
+
+        create_file("app/models/concerns/#{singular}_attributes.rb", content, force: true)
+      end
+
+      def create_model_file
+        path = "app/models/#{singular}.rb"
+
+        if File.exist?(File.join(destination_root, path))
+          say_status :exist, path, :blue
+          say "        → add `include #{singular.camelize}Attributes` to #{path} if not present", :cyan
+        else
+          create_file(path, <<~RUBY)
+            class #{singular.camelize} < ActivePostgrest::Base
+              include #{singular.camelize}Attributes
+            end
+          RUBY
+        end
+      end
+
+      private
+
+      def table    = name.tableize
+      def singular = table.singularize
+    end
+  end
+end

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: active_postgrest
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Evgeny Sokolov
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-06-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-net_http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Query PostgREST APIs using a familiar ActiveRecord-like interface
+email:
+- evgeny.sokolov@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- lib/active_postgrest.rb
+- lib/active_postgrest/base.rb
+- lib/active_postgrest/client.rb
+- lib/active_postgrest/errors.rb
+- lib/active_postgrest/relation.rb
+- lib/active_postgrest/sql_builder.rb
+- lib/active_postgrest/version.rb
+- lib/generators/active_postgrest/model_generator.rb
+homepage: https://github.com/FastJoe/active-postgrest
+licenses:
+- Apache-2.0
+metadata:
+  source_code_uri: https://github.com/FastJoe/active-postgrest
+  changelog_uri: https://github.com/FastJoe/active-postgrest/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: ActiveRecord-style Ruby client for PostgREST
+test_files: []