pool_connection

Pool Connection Abstraction

Provides types and utilities for database connections. The actual connection handling is delegated to driver packages (glimr_sqlite, glimr_postgres) which register with the driver registry.

Types

Config

</>

Configuration for establishing a database connection. Use postgres_config, postgres_params_config, or sqlite_config to create instances.

pub type Config {
  PostgresConfig(url: String, pool_size: Int)
  PostgresParamsConfig(
    host: String,
    port: Int,
    database: String,
    username: String,
    password: option.Option(String),
    pool_size: Int,
  )
  SqliteConfig(path: String, pool_size: Int)
}

Constructors

PostgresConfig(url: String, pool_size: Int)

PostgresParamsConfig(
  host: String,
  port: Int,
  database: String,
  username: String,
  password: option.Option(String),
  pool_size: Int,
)

SqliteConfig(path: String, pool_size: Int)

DbError

</>

Unified error type for database operations. Provides specific error variants for common failure cases, allowing precise error handling in application code.

pub type DbError {
  NotFound
  ConstraintError(message: String, constraint: String)
  QueryError(message: String)
  ConnectionError(message: String)
  TimeoutError
  DecodeError(message: String)
  ConfigError(message: String)
}

Constructors

```
NotFound
```
The requested row was not found (for single-row queries)

ConstraintError(message: String, constraint: String)

A constraint was violated (unique, foreign key, etc.)

```
QueryError(message: String)
```
A query syntax or execution error
```
ConnectionError(message: String)
```
Connection to database failed or unavailable
```
TimeoutError
```
Query timed out
```
DecodeError(message: String)
```
Result decoding failed
```
ConfigError(message: String)
```
Connection configuration is invalid or missing required parameters

Driver

</>

Identifies which database driver is being used. This allows you to seamlessly use multiple connections of different database drivers throughout your app.

pub type Driver {
  Postgres
  Sqlite
}

Constructors

```
Postgres
```
```
Sqlite
```

PoolConnection

opaque </>

A pooled database connection that wraps the underlying driver connection. The actual connection is stored as Dynamic and unwrapped by driver packages.

pub opaque type PoolConnection

QueryResult

</>

The result of a database query, containing the number of affected rows and the list of decoded row data. The count is useful for INSERT/UPDATE/DELETE operations.

pub type QueryResult(t) {
  QueryResult(count: Int, rows: List(t))
}

Constructors

```
QueryResult(count: Int, rows: List(t))
```

Value

</>

A parameter value that can be passed to a database query. Use the constructor functions (int, string, bool, etc.) to create type-safe parameter values.

pub type Value {
  IntValue(Int)
  FloatValue(Float)
  StringValue(String)
  BoolValue(Bool)
  NullValue
  BlobValue(BitArray)
}

Constructors

```
IntValue(Int)
```
```
FloatValue(Float)
```
```
StringValue(String)
```
```
BoolValue(Bool)
```
```
NullValue
```
```
BlobValue(BitArray)
```

Values

blob

</>

pub fn blob(value: BitArray) -> Value

Creates a binary/blob parameter value for storing raw bytes in the database. Maps to BYTEA in PostgreSQL and BLOB in SQLite.

bool

</>

pub fn bool(value: Bool) -> Value

Creates a boolean parameter value for use in database queries. PostgreSQL uses native BOOLEAN, while SQLite stores booleans as integers (0/1).

convert_placeholders

</>

pub fn convert_placeholders(
  sql: String,
  driver: Driver,
) -> String

Converts $1, $2, etc. placeholders to ? for SQLite. This allows using consistent Postgres-style placeholders in SQL files.

driver

</>

pub fn driver(connection: PoolConnection) -> Driver

Returns the driver type for the provided pool connection. Useful for conditionally handling driver-specific behavior in application code.

float

</>

pub fn float(value: Float) -> Value

Creates a floating-point parameter value for use in database queries. Maps to REAL/DOUBLE PRECISION depending on the database driver.

get_pool_ref

</>

pub fn get_pool_ref(
  connection: PoolConnection,
) -> dynamic.Dynamic

Extracts the pool reference from a pool connection. This reference must be passed to checkin when returning the connection to the pool.

int

</>

pub fn int(value: Int) -> Value

Creates an integer parameter value for use in database queries. Maps to INTEGER type in both PostgreSQL and SQLite databases.

null

</>

pub fn null() -> Value

Creates a NULL parameter value for use in database queries. Use this for optional fields where the value should be stored as database NULL.

nullable

</>

pub fn nullable(
  inner: fn(a) -> Value,
  value: option.Option(a),
) -> Value

Creates a parameter value from an Option, converting None to NULL. Pass the appropriate constructor function for the inner type (e.g., nullable(int, some_option)).

postgres_config

</>

pub fn postgres_config(
  url: String,
  pool_size pool_size: Int,
) -> Config

Creates a PostgreSQL configuration from a connection URL. This configuration will have its own pool of connections specific to this database.

URL format: postgresql://user:password@host:port/database

Example:

let config = postgres_config(
  "postgresql://postgres:secret@localhost:5432/myapp",
  pool_size: 10,
)

postgres_params_config

</>

pub fn postgres_params_config(
  host host: String,
  port port: Int,
  database database: String,
  username username: String,
  password password: option.Option(String),
  pool_size pool_size: Int,
) -> Config

Creates a PostgreSQL configuration from individual parameters. This is an alternative to postgres_config when you have separate host, port, database, username, and password values.

Example:

let config = postgres_params_config(
  host: "localhost",
  port: 5432,
  database: "myapp",
  username: "postgres",
  password: Some("secret"),
  pool_size: 10,
)

sqlite_config

</>

pub fn sqlite_config(
  path: String,
  pool_size pool_size: Int,
) -> Config

Creates a SQLite configuration from a file path. This configuration will have its own pool of connections specific to this database.

Use :memory: for an in-memory database.

Example:

let config = sqlite_config("data.db", pool_size: 5)
let memory_config = sqlite_config(":memory:", pool_size: 1)

string

</>

pub fn string(value: String) -> Value

Creates a string/text parameter value for use in database queries. Maps to TEXT/VARCHAR depending on the database driver and column type.

unwrap_handle

</>

pub fn unwrap_handle(
  connection: PoolConnection,
) -> dynamic.Dynamic

Gets the raw connection handle as Dynamic. Used by driver packages to unwrap and cast to the native connection type for executing queries.

wrap_connection

</>

pub fn wrap_connection(
  driver: Driver,
  handle: dynamic.Dynamic,
  pool_ref: dynamic.Dynamic,
) -> PoolConnection

Creates a pool connection wrapper from driver-specific handles. Called by driver packages when checking out a connection from the pool.