Initializing

supabase-rb is a single gem that bundles Auth, PostgREST (Database), Storage, Edge Functions, and Realtime behind one umbrella client. Supabase.create_client is the entry point — pass your project URL and an API key, get back a Supabase::Client.

Install

Add the gem to your Gemfile:

# Gemfile
gem "supabase-rb"

Then run:

bundle install

Or install it directly without bundler:

gem install supabase-rb

Requires Ruby ≥ 3.1.

First query

A complete end-to-end example — install the gem, construct a client with your project URL + anon key, and read a row:

require "supabase"

supabase = Supabase.create_client(
  supabase_url: ENV.fetch("SUPABASE_URL"),
  supabase_key: ENV.fetch("SUPABASE_ANON_KEY")
)

response = supabase.from("countries").select("*").limit(1).execute
puts response.data
# => [{"id" => 1, "name" => "United Kingdom"}]

SUPABASE_URL is your project URL (e.g. https://abcd1234.supabase.co) and SUPABASE_ANON_KEY is the anon (anon) key from the project's API settings.

Construct a client

Supabase.create_client(supabase_url:, supabase_key:, options: {}, async: false)

Equivalent to Supabase::Client.new(...) but routes through Client.create, which additionally restores a persisted session (if options.persist_session is enabled and the auth storage holds one) and applies the session's access token as the bearer.

supabase = Supabase.create_client(
  supabase_url: "https://abcd1234.supabase.co",
  supabase_key: ENV.fetch("SUPABASE_ANON_KEY")
)

You can also call Supabase::Client.new(...) directly if you want to skip the persisted-session restore:

supabase = Supabase::Client.new(
  supabase_url: "https://abcd1234.supabase.co",
  supabase_key: ENV.fetch("SUPABASE_ANON_KEY")
)

ClientOptions

Supabase::ClientOptions is the typed configuration struct passed via options:. A single class covers both sync and async modes because the sync/async split is decided at runtime via the umbrella async: flag (see Async mode).

Supabase::ClientOptions.new(schema: "public",headers: nil,auto_refresh_token: true,persist_session: true,realtime: nil,postgrest_client_timeout: 120,storage_client_timeout: 20,function_client_timeout: 5,flow_type: "pkce",storage: nil,http_client: nil)

options = Supabase::ClientOptions.new(
  schema: "public",
  headers: { "X-Tenant" => "acme" },
  auto_refresh_token: true,
  persist_session: true,
  postgrest_client_timeout: 30,
  storage_client_timeout: 20,
  function_client_timeout: 10,
  flow_type: "pkce"
)

supabase = Supabase.create_client(
  supabase_url: ENV.fetch("SUPABASE_URL"),
  supabase_key: ENV.fetch("SUPABASE_ANON_KEY"),
  options: options
)

A flat hash of the same keys works equivalently — it is canonicalized into a ClientOptions instance internally:

supabase = Supabase.create_client(
  supabase_url: ENV.fetch("SUPABASE_URL"),
  supabase_key: ENV.fetch("SUPABASE_ANON_KEY"),
  options: { schema: "public", headers: { "X-Tenant" => "acme" } }
)

Global headers

Headers passed via options.headers are merged into every HTTP sub-client. The default X-Client-Info: supabase-rb/<version> header is always included so your project logs can attribute requests to the Ruby gem.

options = Supabase::ClientOptions.new(
  headers: { "X-Tenant" => "acme", "X-Request-Id" => SecureRandom.uuid }
)

Database schema

schema: sets the default Postgres schema for all PostgREST requests. To query a non-default schema for a single chain without changing this default, use client.schema("other"):

supabase.schema("private").from("audit_log").select("*").execute

Async mode

Pass async: true to swap every HTTP sub-client (auth, postgrest, storage, functions) to its async-http-faraday variant. Calls return values that integrate with the async gem's reactor.

require "async"
require "supabase"

Async do
  supabase = Supabase.create_client(
    supabase_url: ENV.fetch("SUPABASE_URL"),
    supabase_key: ENV.fetch("SUPABASE_ANON_KEY"),
    async: true
  )

  response = supabase.from("countries").select("*").execute
  puts response.data
end

Legacy nested-hash options

The original Ruby options shape — a nested hash keyed by sub-client name — is still accepted alongside ClientOptions. Existing callers don't need to migrate:

supabase = Supabase.create_client(
  supabase_url: ENV.fetch("SUPABASE_URL"),
  supabase_key: ENV.fetch("SUPABASE_ANON_KEY"),
  options: {
    auth:      { auto_refresh_token: true, persist_session: true, flow_type: "pkce" },
    postgrest: { schema: "public", timeout: 30 },
    storage:   { timeout: 20 },
    functions: { timeout: 10 },
    realtime:  { logger: Logger.new($stdout) },
    global:    { headers: { "X-Tenant" => "acme" } }
  }
)

The shape is detected automatically — presence of any of :auth, :postgrest, :functions, :global, or a Hash-valued :storage switches the client into legacy-routing mode.