gleam/pgo

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: Bool,
    connection_parameters: List(#(String, String)),
    pool_size: Int,
    queue_target: Int,
    queue_interval: Int,
    idle_interval: Int,
    trace: Bool,
    ip_version: IpVersion,
  )
}

Constructors

```
Config(
  host: String,
  port: Int,
  database: String,
  user: String,
  password: Option(String),
  ssl: Bool,
  connection_parameters: List(#(String, String)),
  pool_size: Int,
  queue_target: Int,
  queue_interval: Int,
  idle_interval: Int,
  trace: Bool,
  ip_version: IpVersion,
)
```
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: false): 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
  
  Which internet protocol to use for this connection

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

IpVersion

</>

The internet protocol version to use.

pub type IpVersion {
  Ipv4
  Ipv6
}

Constructors

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

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)
  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.
```
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))
```

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(a: List(a)) -> Value

bool

</>

pub fn bool(a: Bool) -> Value

bytea

</>

pub fn bytea(a: BitArray) -> Value

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.

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.

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 sql: String,
  on pool: Connection,
  with arguments: List(Value),
  expecting decoder: fn(Dynamic) -> Result(a, List(DecodeError)),
) -> 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

int

</>

pub fn int(a: Int) -> Value

null

</>

pub fn null() -> Value

nullable

</>

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

text

</>

pub fn text(a: String) -> Value

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.

Constructors

Arguments

Constructors

Constructors

Constructors