User.where(active: true).order(:last_name).limit(20).to_a
User.find!(42)
User.where(age: 18..65).count
User.create!(name: "Alice", email: "alice@example.com")
User.where(active: false).update_all(status: "archived")

gem "active_postgrest", "~> 0.2"

# Global connection via environment variable POSTGREST_URL
class ApplicationRecord < ActivePostgrest::Base
  establish_connection url: "http://localhost:3000", jwt_token: ENV["POSTGREST_JWT"]
end

class User < ApplicationRecord; end
class Company < ApplicationRecord; end

ApplicationRecord.establish_connection(
  url:       "http://localhost:3000",
  jwt_token: ENV["POSTGREST_JWT"]
)

ApplicationRecord.establish_connection(url: "http://localhost:3000")

# Default connection has a JWT token
ApplicationRecord.establish_connection(url: "...", jwt_token: ENV["POSTGREST_JWT"])

# This query runs without Authorization header
User.anonymous.where(active: true).to_a
User.anonymous.find!(42)
User.where(role: "guest").anonymous.limit(10).to_a

User.with_token(current_jwt).where(active: true).to_a
User.with_token(current_jwt).find!(42)

# config/initializers/postgrest.rb
ApplicationRecord.establish_connection(url: ENV["POSTGREST_URL"])
# no global token — anonymous by default

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  def postgrest_scope(model)
    model.with_token(postgrest_jwt)
  end

  def postgrest_jwt
    # build a short-lived JWT from the current session
    JWT.encode({ user_id: current_user.id, role: "authenticated" }, ENV["JWT_SECRET"])
  end
end

# app/controllers/documents_controller.rb
def index
  @documents = postgrest_scope(Document).where(status: "published").order(:created_at)
end

# Default schema for an entire model (sent as Accept-Profile header on every request)
class AnalyticsEvent < ApplicationRecord
  self.schema_name = "analytics"
end

AnalyticsEvent.where(type: "click").count   # Accept-Profile: analytics

# Subclasses inherit the schema
class PageView < AnalyticsEvent; end
PageView.where(path: "/home").to_a          # Accept-Profile: analytics

# Per-request override — does not affect the default connection
User.with_schema("private").where(active: true).to_a   # Accept-Profile: private
User.where(active: true).to_a                           # no Accept-Profile header

class User < ActivePostgrest::Base
  # Override inferred table name (default: "users")
  self.table_name = "users"
  # Override primary key (default: "id")
  self.primary_key = "id"

  # Declare attribute type casts (optional — untyped attrs pass through as-is)
  attribute :birth_date, :date
  attribute :created_at, :datetime
  attribute :score,      :decimal

  belongs_to :company
  has_many   :posts
  has_one    :profile
end

User.where(name: "Alice")             # name=eq.Alice
User.where(deleted_at: nil)           # deleted_at=is.null
User.where(active: true)              # active=is.true
User.where(id: [1, 2, 3])            # id=in.(1,2,3)
User.where(age: 18..30)              # age=gte.18&age=lte.30  (inclusive)
User.where(age: 18...30)             # age=gte.18&age=lt.30   (exclusive end)
User.where(age: { gt: 18, lt: 65 }) # age=gt.18&age=lt.65
User.where.not(name: "Bob")          # name=not.eq.Bob
User.not_where(status: "banned")     # status=not.eq.banned

User.where(name: { ilike: "%alice%" })
User.where(tags: { cs: "{ruby,rails}" })
User.where(name: { match: "^A.*son$" })   # POSIX regex
User.where(bio: { wfts: "ruby rails" })   # websearch full-text

# Simple OR
User.where(active: true).or(User.where(role: "admin"))
# → or=(active.is.true,role.eq.admin)

# Multiple AND conditions on one side are wrapped automatically
User.where(active: true).where(age: { gt: 18 }).or(User.where(role: "admin"))
# → or=(and(active.is.true,age.gt.18),role.eq.admin)

User.or_where([{ age: { lt: 18 } }, { status: "inactive" }])
# → or=(age.lt.18,status.eq.inactive)

User.and_where([{ age: { gt: 18 } }, { role: "admin" }])
# → and=(age.gt.18,role.eq.admin)

User.order(:last_name)                          # order=last_name.asc
User.order(:created_at, :desc)                  # order=created_at.desc
User.order(:name, :asc, nulls: :last)           # order=name.asc.nullslast
User.order(:name, :desc, nulls: :first)         # order=name.desc.nullsfirst
User.reorder(:id)                               # replaces any previous order
User.limit(10).offset(20)

User.select(:id, :name, :email)     # select=id,name,email

User.spread(:companies)
# select=...companies
# → { id: 1, name: "Alice", company_id: 5, company_name: "Acme" }
# instead of { id: 1, name: "Alice", companies: { id: 5, name: "Acme" } }

User.select(:id, :name).spread(:companies)
# select=id,name,...companies

User.spread(:companies, :profiles)
# select=...companies,...profiles

# INNER JOIN — only users that have a matching company (like ActiveRecord default)
User.joins(:companies)
User.joins(:companies, select: [:id, :name])

# LEFT JOIN — all users, company data is nil when no match
User.left_joins(:companies)
User.left_joins(:companies, select: [:id, :name])

# Filter on joined table — AR style
User.joins(:companies).where(companies: { name: "Acme" })
User.joins(:companies).where(companies: { active: true })

# Aliased join with explicit foreign key (self-referential tables)
User.joins(:users, as: :mother, foreign_key: :mother_id)

# Embed via computed relationship name (PostgREST functions)
User.embed(:profile)
User.embed(:profile, fields: [:bio, :avatar])

class User < ActivePostgrest::Base
  scope :active, -> { where(active: true) }
  scope :admins, -> { where(role: "admin") }
end

User.active.admins.order(:name)

User.all                          # Relation (lazy)
User.to_a                         # Array of model instances
User.first                        # first record
User.last                         # last record (ordered by pk desc)
User.first(5)                     # Array of 5
User.last(5)                      # Array of 5 (order preserved)
User.find(42)                     # nil if not found
User.find!(42)                    # raises RecordNotFound if not found
User.find_by(email: "a@b.com")   # nil if not found
User.find_by!(email: "a@b.com")  # raises RecordNotFound if not found
User.none                         # empty relation, no HTTP request made

User.count                        # exact COUNT(*) — default
User.any?
User.none?
User.one?
User.many?
User.exists?
User.where(active: true).count

User.count              # :exact   — real COUNT(*), always accurate
User.count(:planned)    # :planned — estimate from query planner (EXPLAIN)
User.count(:estimated)  # :estimated — from pg_class.reltuples, near-instant

User.average(:age)                # => "32.4"
User.sum(:score)                  # => "15000"
User.minimum(:age)                # => "18"
User.maximum(:age)                # => "75"

# Filters are respected
User.where(active: true).average(:age)
User.joins(:companies).where(companies: { name: "Acme" }).maximum(:score)

User.pluck(:id)                   # [1, 2, 3, ...]
User.pluck(:id, :name)            # [[1, "Alice"], [2, "Bob"], ...]
User.pick(:email)                 # "alice@example.com" (first match)

# Returns a persisted instance (or nil on empty response)
User.create(name: "Alice", email: "alice@example.com")

# Raises if creation fails: UnprocessableEntity on constraint violations (422),
# RecordNotSaved if PostgREST returns no body
User.create!(name: "Alice")

# Bulk insert — returns array of persisted records
User.insert_all([{ name: "Alice" }, { name: "Bob" }])

# Single upsert — uses PostgREST resolution=merge-duplicates
User.upsert(id: 1, name: "Alice Updated")

# Bulk upsert
User.upsert_all([
  { id: 1, name: "Alice Updated" },
  { id: 2, name: "Bob New" }
])

# Bulk — updates all matching rows, returns updated records
User.where(active: false).update_all(status: "archived")
User.where(role: "trial").update_all(expires_at: 30.days.from_now)

# Instance
user = User.find!(1)
user.update(name: "New Name")   # merges attrs and saves
user.name = "Other"
user.save                        # returns true/false

# Bulk — deletes all matching rows, returns deleted records
User.where(created_at: ..1.year.ago).delete_all
User.where(active: false).delete_all

# Instance
user.destroy          # DELETE by primary key; record is marked as destroyed
user.destroyed?       # => true
user.persisted?       # => false
user.save             # => false (destroyed records cannot be re-inserted this way)

user = User.find!(1)
user.name = "Local change"
user.reload   # re-fetches from DB, discards local changes

User.new(name: "Alice").new_record?   # => true
User.find!(1).persisted?              # => true

user = User.new(name: "Alice")
user.save          # inserts, marks as persisted
user.persisted?    # => true

user.destroy
user.destroyed?    # => true
user.new_record?   # => false

# Both GET and PATCH run under user_jwt
user = User.with_token(user_jwt).find!(1)
user.update(name: "New Name")   # uses user_jwt, not the class default connection

User.with_token(user_jwt).create!(name: "Alice")   # INSERT under user_jwt

require 'active_postgrest'
require 'active_postgrest/active_model'

require 'active_postgrest/railtie'

class User < ActivePostgrest::Base
  validates :name, presence: true
  validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
end

user = User.new(email: "bad")
user.valid?           # => false
user.errors[:name]    # => ["can't be blank"]
user.save             # => false — validation failed, no HTTP request made

user = User.new(name: "Alice", email: "alice@example.com")
user.save             # => true — validates then POST

class User < ActivePostgrest::Base
  belongs_to :company
  belongs_to :mother, class_name: "User", foreign_key: :mother_id
  has_many   :posts
  has_one    :profile
end

User.with_company                        # joins companies
User.with_company(fields: [:id, :name])  # joins companies, select id,name
User.with_posts
User.with_mother                         # aliased self-join

user = User.with_company.find!(1)
user.company.name   # works — company data was embedded

# Via connection object
User.connection.tables          # ["users", "companies", ...]
User.connection.table_schema("users")  # raw OpenAPI definition hash

# Via model
User.schema                     # raw definition hash
User.attributes                 # { "id" => "integer", "name" => "text", ... }

User.where(active: true).limit(10).to_url
# => "http://localhost:3000/users?active=is.true&limit=10"

User.joins(:companies).where(active: true).to_sql
# => "SELECT *, companies!inner(*)\nFROM users\nWHERE active IS TRUE"
# Reconstructed from relation state — no HTTP call. See method docs for limitations.

User.where(active: true).explain
# Returns PostgREST EXPLAIN plan (requires PostgREST ≥ 10)

User.where(active: true)
User.where(age: { gt: 18 })
User.where(companies: { name: "Acme" })   # AR-style join filter
User.where.not(name: "Bob")
User.joins(:companies)                     # INNER JOIN
User.left_joins(:companies)               # LEFT JOIN
User.order(:name, :desc)
User.limit(10).offset(20)
User.select(:id, :name)
User.find(1) / find!(1) / find_by / find_by!
User.count / any? / none? / one? / many? / exists?
User.average(:age) / sum(:amount) / minimum(:age) / maximum(:age)
User.pluck(:name) / pick(:name)
User.first / last
User.scope :active, -> { where(active: true) }
User.create / create! / insert / insert_all / upsert / upsert_all
User.where(...).update_all / delete_all
user.save / update / destroy / reload
User.where(a: 1).or(User.where(b: 2))       # AR-style OR

# Same as AR — chaining where + or
User.where(active: true).or(User.where(role: "admin"))
User.where(active: true).where(age: { gt: 18 }).or(User.where(role: "admin"))

# PostgREST-specific — pass an array of conditions
User.or_where([{ age: 18 }, { role: "admin" }])
User.and_where([{ age: { gt: 18 } }, { active: true }])

# AR
User.order(Arel.sql("name ASC NULLS LAST"))

# active_postgrest
User.order(:name, :asc, nulls: :last)

# AR
User.where("name ~ ?", "^A")

# active_postgrest
User.where(name: { match: "^A" })
User.where(name: { imatch: "^a" })   # case-insensitive

User.average(:age).to_f     # => 32.4
User.sum(:score).to_i       # => 15000

User.joins(:companies).where(active: true).to_sql
# => "SELECT *, companies!inner(*)\nFROM users\nWHERE active IS TRUE"

User.embed(:profile, fields: [:bio])              # computed relationship embedding
User.joins(:companies, where: { active: true })   # join-level filter shorthand
User.where(active: true).to_url                   # inspect the generated URL
User.where(active: true).explain                  # PostgREST EXPLAIN plan
User.with_schema("analytics").where(active: true) # per-request schema switch
User.count(:planned)                              # approximate count from query planner
User.count(:estimated)                            # near-instant count from pg_class