PgORM::Database

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

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.

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")

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"]?)

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