### Start a PostgreSQL connection pool Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Starts a database connection pool in a new process. It asynchronously connects to the PostgreSQL instance. If the configuration is invalid or connection fails, it will retry, but queries will fail. ```gleam pub fn connect(a: Config) -> Connection ``` -------------------------------- ### connect Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Starts 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. ```APIDOC ## connect ### Description Starts 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. ### Signature ```gleam pub fn connect(a: Config) -> Connection ``` ``` -------------------------------- ### Parse database URL into configuration Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Parses a database URL string into a `Config` object suitable for starting a connection pool. Returns `Ok(Config)` on success or `Err(Nil)` if parsing fails. ```gleam pub fn url_config(database_url: String) -> Result(Config, Nil) ``` -------------------------------- ### url_config Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Parses a database URL into configuration suitable for starting a connection pool. ```APIDOC ## url_config ### Description Parse a database url into configuration that can be used to start a pool. ### Signature ```gleam pub fn url_config(database_url: String) -> Result(Config, Nil) ``` ``` -------------------------------- ### Get PostgreSQL error code name Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Retrieves the descriptive name for a given PostgreSQL error code string. Returns `Ok(String)` on success or `Err(Nil)` if the code is not found. ```gleam pub fn error_code_name(error_code: String) -> Result(String, Nil) ``` ```gleam > error_code_name("01007") Ok("privilege_not_granted") ``` -------------------------------- ### Connect and Query PostgreSQL Database Source: https://hexdocs.pm/gleam_pgo/index.html Demonstrates how to establish a database connection pool, define an SQL query with parameters, specify the return type decoder, execute the query, and assert the results. Ensure you have a PostgreSQL server running and a database named 'my_database' with a 'cats' table. ```gleam import gleam/pgo import gleam/dynamic import gleeunit/should pub fn main() { // Start a database connection pool. // Typically you will want to create one pool for use in your program let db = pgo.connect(pgo.Config( ..pgo.default_config(), host: "localhost", database: "my_database", pool_size: 15, )) // An SQL statement to run. It takes one int as a parameter let sql = " select name, age, colour, friends from cats where id = $1" // This is the decoder for the value returned by the query let return_type = dynamic.tuple4( dynamic.string, dynamic.int, dynamic.string, dynamic.list(dynamic.string), ) // Run the query against the PostgreSQL database // The int `1` is given as a parameter let assert Ok(response) = pgo.execute(sql, db, [pgo.int(1)], return_type) // And then do something with the returned results response.count |> should.equal(2) response.rows |> should.equal([ #("Nubi", 3, "black", ["Al", "Cutlass"]), ]) } ``` -------------------------------- ### IpVersion Constructors Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Constructors for specifying the internet protocol version. Use `Ipv4` for IPv4 and `Ipv6` for IPv6. ```gleam Ipv4 ``` ```gleam Ipv6 ``` -------------------------------- ### Config Constructor Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Constructs a new Config for PostgreSQL connections. Defaults are provided for host, port, SSL, connection parameters, pool size, queue settings, idle interval, tracing, and row format. ```gleam 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, ) ``` -------------------------------- ### Config Constructor Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Constructs a new Config for a pool of database connections. Allows customization of host, port, credentials, connection parameters, pool size, and various performance-related settings. ```APIDOC ## Config Constructor ### Description Constructs a new `Config` for a pool of database connections. Allows customization of host, port, credentials, connection parameters, pool size, and various performance-related settings. ### Arguments * _host_ (String) - Database server hostname. (default: 127.0.0.1) * _port_ (Int) - Port the server is listening on. (default: 5432) * _database_ (String) - Name of database to use. * _user_ (String) - Username to connect to database as. * _password_ (Option(String)) - Password for the user. * _ssl_ (Bool) - Whether to use SSL or not. (default: false) * _connection_parameters_ (List(#(String, String))) - 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")`. (default: []) * _pool_size_ (Int) - Number of connections to keep open with the database (default: 1) * _queue_target_ (Int) - 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) * _queue_interval_ (Int) - (default: 1000) * _idle_interval_ (Int) - The database is pinged every idle_interval when the connection is idle. (default: 1000) * _trace_ (Bool) - pgo is instrumented with OpenCensus and when this option is true a span will be created (if sampled). (default: false) * _ip_version_ (IpVersion) - Which internet protocol to use for this connection * _rows_as_map_ (Bool) - 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`. ``` -------------------------------- ### IpVersion Constructors Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Represents the internet protocol version to use for a connection. Supports both IPv4 and IPv6. ```APIDOC ## IpVersion Constructors ### Description Represents the internet protocol version to use for a connection. Supports both IPv4 and IPv6. ### Constructors * ``` Ipv4 ``` Internet Protocol version 4 (IPv4) * ``` Ipv6 ``` Internet Protocol version 6 (IPv6) ``` -------------------------------- ### Execute a PostgreSQL query Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Runs a SQL query against a PostgreSQL database using the provided connection pool and arguments. It uses a dynamic decoder to process returned rows. Use `dynamic.dynamic` if no rows are needed. ```gleam 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) ``` -------------------------------- ### execute Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Executes a query against a PostgreSQL database using the provided connection pool and arguments. It uses a dynamic decoder to process the returned rows. ```APIDOC ## execute ### Description 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. ### Signature ```gleam 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) ``` ``` -------------------------------- ### Connection Type Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Represents a pool of one or more database connections. Use the `connect` function to create and `disconnect` to shut down. ```gleam pub type Connection ``` -------------------------------- ### Config Type Definition Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Defines the configuration structure for a pool of PostgreSQL connections. Customize connection details, pooling behavior, and tracing options. ```gleam 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, ) } ``` -------------------------------- ### Returned Constructor Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Represents the result of a database query, containing the count of affected rows and a list of returned rows. ```APIDOC ## Returned Constructor ### Description Represents the result of a database query, containing the count of affected rows and a list of returned rows. ### Constructor * ``` Returned(count: Int, rows: List(t)) ``` ``` -------------------------------- ### Add gleam_pgo Dependency Source: https://hexdocs.pm/gleam_pgo/index.html Use this command to add the gleam_pgo library to your Gleam project dependencies. ```bash gleam add gleam_pgo ``` -------------------------------- ### Default PostgreSQL connection pool configuration Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Provides the default configuration for a connection pool with a single connection. It is recommended to increase the pool size for applications. ```gleam pub fn default_config() -> Config ``` -------------------------------- ### Returned Constructor Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Constructor for the `Returned` type, used to package query results. It takes the count of affected rows and a list of the returned rows. ```gleam Returned(count: Int, rows: List(t)) ``` -------------------------------- ### default_config Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Provides the default configuration for a connection pool with a single connection. It is recommended to increase the pool size for applications. ```APIDOC ## default_config ### Description 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. ### Signature ```gleam pub fn default_config() -> Config ``` ``` -------------------------------- ### IpVersion Type Definition Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Defines the internet protocol version for connections. Supports both IPv4 and IPv6. ```gleam pub type IpVersion { Ipv4 Ipv6 } ``` -------------------------------- ### int Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Encodes an integer into a `Value`. ```APIDOC ## int ### Description Encodes an integer into a `Value`. ### Signature ```gleam pub fn int(a: Int) -> Value ``` ``` -------------------------------- ### QueryError Constructors Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Constructors for various `QueryError` types. Use `ConstraintViolated` for constraint failures, `PostgresqlError` for database-level errors, and others for argument or connection problems. ```gleam ConstraintViolated( message: String, constraint: String, detail: String, ) ``` ```gleam PostgresqlError(code: String, name: String, message: String) ``` ```gleam UnexpectedArgumentCount(expected: Int, got: Int) ``` ```gleam UnexpectedArgumentType(expected: String, got: String) ``` ```gleam UnexpectedResultType(DecodeErrors) ``` ```gleam ConnectionUnavailable ``` -------------------------------- ### text Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Encodes a string into a `Value`. ```APIDOC ## text ### Description Encodes a string into a `Value`. ### Signature ```gleam pub fn text(a: String) -> Value ``` ``` -------------------------------- ### bytea Function Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Converts a Gleam bit array into a PostgreSQL bytea value for parameterized queries. ```APIDOC ## bytea Function ### Description Converts a Gleam bit array into a PostgreSQL bytea value for parameterized queries. ### Signature ``` pub fn bytea(a: BitArray) -> Value ``` ``` -------------------------------- ### Create nullable PostgreSQL Value Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Constructs a PostgreSQL `Value` that can be NULL. It takes a function to convert the inner type to a `Value` and an `Option` containing the value. ```gleam pub fn nullable( inner_type: fn(a) -> Value, value: Option(a), ) -> Value ``` -------------------------------- ### bytea Function Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Converts a Gleam bit array into a PostgreSQL bytea value for use in parameterized queries. ```gleam pub fn bytea(a: BitArray) -> Value ``` -------------------------------- ### Represent PostgreSQL NULL value Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Returns a PostgreSQL `Value` representing SQL NULL. ```gleam pub fn null() -> Value ``` -------------------------------- ### QueryError Constructors Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Represents errors that can occur during a database query. Includes constraint violations, PostgreSQL errors, argument mismatches, and connection issues. ```APIDOC ## QueryError Constructors ### Description Represents errors that can occur during a database query. Includes constraint violations, PostgreSQL errors, argument mismatches, and connection issues. ### 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. ``` -------------------------------- ### float Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Encodes a float into a `Value`. ```APIDOC ## float ### Description Encodes a float into a `Value`. ### Signature ```gleam pub fn float(a: Float) -> Value ``` ``` -------------------------------- ### Coerce timestamp to PostgreSQL Value Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Converts a timestamp represented as `#(#(year, month, day), #(hour, minute, second))` into a PostgreSQL `Value`. ```gleam pub fn timestamp( a: #(#(Int, Int, Int), #(Int, Int, Int)), ) -> Value ``` -------------------------------- ### Shut down a PostgreSQL connection pool Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Gracefully shuts down a connection pool. ```gleam pub fn disconnect(a: Connection) -> Nil ``` -------------------------------- ### array Function Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Converts a Gleam list into a PostgreSQL array value for use in parameterized queries. ```gleam pub fn array(a: List(a)) -> Value ``` -------------------------------- ### Coerce date to PostgreSQL Value Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Converts a date represented as a tuple `#(year, month, day)` into a PostgreSQL `Value`. ```gleam pub fn date(a: #(Int, Int, Int)) -> Value ``` -------------------------------- ### Decode timestamp from Dynamic Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Checks if a `Dynamic` value is formatted as `#(#(Int, Int, Int), #(Int, Int, Int))` representing a timestamp `#(#(year, month, day), #(hour, minute, second))` and returns it if valid. Returns a `List(DecodeError)` on failure. ```gleam pub fn decode_timestamp( value: Dynamic, ) -> Result( #(#(Int, Int, Int), #(Int, Int, Int)), List(DecodeError), ) ``` -------------------------------- ### array Function Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Converts a Gleam list into a PostgreSQL array value for parameterized queries. ```APIDOC ## array Function ### Description Converts a Gleam list into a PostgreSQL array value for parameterized queries. ### Signature ``` pub fn array(a: List(a)) -> Value ``` ``` -------------------------------- ### Run function within a PostgreSQL transaction Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Executes a callback function within a PostgreSQL transaction. The transaction is committed if the callback returns `Ok`, and rolled back if it returns `Error` or panics. ```gleam pub fn transaction( pool: Connection, callback: fn(Connection) -> Result(a, String), ) -> Result(a, TransactionError) ``` -------------------------------- ### Coerce text to PostgreSQL Value Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Converts a Gleam `String` into a PostgreSQL `Value`. ```gleam pub fn text(a: String) -> Value ``` -------------------------------- ### Decode date from Dynamic Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Checks if a `Dynamic` value is formatted as `#(Int, Int, Int)` representing a date `#(year, month, day)` and returns it if valid. Returns a `List(DecodeError)` on failure. ```gleam pub fn decode_date( value: Dynamic, ) -> Result(#(Int, Int, Int), List(DecodeError)) ``` -------------------------------- ### TransactionError Constructors Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Constructors for `TransactionError`. Use `TransactionQueryError` to wrap a `QueryError` or `TransactionRolledBack` to indicate a transaction was rolled back. ```gleam TransactionQueryError(QueryError) ``` ```gleam TransactionRolledBack(String) ``` -------------------------------- ### Coerce float to PostgreSQL Value Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Converts a Gleam `Float` into a PostgreSQL `Value`. ```gleam pub fn float(a: Float) -> Value ``` -------------------------------- ### Value Type Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Represents a value that can be sent to PostgreSQL as an argument for parameterized SQL queries. ```gleam pub type Value ``` -------------------------------- ### Coerce integer to PostgreSQL Value Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Converts a Gleam `Int` into a PostgreSQL `Value`. ```gleam pub fn int(a: Int) -> Value ``` -------------------------------- ### null Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Represents a null value. ```APIDOC ## null ### Description Represents a null value. ### Signature ```gleam pub fn null() -> Value ``` ``` -------------------------------- ### date Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Coerces a date represented as a tuple of (year, month, day) into a `Value`. ```APIDOC ## date ### Description Coerce a date represented as `#(year, month, day)` into a `Value`. ### Signature ```gleam pub fn date(a: #(Int, Int, Int)) -> Value ``` ``` -------------------------------- ### bool Function Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Converts a Gleam boolean into a PostgreSQL boolean value for use in parameterized queries. ```gleam pub fn bool(a: Bool) -> Value ``` -------------------------------- ### bool Function Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Converts a Gleam boolean into a PostgreSQL boolean value for parameterized queries. ```APIDOC ## bool Function ### Description Converts a Gleam boolean into a PostgreSQL boolean value for parameterized queries. ### Signature ``` pub fn bool(a: Bool) -> Value ``` ``` -------------------------------- ### timestamp Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Coerces a timestamp represented as a nested tuple of (year, month, day) and (hour, minute, second) into a `Value`. ```APIDOC ## timestamp ### Description Coerce a timestamp represented as `#(#(year, month, day), #(hour, minute, second))` into a `Value`. ### Signature ```gleam pub fn timestamp( a: #(#(Int, Int, Int), #(Int, Int, Int)), ) -> Value ``` ``` -------------------------------- ### TransactionError Constructors Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Represents errors that can occur during a database transaction, including query errors and rollbacks. ```APIDOC ## TransactionError Constructors ### Description Represents errors that can occur during a database transaction, including query errors and rollbacks. ### Constructors * ``` TransactionQueryError(QueryError) ``` * ``` TransactionRolledBack(String) ``` ``` -------------------------------- ### Returned Type Definition Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Represents the result of a database query, containing the number of affected rows and a list of returned rows. ```gleam pub type Returned(t) { Returned(count: Int, rows: List(t)) } ``` -------------------------------- ### transaction Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Runs a function within a PostgreSQL transaction. The transaction is committed if the function returns `Ok`, and rolled back if it returns an `Error` or panics. ```APIDOC ## transaction ### Description 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. ### Signature ```gleam pub fn transaction( pool: Connection, callback: fn(Connection) -> Result(a, String), ) -> Result(a, TransactionError) ``` ``` -------------------------------- ### disconnect Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Shuts down a connection pool. ```APIDOC ## disconnect ### Description Shut down a connection pool. ### Signature ```gleam pub fn disconnect(a: Connection) -> Nil ``` ``` -------------------------------- ### error_code_name Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Retrieves the name for a given PostgreSQL error code. ```APIDOC ## error_code_name ### Description Get the name for a PostgreSQL error code. ### Example ```gleam > error_code_name("01007") Ok("privilege_not_granted") ``` ### Signature ```gleam pub fn error_code_name(error_code: String) -> Result(String, Nil) ``` ### Reference https://www.postgresql.org/docs/current/errcodes-appendix.html ``` -------------------------------- ### nullable Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Encodes an optional value into a `Value`, using an inner type encoder for non-null values. ```APIDOC ## nullable ### Description Encodes an optional value into a `Value`, using an inner type encoder for non-null values. ### Signature ```gleam pub fn nullable( inner_type: fn(a) -> Value, value: Option(a), ) -> Value ``` ``` -------------------------------- ### QueryError Type Definition Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Defines possible errors that can occur during a database query. Includes constraint violations, PostgreSQL errors, argument mismatches, and connection issues. ```gleam 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 } ``` -------------------------------- ### decode_date Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Checks if a value is formatted as a tuple of (Int, Int, Int) representing a date (year, month, day) and returns the value if it is. ```APIDOC ## decode_date ### Description 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. ### Signature ```gleam pub fn decode_date( value: Dynamic, ) -> Result(#(Int, Int, Int), List(DecodeError)) ``` ``` -------------------------------- ### TransactionError Type Definition Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Defines possible errors that can occur within a database transaction. Includes query errors and rollback events. ```gleam pub type TransactionError { TransactionQueryError(QueryError) TransactionRolledBack(String) } ``` -------------------------------- ### decode_timestamp Source: https://hexdocs.pm/gleam_pgo/gleam/pgo.html Checks if a value is formatted as a nested tuple representing a timestamp (year, month, day) and (hour, minute, second) and returns the value if it is. ```APIDOC ## decode_timestamp ### Description 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. ### Signature ```gleam pub fn decode_timestamp( value: Dynamic, ) -> Result( #(#(Int, Int, Int), #(Int, Int, Int)), List(DecodeError), ) ``` ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.