pog - v2.0.0

pog

Postgresql client

Gleam wrapper around pgo library

Types

Config

</>

The configuration for a pool of connections.

pub type Config {
  Config(
    host: String,
    port: Int,
    database: String,
    user: String,
    password: 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,
    default_timeout: Int,
  )
}

Constructors 

  • Config(
  host: String,
  port: Int,
  database: String,
  user: String,
  password: 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,
  default_timeout: Int,
)

    Arguments

    • 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.

    • default_timeout

      (default: 5000): Default time in milliseconds to wait before the query is considered timeout. Timeout can be edited per query.

Connection

</>

A pool of one or more database connections against which queries can be made.

Created using the connect function and shut-down with the disconnect function.

pub type Connection

Date

</> 
pub type Date {
  Date(year: Int, month: Int, day: Int)
}

Constructors 

  • Date(year: Int, month: Int, day: Int)

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)

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(DecodeErrors)
  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(DecodeErrors)

    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.

Time

</> 
pub type Time {
  Time(hours: Int, minutes: Int, seconds: Int, microseconds: Int)
}

Constructors 

  • Time(hours: Int, minutes: Int, seconds: Int, microseconds: Int)

Timestamp

</> 
pub type Timestamp {
  Timestamp(date: Date, time: Time)
}

Constructors 

  • Timestamp(date: Date, time: Time)

TransactionError

</> 
pub type TransactionError {
  TransactionQueryError(QueryError)
  TransactionRolledBack(String)
}

Constructors 

  • TransactionQueryError(QueryError)
  • TransactionRolledBack(String)

Value

</>

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

pub type Value

Functions

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

connect

</> 
pub fn connect(a: Config) -> Connection

Start a database connection pool.

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.

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"

database

</> 
pub fn database(config: Config, database: String) -> Config

Name of database to use.

date

</> 
pub fn date(date: Date) -> Value

decode_date

</> 
pub fn decode_date(
  value: Dynamic,
) -> Result(Date, List(DecodeError))

decode_time

</> 
pub fn decode_time(
  value: Dynamic,
) -> Result(Time, List(DecodeError))

decode_timestamp

</> 
pub fn decode_timestamp(
  value: Dynamic,
) -> Result(Timestamp, List(DecodeError))

default_config

</> 
pub fn default_config() -> 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.

default_timeout

</> 
pub fn default_timeout(
  config: Config,
  default_timeout: Int,
) -> Config

By default, pog have a default value of 5000ms as timeout. By setting default_timeout, every queries will now use that timeout. The timeout is given in milliseconds.

disconnect

</> 
pub fn disconnect(a: Connection) -> Nil

Shut down a connection pool.

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(a),
  on pool: Connection,
) -> Result(Returned(a), QueryError)

Run a query against a PostgreSQL database.

The provided dynamic decoder is used to decode the rows returned by PostgreSQL. If you are not interested in any returned rows you may want to use the dynamic.dynamic decoder.

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

null

</> 
pub fn null() -> Value

nullable

</> 
pub fn nullable(
  inner_type: fn(a) -> Value,
  value: Option(a),
) -> Value

parameter

</> 
pub fn parameter(query: Query(a), parameter: Value) -> Query(a)

Push a new query parameter value for the query.

password

</> 
pub fn password(
  config: Config,
  password: Option(String),
) -> Config

Password for the user.

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

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: 50

returning

</> 
pub fn returning(
  query: Query(a),
  decoder: fn(Dynamic) -> Result(b, List(DecodeError)),
) -> Query(b)

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)

text

</> 
pub fn text(a: String) -> Value

time

</> 
pub fn time(time: Time) -> Value

timeout

</> 
pub fn timeout(query: Query(a), timeout: Int) -> Query(a)

Use a custom timeout for the query. This timeout will take precedence over the default connection timeout. The timeout is given in milliseconds.

timestamp

</> 
pub fn timestamp(timestamp: Timestamp) -> Value

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(a, String),
) -> Result(a, TransactionError)

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(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.

✨ Search Document