module PgORM::Database

Extended Modules

Defined in:

pg-orm/database.cr

Class Method Summary

Class Method Detail

def self.adapter(builder : Query::Builder) : PostgreSQL #

[View source]
def self.begin_transaction : DB::Transaction #

[View source]
def self.checkout : DB::Connection #

[View source]
def self.configure(&) : Nil #

Configures database connection settings.

This also enables change data capture (CDC) for real-time notifications.

Example

PgORM::Database.configure do |settings|
  settings.host = "db.example.com"
  settings.port = 5432
  settings.db = "production"
  settings.user = "app_user"
  settings.password = ENV["DB_PASSWORD"]
end

[View source]
def self.connection(read : Bool = false, &) #

Yields a database connection.

Routing rules:

  • If the current fiber already holds a pinned connection (i.e. we are inside a transaction or an explicit .with_connection block), that connection is reused — guaranteeing read-your-writes consistency.
  • Otherwise, when read is true and a replica pool is configured, the query is routed to the read-only replica.
  • Otherwise the primary pool is used.

[View source]
def self.exec_sql(sql : String, *args_) #

[View source]
def self.info : Info #

[View source]
def self.parse(uri : String | URI) : Nil #

Parses a PostgreSQL connection URL and configures the database.

This is the recommended way to configure the database in production, typically from an environment variable.

Example

# From environment variable
PgORM::Database.parse(ENV["DATABASE_URL"])

# Direct URL
PgORM::Database.parse("postgres://user:pass@localhost:5432/mydb")

[View source]
def self.parse_read(uri : String | URI | Nil) : Nil #

Configures an optional read-only replica connection.

When configured, standalone read queries (SELECTs issued outside of a transaction or an explicit .with_connection block) are routed to the replica, while all writes — and any reads inside a transaction — continue to use the primary. Pass nil to disable replica routing.

CDC/change-feed and advisory locks are intentionally NOT moved to the replica; they must run against the primary.

Example

PgORM::Database.parse_read(ENV["PG_DATABASE_READ_URL"]?)

[View source]
def self.pool : DB::Database #

[View source]
def self.quote(name : Symbol | String, io : IO) #

[View source]
def self.quote(name : Symbol | String) #

[View source]
def self.read_pool? : DB::Database | Nil #

The read-only replica connection pool, or nil when no replica is configured. Lazily opened on first use.


[View source]
def self.release : Nil #

[View source]
def self.transaction(&) #

[View source]
def self.with_connection(&) #

[View source]