pgl

PostgreSQL database client

Types

Config

pub type Config {
  Config(
    application: String,
    host: String,
    port: Int,
    username: String,
    password: String,
    database: String,
    connection_parameters: List(#(String, String)),
    ssl: Ssl,
    rows_as_dict: Bool,
    ip_version: IpVersion,
    pool_size: Int,
    idle_interval: Int,
    queue_target: Int,
  )
}

Constructors

```
Config(
  application: String,
  host: String,
  port: Int,
  username: String,
  password: String,
  database: String,
  connection_parameters: List(#(String, String)),
  ssl: Ssl,
  rows_as_dict: Bool,
  ip_version: IpVersion,
  pool_size: Int,
  idle_interval: Int,
  queue_target: Int,
)
```
Arguments

application

Application’s name.

host

(default: 127.0.0.1) Database server hostname.

port

(default: 5432) Database server port.

username

Database username.

password

Database user password.

database

Database to use.

connection_parameters

Other Postgres connection parameters.

ssl

(default: SslDisabled) SSL enabled or disabled.

rows_as_dict

(default: False) Return rows as Dict or n-tuple.

ip_version

(default: Ipv4) The IP version to use

pool_size

(default: 1) Connection pool size.

idle_interval

(default: 1000) Idle connections ping the database every idle_interval.

queue_target

(default: 50) How long checking out a connection should take.

Connection

opaque </>

A single database connection

pub opaque type Connection

Db

opaque </>

A configured Db. Must be started via pgl.start or pgl.supervised before use. Once started, Db can be passed to with_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

</>

pub type PglError {
  QueryError(message: String)
  ConnectionError(message: String)
  ConnectionTimeout
  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)
```
```
ConnectionError(message: String)
```
```
ConnectionTimeout
```
```
AuthenticationError(message: String)
```
```
ProtocolError(message: String)
```
```
SocketError(message: String)
```

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

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, params: List(pg_value.Value))
}

Constructors

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

Ssl

</>

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

</>

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

Constructors

```
RollbackError(cause: error)
```
```
NotInTransaction
```
```
TransactionError(message: String)
```

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),
  conn: 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.

connection_parameter

</>

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

Sets other postgres connection parameters.

default

</>

pub const default: Config

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

execute

</>

pub fn execute(
  sql: String,
  on conn: 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.

params

</>

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

Sets a list of query parameters for the provided Query.

port

</>

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

The port on which the database server is listening.

query

</>

pub fn query(
  q: Query,
  conn: 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.

rows_as_dict

</>

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

Configures rows to be returns as Dict rather than n-tuples.

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

supervised

</>

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

transaction

</>

pub fn transaction(
  conn: 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.

with_connection

</>

pub fn with_connection(
  db: Db,
  next: fn(Connection) -> t,
) -> Result(t, PglError)

Checks out a connection passes it to the provided function. After the provided function returns, the connection is checked back in.

Example:

pgl.with_connection(db, fn(conn) {
  pgl.query(sql, [], conn)
})

Constructors

Arguments

Constructors

Constructors

Constructors

Constructors

Constructors

Constructors

Constructors