gleam_pgo - v0.14.0

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,
    rows_as_map: Bool,
  )
}

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,
  rows_as_map: Bool,
)

    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

    • rows_as_map

      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

</>

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 4 (IPv4)

  • Ipv6

    Internet Protocol version 6 (IPv6)

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

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

date

</> 
pub fn date(a: #(Int, Int, Int)) -> Value

Coerce a date represented as #(year, month, day) into a Value.

decode_date

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

Checks to see if the value is formatted as #(Int, Int, Int) to represent a date as #(year, month, day), and returns the value if it is.

decode_timestamp

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

Checks to see if the value is formatted as #(#(Int, Int, Int), #(Int, Int, Int)) to represent #(#(year, month, day), #(hour, minute, second)), and returns the value if it is.

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

timestamp

</> 
pub fn timestamp(
  a: #(#(Int, Int, Int), #(Int, Int, Int)),
) -> Value

Coerce a timestamp represented as #(#(year, month, day), #(hour, minute, second)) into a Value.

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.

✨ Search Document