postgres

Types

BatchConfig

Configuration for batch operations

pub type BatchConfig {
  BatchConfig(max_values_per_insert: Int, use_transaction: Bool)
}

Constructors

```
BatchConfig(max_values_per_insert: Int, use_transaction: Bool)
```
Arguments

max_values_per_insert

Maximum rows per INSERT statement (limits VALUES clause size)

use_transaction

Wrap entire batch in a transaction

PostgresConfig

</>

PostgreSQL connection configuration. This wraps pog.Config with cquill-specific defaults.

pub type PostgresConfig {
  PostgresConfig(
    pool_name: process.Name(pog.Message),
    host: String,
    port: Int,
    database: String,
    user: String,
    password: option.Option(String),
    ssl: pog.Ssl,
    pool_size: Int,
    default_timeout: Int,
    idle_interval: Int,
  )
}

Constructors

```
PostgresConfig(
  pool_name: process.Name(pog.Message),
  host: String,
  port: Int,
  database: String,
  user: String,
  password: option.Option(String),
  ssl: pog.Ssl,
  pool_size: Int,
  default_timeout: Int,
  idle_interval: Int,
)
```
Arguments

pool_name

Pool name for process registration

host

Database server hostname (default: “127.0.0.1”)

port

Port the server is listening on (default: 5432)

database

Name of database to use

user

Username to connect to database as

password

Password for the user (None for no password)

ssl

SSL mode (default: SslDisabled)

pool_size

Number of connections in the pool (default: 10)

default_timeout

Default query timeout in milliseconds (default: 5000)

idle_interval

Interval in ms to ping idle connections (default: 1000)

PostgresConnection

opaque </>

PostgreSQL connection handle. This wraps pog.Connection which represents a pool.

pub opaque type PostgresConnection

TransactionError

</>

Transaction error type for the higher-level API

pub type TransactionError {
  QueryError(error.AdapterError)
  RolledBack(String)
}

Constructors

```
QueryError(error.AdapterError)
```
```
RolledBack(String)
```

Values

batch_delete_all

</>

pub fn batch_delete_all(
  conn: PostgresConnection,
  table: String,
  where_clause: String,
  where_params: List(adapter.QueryParam),
) -> Result(Int, error.AdapterError)

Delete all rows matching a condition. Returns the number of deleted rows.

batch_delete_all_returning

</>

pub fn batch_delete_all_returning(
  conn: PostgresConnection,
  table: String,
  where_clause: String,
  where_params: List(adapter.QueryParam),
) -> Result(List(List(dynamic.Dynamic)), error.AdapterError)

Delete all rows matching a condition and return deleted rows.

batch_update_all

</>

pub fn batch_update_all(
  conn: PostgresConnection,
  table: String,
  set_clauses: List(#(String, adapter.QueryParam)),
  where_clause: String,
  where_params: List(adapter.QueryParam),
) -> Result(Int, error.AdapterError)

Update all rows matching a condition. Returns the number of updated rows.

Example: update_all(conn, “users”, [#(“active”, adapter.param_bool(False))], “created_at < $1”, [adapter.param_string(“2024-01-01”)])

batch_update_all_returning

</>

pub fn batch_update_all_returning(
  conn: PostgresConnection,
  table: String,
  set_clauses: List(#(String, adapter.QueryParam)),
  where_clause: String,
  where_params: List(adapter.QueryParam),
) -> Result(List(List(dynamic.Dynamic)), error.AdapterError)

Update all rows matching a condition and return updated rows.

config_from_url

</>

pub fn config_from_url(
  pool_name: process.Name(pog.Message),
  url: String,
) -> Result(PostgresConfig, Nil)

Create configuration from a database URL. URL format: postgresql://user:password@host:port/database

create_savepoint

</>

pub fn create_savepoint(
  conn: PostgresConnection,
  name: String,
) -> Result(Nil, error.SavepointError(Nil))

Create a savepoint with the given name. Savepoints allow partial rollback within a transaction. The connection must be within an active transaction.

decode_bool

</>

pub fn decode_bool(
  row: List(dynamic.Dynamic),
  index: Int,
) -> Result(Bool, Nil)

Decode a single bool value from a result row

decode_float

</>

pub fn decode_float(
  row: List(dynamic.Dynamic),
  index: Int,
) -> Result(Float, Nil)

Decode a single float value from a result row

decode_int

</>

pub fn decode_int(
  row: List(dynamic.Dynamic),
  index: Int,
) -> Result(Int, Nil)

Decode a single integer value from a result row

decode_optional

</>

pub fn decode_optional(
  row: List(dynamic.Dynamic),
  index: Int,
  decoder: decode.Decoder(a),
) -> Result(option.Option(a), Nil)

Decode an optional value from a result row

decode_string

</>

pub fn decode_string(
  row: List(dynamic.Dynamic),
  index: Int,
) -> Result(String, Nil)

Decode a single string value from a result row

default_config

</>

pub fn default_config(
  pool_name: process.Name(pog.Message),
) -> PostgresConfig

Create a default configuration with a pool name.

default_timeout

</>

pub fn default_timeout(
  config: PostgresConfig,
  timeout_ms: Int,
) -> PostgresConfig

Set the default query timeout in milliseconds. Queries taking longer than this will be aborted with a Timeout error. Default is 5000ms (5 seconds).

delete_all_rows

</>

pub fn delete_all_rows(
  conn: PostgresConnection,
  table: String,
) -> Result(Int, error.AdapterError)

Delete all rows in a table (truncate-like operation). Returns the number of deleted rows.

execute_savepoint

</>

pub fn execute_savepoint(
  conn: PostgresConnection,
  name: String,
  operation: fn(PostgresConnection) -> Result(
    a,
    error.AdapterError,
  ),
) -> Result(a, error.SavepointError(Nil))

Execute a function within a savepoint. If the function succeeds, the savepoint is released. If the function fails, changes are rolled back to the savepoint. This must be called within an active transaction.

execute_savepoint_with_user_error

</>

pub fn execute_savepoint_with_user_error(
  conn: PostgresConnection,
  name: String,
  operation: fn(PostgresConnection) -> Result(a, e),
) -> Result(a, error.SavepointError(e))

Execute a function within a savepoint, allowing user errors. If the function succeeds, the savepoint is released. If the function fails, changes are rolled back to the savepoint.

execute_sql

</>

pub fn execute_sql(
  conn: PostgresConnection,
  sql: String,
  params: List(adapter.QueryParam),
) -> Result(List(List(dynamic.Dynamic)), error.AdapterError)

Execute a raw SQL query with parameters. Returns rows as List(Dynamic).

execute_sql_mutation

</>

pub fn execute_sql_mutation(
  conn: PostgresConnection,
  sql: String,
  params: List(adapter.QueryParam),
) -> Result(Int, error.AdapterError)

Execute a raw SQL mutation with parameters. Returns the number of affected rows.

execute_sql_mutation_with_timeout

</>

pub fn execute_sql_mutation_with_timeout(
  conn: PostgresConnection,
  sql: String,
  params: List(adapter.QueryParam),
  timeout_ms: Int,
) -> Result(Int, error.AdapterError)

Execute a raw SQL mutation with a custom timeout. The timeout is in milliseconds.

execute_sql_with_timeout

</>

pub fn execute_sql_with_timeout(
  conn: PostgresConnection,
  sql: String,
  params: List(adapter.QueryParam),
  timeout_ms: Int,
) -> Result(List(List(dynamic.Dynamic)), error.AdapterError)

Execute a raw SQL query with a custom timeout. The timeout is in milliseconds. Use this for queries that may take longer than the default 5 second timeout.

execute_transaction

</>

pub fn execute_transaction(
  conn: PostgresConnection,
  operation: fn(PostgresConnection) -> Result(
    a,
    error.AdapterError,
  ),
) -> Result(a, error.TransactionError(Nil))

Execute a transaction with automatic error handling. This version uses the standard cquill TransactionError type.

On success: commits and returns the result
On adapter error (constraint violation, etc.): rolls back and returns AdapterTransactionError
On pog query error during transaction: returns AdapterTransactionError

execute_transaction_with_user_error

</>

pub fn execute_transaction_with_user_error(
  conn: PostgresConnection,
  operation: fn(PostgresConnection) -> Result(a, e),
) -> Result(a, error.TransactionError(e))

Execute a transaction with a user error type. This version allows the operation to return a custom error type.

On success: commits and returns the result
On user error: rolls back and returns UserError
On pog query error during transaction: returns AdapterTransactionError

host

</>

pub fn host(
  config: PostgresConfig,
  host: String,
) -> PostgresConfig

Set the database host

idle_interval

</>

pub fn idle_interval(
  config: PostgresConfig,
  interval_ms: Int,
) -> PostgresConfig

Set the idle connection ping interval in milliseconds. The database is pinged every idle_interval when the connection is idle. This helps detect and recover from stale connections. Default is 1000ms (1 second).

insert_all

</>

pub fn insert_all(
  conn: PostgresConnection,
  table: String,
  columns: List(String),
  rows: List(List(adapter.QueryParam)),
) -> Result(Int, error.AdapterError)

Insert multiple rows using a multi-value INSERT statement. This is more efficient than individual inserts.

Example SQL generated: INSERT INTO users (email, name) VALUES ($1, $2), ($ 3, $4), ($ 5, $6)

insert_all_returning

</>

pub fn insert_all_returning(
  conn: PostgresConnection,
  table: String,
  columns: List(String),
  rows: List(List(adapter.QueryParam)),
) -> Result(List(List(dynamic.Dynamic)), error.AdapterError)

Insert multiple rows and return the inserted rows. Uses RETURNING * to get all inserted data.

insert_all_with_config

</>

pub fn insert_all_with_config(
  conn: PostgresConnection,
  table: String,
  columns: List(String),
  rows: List(List(adapter.QueryParam)),
  config: BatchConfig,
) -> Result(Int, error.AdapterError)

Insert multiple rows with configuration options.

named_connection

</>

pub fn named_connection(
  name: process.Name(pog.Message),
) -> PostgresConnection

Create a connection reference to a named pool. Use this when you’ve started a pool with supervision and need to reference it by name.

password

</>

pub fn password(
  config: PostgresConfig,
  password: option.Option(String),
) -> PostgresConfig

Set the database password

pool_size

</>

pub fn pool_size(
  config: PostgresConfig,
  pool_size: Int,
) -> PostgresConfig

Set the connection pool size

port

</>

pub fn port(config: PostgresConfig, port: Int) -> PostgresConfig

Set the database port

postgres_adapter

</>

pub fn postgres_adapter() -> adapter.Adapter(
  PostgresConnection,
  List(dynamic.Dynamic),
)

Create a PostgreSQL adapter. This implements the full adapter interface for PostgreSQL.

postgres_capabilities

</>

pub fn postgres_capabilities() -> adapter.AdapterCapabilities

PostgreSQL adapter capabilities - full SQL support

release_savepoint

</>

pub fn release_savepoint(
  conn: PostgresConnection,
  name: String,
) -> Result(Nil, error.SavepointError(Nil))

Release a savepoint without rolling back. This destroys the savepoint but keeps all changes made after it. This is useful to free up resources when a savepoint is no longer needed.

rollback_to_savepoint

</>

pub fn rollback_to_savepoint(
  conn: PostgresConnection,
  name: String,
) -> Result(Nil, error.SavepointError(Nil))

Rollback to a named savepoint. All changes made after the savepoint was created are discarded. The savepoint remains active and can be rolled back to again.

ssl

</>

pub fn ssl(
  config: PostgresConfig,
  ssl: pog.Ssl,
) -> PostgresConfig

Set SSL mode

start

</>

pub fn start(
  config: PostgresConfig,
) -> Result(PostgresConnection, actor.StartError)

Start a connection pool using the provided configuration. Returns a PostgresConnection that can be used for queries.

user

</>

pub fn user(
  config: PostgresConfig,
  user: String,
) -> PostgresConfig

Set the database user

with_transaction

</>

pub fn with_transaction(
  conn: PostgresConnection,
  operation: fn(PostgresConnection) -> Result(a, String),
) -> Result(a, TransactionError)

Run a function within a PostgreSQL transaction. This uses pog’s native transaction support which provides proper transaction isolation and automatic commit/rollback.

Constructors

Arguments

Constructors

Arguments

Constructors