supabase-rb 2.0.0

data/lib/supabase/postgrest/README.md

@@ -0,0 +1,84 @@
+# `supabase-postgrest`
+
+Ruby client for [PostgREST](https://postgrest.org). Query builder for
+PostgREST-backed Supabase tables, RPCs, and views. Mirrors the public surface
+of [`postgrest`](https://github.com/supabase/supabase-py/tree/main/src/postgrest)
+in Python.
+
+- Source: [github.com/supabase-rb/client](https://github.com/supabase-rb/client)
+
+## Installation
+
+```ruby
+gem "supabase-postgrest"
+```
+
+Then `bundle install`. (Requires Ruby >= 3.0.)
+
+## Usage
+
+```ruby
+require "supabase/postgrest"
+
+client = Supabase::Postgrest::Client.new(
+  base_url: "https://your-project.supabase.co/rest/v1",
+  headers:  { "apikey" => key, "Authorization" => "Bearer #{token}" }
+)
+```
+
+### Select
+
+```ruby
+users = client.from("users")
+              .select("id, name, email")
+              .eq("status", "active")
+              .gt("age", 18)
+              .order("created_at", desc: true)
+              .limit(10)
+              .execute
+users.data    # => [{ "id" => ..., "name" => ..., ... }, ...]
+users.count   # => populated when select(count: "exact")
+```
+
+### Insert / Upsert / Update / Delete
+
+```ruby
+client.from("users").insert({ "name" => "Ada" }).execute
+client.from("users").upsert({ "id" => 1, "name" => "Ada" }, on_conflict: "id").execute
+client.from("users").update({ "name" => "Ada Lovelace" }).eq("id", 1).execute
+client.from("users").delete.eq("id", 1).execute
+```
+
+### RPC
+
+```ruby
+client.rpc("increment", { x: 1 }).execute
+```
+
+### Filters
+
+Every PostgREST filter operator is supported: `eq`, `neq`, `gt/gte/lt/lte`,
+`like` / `ilike` (+ `_all_of` / `_any_of` variants), `is_`, `in_`,
+`contains` / `contained_by`, `range_lt/gt/gte/lte/adjacent`, `overlaps`,
+`fts/plfts/phfts/wfts`, `match`, `or_`, `not_`. See
+[`request_builder.rb`](request_builder.rb) for the full surface.
+
+## Async variant
+
+```ruby
+require "supabase/postgrest/async"
+
+async_client = Supabase::Postgrest::Async::Client.new(
+  base_url: ENV["SUPABASE_URL"] + "/rest/v1",
+  headers:  { "apikey" => key, "Authorization" => "Bearer #{token}" }
+)
+
+Async do |task|
+  jobs = ids.map { |id| task.async { async_client.from("users").select("*").eq("id", id).execute } }
+  jobs.map(&:wait)
+end
+```
+
+A one-method override on top of `Postgrest::Client` that swaps in
+[`async-http-faraday`](https://github.com/socketry/async-http-faraday) for
+fiber-parallel I/O.

data/lib/supabase/postgrest/async/client.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "async/http/faraday"
+require_relative "../client"
+
+module Supabase
+  module Postgrest
+    module Async
+      # Async counterpart to {Supabase::Postgrest::Client}.
+      #
+      # Inherits the full public surface (from, table, rpc, schema) and rewires
+      # only the Faraday adapter to async-http-faraday so HTTP I/O yields back
+      # to the {::Async} reactor instead of blocking the thread.
+      #
+      # The request builders (RequestBuilder / FilterRequestBuilder / etc.) are
+      # transport-agnostic and reused unchanged — they speak to whatever Faraday
+      # connection the client hands them.
+      #
+      # Call sites must run inside an `Async do ... end` block; outside one, the
+      # adapter still works but loses the concurrency win.
+      #
+      #   require "supabase/postgrest/async"
+      #   require "async"
+      #
+      #   client = Supabase::Postgrest::Async::Client.new(
+      #     base_url: "https://project.supabase.co/rest/v1",
+      #     headers:  { "apikey" => key }
+      #   )
+      #
+      #   Async do |task|
+      #     users_task = task.async { client.from("users").select("*").execute }
+      #     posts_task = task.async { client.from("posts").select("*").execute }
+      #     users, posts = users_task.wait, posts_task.wait
+      #   end
+      class Client < Supabase::Postgrest::Client
+        private
+
+        def build_session
+          Faraday.new(url: @base_url, ssl: { verify: @verify }, proxy: @proxy) do |f|
+            if @timeout
+              f.options.timeout = @timeout
+              f.options.open_timeout = @timeout
+            end
+            f.adapter :async_http
+          end
+        end
+      end
+    end
+  end
+end

data/lib/supabase/postgrest/async.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Convenience requirer for the async tree, mirroring lib/supabase/auth/async.rb.
+# Plain `require "supabase/postgrest"` stays free of async-http-faraday so
+# sync-only consumers don't pay for the fiber stack.
+
+require_relative "../postgrest"
+require_relative "async/client"

data/lib/supabase/postgrest/client.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+require_relative "request_builder"
+require_relative "version"
+
+module Supabase
+  module Postgrest
+    DEFAULT_HEADERS = {
+      "Accept" => "application/json",
+      "Content-Type" => "application/json"
+    }.freeze
+
+    # Sync PostgREST client. Constructed once per project; reused across requests.
+    #
+    # ```ruby
+    # client = Supabase::Postgrest::Client.new(
+    #   base_url: "https://project.supabase.co/rest/v1",
+    #   headers: { "apikey" => key, "Authorization" => "Bearer #{token}" }
+    # )
+    #
+    # users = client.from("users").select("id, name").eq("status", "active").execute
+    # users.data       # => [{ "id" => "...", "name" => "..." }, ...]
+    # users.count      # => nil unless a count: was requested
+    # ```
+    class Client
+      attr_reader :base_url, :headers, :schema_name
+
+      # @param base_url [String] full URL to the PostgREST endpoint (e.g. ".../rest/v1")
+      # @param schema [String] postgres schema (default "public")
+      # @param headers [Hash] static request headers (apikey, Authorization)
+      # @param http_client [Faraday::Connection, nil] inject a pre-built Faraday for tests/custom adapters
+      # @param verify [Boolean] TLS cert verification
+      # @param proxy [String, nil] HTTP proxy URL
+      # @param timeout [Numeric, nil] per-request timeout (seconds)
+      def initialize(base_url:, schema: "public", headers: {}, http_client: nil,
+                     verify: true, proxy: nil, timeout: nil)
+        @base_url = base_url.to_s.chomp("/")
+        @schema_name = schema
+        @headers = build_default_headers(schema, headers)
+        @http_client = http_client
+        @verify = verify
+        @proxy = proxy
+        @timeout = timeout
+      end
+
+      # Switch schemas. Returns a new client that points at a different postgres schema.
+      # @param name [String]
+      # @return [Client]
+      def schema(name)
+        # self.class so async subclasses return an async client, not a sync one.
+        self.class.new(
+          base_url: @base_url, schema: name,
+          headers: @headers.reject { |k, _| %w[Accept-Profile Content-Profile].include?(k) },
+          http_client: @http_client, verify: @verify, proxy: @proxy, timeout: @timeout
+        )
+      end
+
+      # @param table [String]
+      # @return [RequestBuilder] entry point for select/insert/update/upsert/delete on this table
+      def from(table)
+        RequestBuilder.new(session, "#{base_path}/#{table}", @headers.dup)
+      end
+
+      alias table from
+
+      # Stored procedure call.
+      # @param func [String] function name
+      # @param params [Hash] arguments to the function
+      # @param count [String, nil] one of "exact" / "planned" / "estimated"
+      # @param head [Boolean] HEAD method (count only, no body)
+      # @param get [Boolean] GET method (read-only)
+      # @return [RPCFilterRequestBuilder]
+      def rpc(func, params = {}, count: nil, head: false, get: false)
+        method = if head
+                   "HEAD"
+                 elsif get
+                   "GET"
+                 else
+                   "POST"
+                 end
+
+        headers = @headers.dup
+        headers["Prefer"] = "count=#{count}" if count
+
+        if %w[HEAD GET].include?(method)
+          query = stringify_keys(params)
+          body = nil
+        else
+          query = {}
+          body = params
+        end
+
+        request = RequestConfig.new(
+          session: session, path: "#{base_path}/rpc/#{func}",
+          http_method: method, headers: headers, params: query, json: body
+        )
+        RPCFilterRequestBuilder.new(request)
+      end
+
+      private
+
+      def build_default_headers(schema, user_headers)
+        defaults = DEFAULT_HEADERS.merge(
+          "X-Client-Info" => "supabase-rb/postgrest-rb v#{VERSION}"
+        )
+        defaults["Accept-Profile"] = schema
+        defaults["Content-Profile"] = schema
+        defaults.merge(user_headers)
+      end
+
+      def session
+        @session ||= @http_client || build_session
+      end
+
+      def build_session
+        Faraday.new(url: @base_url, ssl: { verify: @verify }, proxy: @proxy) do |f|
+          if @timeout
+            f.options.timeout = @timeout
+            f.options.open_timeout = @timeout
+          end
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      def base_path
+        URI.parse(@base_url).path.chomp("/")
+      end
+
+      def stringify_keys(hash)
+        hash.each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+      end
+    end
+  end
+end

data/lib/supabase/postgrest/errors.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Postgrest
+    module Errors
+      # Raised when the PostgREST server returns a non-success status.
+      # Mirrors supabase-py's APIError — exposes :message, :code, :hint, :details
+      # plus the raw error hash via {#raw}.
+      class APIError < StandardError
+        attr_reader :raw, :message, :code, :hint, :details
+
+        # @param error [Hash] parsed JSON body from a PostgREST error response
+        def initialize(error = {})
+          @raw = error || {}
+          @message = @raw["message"] || @raw[:message]
+          @code = @raw["code"] || @raw[:code]
+          @hint = @raw["hint"] || @raw[:hint]
+          @details = @raw["details"] || @raw[:details]
+          super(to_s)
+        end
+
+        def to_s
+          parts = []
+          parts << "Error #{@code}:" if @code
+          parts << "\nMessage: #{@message}" if @message
+          parts << "\nHint: #{@hint}" if @hint
+          parts << "\nDetails: #{@details}" if @details
+          result = parts.join
+          result.empty? ? "Empty error" : result
+        end
+
+        # @return [Hash] the raw error payload as received
+        def json
+          @raw
+        end
+      end
+
+      # Builds a fallback error payload when the server body isn't valid JSON.
+      def self.generate_default_error_message(response)
+        {
+          "message" => "JSON could not be generated",
+          "code" => response.status.to_s,
+          "hint" => "Refer to full message for details",
+          "details" => response.body.to_s
+        }
+      end
+    end
+  end
+end