pgl

PostgreSQL database client

Types

Config

opaque </>

pub opaque type Config

Connection

opaque </>

A Connection that can be a reference to the connection pool or a single checked-out connection

pub opaque type Connection

Db

opaque </>

A configured Db. Must be started via pgl.start or pgl.supervised before use. Once started, use pgl.connection to get a Connection.

pub opaque type Db

Field

</>

Error and notice message fields

pub type Field {
  Severity
  Code
  Message
  Detail
  Hint
  Position
  InternalPosition
  InternalQuery
  Where
  Schema
  Table
  Column
  DataType
  Constraint
  File
  Line
  Routine
  Other(BitArray)
}

Constructors

```
Severity
```
```
Code
```
```
Message
```
```
Detail
```
```
Hint
```
```
Position
```
```
InternalPosition
```
```
InternalQuery
```
```
Where
```
```
Schema
```
```
Table
```
```
Column
```
```
DataType
```
```
Constraint
```
```
File
```
```
Line
```
```
Routine
```
```
Other(BitArray)
```

PglError

</>

Errors that can occur when interacting with the database.

pub type PglError {
  QueryError(message: String)
  ConnectionError(message: String)
  ConnectionTimeout
  ConnectionUnavailable
  AuthenticationError(message: String)
  ProtocolError(message: String)
  SocketError(message: String)
  PostgresError(
    code: String,
    name: String,
    message: String,
    fields: dict.Dict(Field, String),
  )
}

Constructors

```
QueryError(message: String)
```
An error processing query results.
```
ConnectionError(message: String)
```
Failed to connect to the database.
```
ConnectionTimeout
```
Timed out waiting for a connection from the pool.
```
ConnectionUnavailable
```
No connections available in the pool.
```
AuthenticationError(message: String)
```
Authentication with the database failed.
```
ProtocolError(message: String)
```
An error in the PostgreSQL wire protocol.
```
SocketError(message: String)
```
A low-level socket error.

PostgresError(
  code: String,
  name: String,
  message: String,
  fields: dict.Dict(Field, String),
)

An error returned by the PostgreSQL server.

Queried

</>

Queried captures the number of rows queried, the fields that were queried, and rows returned by the query. The rows returned need to be decoded.

pub type Queried {
  Queried(
    count: Int,
    fields: List(String),
    rows: List(dynamic.Dynamic),
  )
}

Constructors

Queried(
  count: Int,
  fields: List(String),
  rows: List(dynamic.Dynamic),
)

Query

</>

Holds a SQL string and a list of query parameters.

pub type Query {
  Query(sql: String, values: List(pg_value.Value))
}

Constructors

Query(sql: String, values: List(pg_value.Value))

Ssl

</>

SSL mode for the database connection.

pub type Ssl {
  SslDisabled
  SslVerified
  SslUnverified
}

Constructors

```
SslDisabled
```
Disables SSL leaving connections unsecured. Avoid using this in production.
```
SslVerified
```
Enables SSL and checks the CA certificate.
```
SslUnverified
```
Enables SSL but does not check the CA certificate.

TransactionError

</>

Errors that can occur during a transaction.

pub type TransactionError(error) {
  RollbackError(cause: error)
  NotInTransaction
  TransactionError(message: String)
}

Constructors

```
RollbackError(cause: error)
```
The transaction callback returned an error, and the transaction was rolled back.
```
NotInTransaction
```
Attempted to commit or rollback outside of a transaction.
```
TransactionError(message: String)
```
A transaction-level query (BEGIN, COMMIT, ROLLBACK) failed.

Values

application

</>

pub fn application(conf: Config, application: String) -> Config

Name of the application connecting to the database.

batch

</>

pub fn batch(
  queries: List(Query),
  connection: Connection,
) -> Result(List(Queried), PglError)

Uses pipelining to send multiple queries to the database server without waiting for previous queries to complete. Reduces the number of network roundtrips needed for multiple queries.

begin

</>

pub fn begin(
  connection: Connection,
) -> Result(Connection, TransactionError(error))

Begins a transaction.

You should typically use pgl.transaction to take care of starting and ending transactions.

commit

</>

pub fn commit(
  connection: Connection,
) -> Result(Connection, TransactionError(error))

Commits a transaction.

You should typically use pgl.transaction to take care of starting and ending transactions.

config

</>

pub const config: Config

A default configuration with a connection pool size of 5. At minimum you need to set the username, password, and database values.

The default SSL mode is SslVerified. Use pgl.from_url to configure from a connection URL instead.

connection_parameter

</>

pub fn connection_parameter(
  conf: Config,
  name name: String,
  value value: String,
) -> Config

Sets other postgres connection parameters.

error_to_string

</>

pub fn error_to_string(err: PglError) -> String

Returns a formatted string representation of the provided error.

execute

</>

pub fn execute(
  sql: String,
  on connection: Connection,
) -> Result(Int, PglError)

Perform a query with the given SQL string. This function will send the SQL string as is to the postgres database server.

idle_interval

</>

pub fn idle_interval(conf: Config, idle_interval: Int) -> Config

How often idle connections should ping the database server.

new

</>

pub fn new(config: Config) -> Db

Creates a new Db record. This must be passed to pgl.start or pgl.supervised before it can be used.

port

</>

pub fn port(conf: Config, port: Int) -> Config

The port on which the database server is listening.

query

</>

pub fn query(
  q: Query,
  connection: Connection,
) -> Result(Queried, PglError)

Perform a query with the given SQL string and list of parameters.

queue_target

</>

pub fn queue_target(conf: Config, queue_target: Int) -> Config

How long it should take to check out a connection from the connection pool.

rollback

</>

pub fn rollback(
  connection: Connection,
) -> Result(Connection, TransactionError(error))

Rolls back to a savepoint if one exists, otherwise rolls back the transaction.

You should typically use pgl.transaction to take care of starting and ending transactions.

rows_as_dict

</>

pub fn rows_as_dict(conf: Config, rows_as_dict: Bool) -> Config

Configures rows to be returned as Dict rather than n-tuples. The keys of the Dict are the queried column names.

sql

</>

pub fn sql(sql: String) -> Query

Returns a Query with the provided SQL string.

start

</>

pub fn start(
  db: Db,
) -> Result(
  actor.Started(static_supervisor.Supervisor),
  actor.StartError,
)

Starts the connection pool, type cache, query cache, and socket factory under a supervision tree.

supervised

</>

pub fn supervised(
  db: Db,
) -> supervision.ChildSpecification(static_supervisor.Supervisor)

Returns a child specification for use in an existing supervision tree.

transaction

</>

pub fn transaction(
  connection: Connection,
  next: fn(Connection) -> Result(t, error),
) -> Result(t, TransactionError(error))

Starts a transaction and then calls the provided function, passing it the transaction connection. If the given function throws an exception, the transaction will be rolled back the exception propagated up. If the given function returns an error result, the transaction will also be rolled back and an error result returned.

username

</>

pub fn username(conf: Config, username: String) -> Config

The username to connect to the database as.

values

</>

pub fn values(q: Query, values: List(pg_value.Value)) -> Query

Sets a list of query parameters for the provided Query.