pog

Postgresql client

Gleam wrapper around pgo library

Types

Config

The configuration for a pool of connections.

pub type Config {
  Config(
    pool_name: process.Name(Message),
    host: String,
    port: Int,
    database: String,
    user: String,
    password: option.Option(String),
    ssl: Ssl,
    connection_parameters: List(#(String, String)),
    pool_size: Int,
    queue_target: Int,
    queue_interval: Int,
    idle_interval: Int,
    trace: Bool,
    ip_version: IpVersion,
    rows_as_map: Bool,
  )
}

Constructors

```
Config(
  pool_name: process.Name(Message),
  host: String,
  port: Int,
  database: String,
  user: String,
  password: option.Option(String),
  ssl: Ssl,
  connection_parameters: List(#(String, String)),
  pool_size: Int,
  queue_target: Int,
  queue_interval: Int,
  idle_interval: Int,
  trace: Bool,
  ip_version: IpVersion,
  rows_as_map: Bool,
)
```
Arguments

pool_name

The Erlang name to register the pool with.

host

(default: 127.0.0.1): Database server hostname.

port

(default: 5432): Port the server is listening on.

database

Name of database to use.

user

Username to connect to database as.

password

Password for the user.

ssl

(default: SslDisabled): Whether to use SSL or not.

connection_parameters

(default: []): List of 2-tuples, where key and value must be binary strings. You can include any Postgres connection parameter here, such as #("application_name", "myappname") and #("timezone", "GMT").

pool_size

(default: 1): Number of connections to keep open with the database

queue_target

(default: 50) Checking out connections is handled through a queue. If it takes longer than queue_target to get out of the queue for longer than queue_interval then the queue_target will be doubled and checkouts will start to be dropped if that target is surpassed.

queue_interval

(default: 1000)

idle_interval

(default: 1000): The database is pinged every idle_interval when the connection is idle.

trace

trace (default: False): pgo is instrumented with OpenCensus and when this option is true a span will be created (if sampled).

ip_version

(default: Ipv4) Which internet protocol to use for this connection

rows_as_map

(default: False) By default, pgo will return a n-tuple, in the order of the query. By setting rows_as_map to True, the result will be Dict.

Connection

opaque </>

pub opaque type Connection

IpVersion

</>

The internet protocol version to use.

pub type IpVersion {
  Ipv4
  Ipv6
}

Constructors

```
Ipv4
```
Internet Protocol version 4 (IPv4)
```
Ipv6
```
Internet Protocol version 6 (IPv6)

Message

</>

pub type Message

Query

opaque </>

pub opaque type Query(row_type)

QueryError

</>

pub type QueryError {
  ConstraintViolated(
    message: String,
    constraint: String,
    detail: String,
  )
  PostgresqlError(code: String, name: String, message: String)
  UnexpectedArgumentCount(expected: Int, got: Int)
  UnexpectedArgumentType(expected: String, got: String)
  UnexpectedResultType(List(decode.DecodeError))
  QueryTimeout
  ConnectionUnavailable
}

Constructors

ConstraintViolated(
  message: String,
  constraint: String,
  detail: String,
)

The query failed as a database constraint would have been violated by the change.

```
PostgresqlError(code: String, name: String, message: String)
```
The query failed within the database. https://www.postgresql.org/docs/current/errcodes-appendix.html

UnexpectedArgumentCount(expected: Int, got: Int)

```
UnexpectedArgumentType(expected: String, got: String)
```
One of the arguments supplied was not of the type that the query required.
```
UnexpectedResultType(List(decode.DecodeError))
```
The rows returned by the database could not be decoded using the supplied dynamic decoder.
```
QueryTimeout
```
The query timed out.
```
ConnectionUnavailable
```
No connection was available to execute the query. This may be due to invalid connection details such as an invalid username or password.

Returned

</>

The rows and number of rows that are returned by a database query.

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

Constructors

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

Ssl

</>

pub type Ssl {
  SslVerified
  SslUnverified
  SslDisabled
}

Constructors

```
SslVerified
```
Enable SSL connection, and check CA certificate. It is the most secured option to use SSL and should be always used by default. Never ignore CA certificate checking unless you know exactly what you are doing.
```
SslUnverified
```
Enable SSL connection, but don’t check CA certificate. SslVerified should always be prioritized upon SslUnverified. As it implies, that option enables SSL, but as it is unverified, the connection can be unsafe. Use this option only if you know what you’re doing. In case pog can not find the proper CA certificate, take a look at the README to get some help to inject the CA certificate in your OS.
```
SslDisabled
```
Disable SSL connection completely. Using this option will let the connection unsecured, and should be avoided in production environment.

TransactionError

</>

pub type TransactionError(error) {
  TransactionQueryError(QueryError)
  TransactionRolledBack(error)
}

Constructors

```
TransactionQueryError(QueryError)
```
```
TransactionRolledBack(error)
```

Value

</>

A value that can be sent to PostgreSQL as one of the arguments to a parameterised SQL query.

pub type Value

Values

array

</>

pub fn array(converter: fn(a) -> Value, values: List(a)) -> Value

bool

</>

pub fn bool(a: Bool) -> Value

bytea

</>

pub fn bytea(a: BitArray) -> Value

calendar_date

</>

pub fn calendar_date(date: calendar.Date) -> Value

calendar_date_decoder

</>

pub fn calendar_date_decoder() -> decode.Decoder(calendar.Date)

calendar_time_of_day

</>

pub fn calendar_time_of_day(time: calendar.TimeOfDay) -> Value

calendar_time_of_day_decoder

</>

pub fn calendar_time_of_day_decoder(
  ,
) -> decode.Decoder(calendar.TimeOfDay)

connection_parameter

</>

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

Any Postgres connection parameter here, such as "application_name: myappname" and "timezone: GMT"

default_config

</>

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

The default configuration for a connection pool, with a single connection. You will likely want to increase the size of the pool for your application.

error_code_name

</>

pub fn error_code_name(error_code: String) -> Result(String, Nil)

Get the name for a PostgreSQL error code.

> error_code_name("01007")
Ok("privilege_not_granted")

https://www.postgresql.org/docs/current/errcodes-appendix.html

execute

</>

pub fn execute(
  query query: Query(t),
  on pool: Connection,
) -> Result(Returned(t), QueryError)

Run a query against a PostgreSQL database.

float

</>

pub fn float(a: Float) -> Value

host

</>

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

Database server hostname.

(default: 127.0.0.1)

idle_interval

</>

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

The database is pinged every idle_interval when the connection is idle.

default: 1000

int

</>

pub fn int(a: Int) -> Value

ip_version

</>

pub fn ip_version(
  config: Config,
  ip_version: IpVersion,
) -> Config

Which internet protocol to use for this connection

named_connection

</>

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

Create a reference to a pool using the pool’s name.

If no pool has been started using this name then queries using this connection will fail.

null

</>

pub fn null() -> Value

nullable

</>

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

numeric_decoder

</>

pub fn numeric_decoder() -> decode.Decoder(Float)

Decode a PostgreSQL numeric, which is a union of PostgreSQL integers and float types. Int values are decoded as floats.

parameter

</>

pub fn parameter(query: Query(t1), parameter: Value) -> Query(t1)

Push a new query parameter value for the query.

pool_size

</>

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

Number of connections to keep open with the database

default: 10

port

</>

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

Port the server is listening on.

(default: 5432)

query

</>

pub fn query(sql: String) -> Query(Nil)

Create a new query to use with the execute, returning, and parameter functions.

queue_interval

</>

pub fn queue_interval(
  config: Config,
  queue_interval: Int,
) -> Config

Checking out connections is handled through a queue. If it takes longer than queue_target to get out of the queue for longer than queue_interval then the queue_target will be doubled and checkouts will start to be dropped if that target is surpassed.

default: 1000

queue_target

</>

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

default: 50

returning

</>

pub fn returning(
  query: Query(t1),
  decoder: decode.Decoder(t2),
) -> Query(t2)

Set the decoder to use for the type of row returned by executing this query.

If the decoder is unable to decode the row value then the query will return an error from the exec function, but the query will still have been run against the database.

rows_as_map

</>

pub fn rows_as_map(config: Config, rows_as_map: Bool) -> Config

By default, pgo will return a n-tuple, in the order of the query. By setting rows_as_map to True, the result will be Dict.

ssl

</>

pub fn ssl(config: Config, ssl: Ssl) -> Config

Whether to use SSL or not.

(default: False)

start

</>

pub fn start(
  config: Config,
) -> Result(actor.Started(Connection), actor.StartError)

Start a database connection pool. Most the time you want to use supervised and add the pool to your supervision tree instead of using this function directly.

The pool is started in a new process and will asynchronously connect to the PostgreSQL instance specified in the config. If the configuration is invalid or it cannot connect for another reason it will continue to attempt to connect, and any queries made using the connection pool will fail.

supervised

</>

pub fn supervised(
  config: Config,
) -> supervision.ChildSpecification(Connection)

Start a database connection pool by adding it to your supervision tree.

Use the named_connection function to create a connection to query this pool with if your supervisor does not pass back the return value of creating the pool.

text

</>

pub fn text(a: String) -> Value

timeout

</>

pub fn timeout(query: Query(t1), timeout: Int) -> Query(t1)

Use a custom timeout for the query, in milliseconds. the default connection timeout.

If this function is not used to give a timeout then default of 5000 ms is used.

timestamp

</>

pub fn timestamp(timestamp: timestamp.Timestamp) -> Value

timestamp_decoder

</>

pub fn timestamp_decoder() -> decode.Decoder(timestamp.Timestamp)

trace

</>

pub fn trace(config: Config, trace: Bool) -> Config

Trace pgo is instrumented with OpenTelemetry and when this option is true a span will be created (if sampled).

default: False

transaction

</>

pub fn transaction(
  pool: Connection,
  callback: fn(Connection) -> Result(t, error),
) -> Result(t, TransactionError(error))

Runs a function within a PostgreSQL transaction.

If the function returns an Ok then the transaction is committed.

If the function returns an Error or panics then the transaction is rolled back.

url_config

</>

pub fn url_config(
  name: process.Name(Message),
  database_url: String,
) -> Result(Config, Nil)

Parse a database url into configuration that can be used to start a pool.

user

</>

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

Username to connect to database as.

Constructors

Arguments

Constructors

Constructors

Constructors

Constructors

Constructors