dream_postgres - v1.0.0

dream_postgres/client

PostgreSQL client wrapper

Provides a clean builder interface to Pog connection management. Follows Dream’s builder pattern for consistency.

Example

import dream_postgres/client as postgres

// Builder pattern
let db = postgres.new()
  |> postgres.host("localhost")
  |> postgres.port(5432)
  |> postgres.database("myapp")
  |> postgres.user("postgres")
  |> postgres.pool_size(15)
  |> postgres.connect()

// Or from URL
let db = postgres.from_url("postgresql://user:pass@localhost:5432/myapp")

Types

Config

</> 
pub type Config =
  pog.Config

Connection

</> 
pub type Connection =
  pog.Connection

QueryError

</> 
pub type QueryError =
  pog.QueryError

Returned

</> 
pub type Returned(a) =
  pog.Returned(a)

Value

</> 
pub type Value =
  pog.Value

Values

connect

</> 
pub fn connect(
  config: pog.Config,
) -> Result(pog.Connection, actor.StartError)

Start the connection pool

Creates and starts the PostgreSQL connection pool with the provided configuration. The pool will be registered with the process name you provided to new().

Parameters

  • config: The complete configuration

Returns

  • Ok(Connection): Successfully started the pool
  • Error(StartError): Failed to start (e.g., connection refused, invalid config)

Example

import dream_postgres/client as postgres
import gleam/erlang/process

let pool_name = process.new_name("db_pool")
let assert Ok(db) = postgres.new(pool_name)
  |> postgres.host("localhost")
  |> postgres.port(5432)
  |> postgres.database("myapp")
  |> postgres.user("postgres")
  |> postgres.password("secret")
  |> postgres.pool_size(15)
  |> postgres.connect()

database

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

Set the database name

Sets the name of the PostgreSQL database to connect to.

Parameters

  • config: The configuration to modify
  • value: The database name

Returns

A new Config with the database name updated.

Example

config
|> postgres.database("myapp_prod")

from_url

</> 
pub fn from_url(url: String) -> pog.Connection

Connect from a PostgreSQL connection URL

Parses a PostgreSQL connection URL and creates a connection pool. This is a convenience function for quick setup, but the builder pattern is recommended for production code as it’s more explicit and type-safe.

Note: This uses a simple URL parser. For production applications with complex connection requirements, use the builder pattern instead.

URL Format

postgresql://user:password@host:port/database

Examples:

  • postgresql://postgres:secret@localhost:5432/myapp
  • postgresql://user@localhost/myapp (no password)
  • postgresql://localhost/myapp (defaults: user=postgres, port=5432)

Parameters

  • url: The PostgreSQL connection URL

Returns

A Connection (panics on parse failure - use builder pattern for error handling).

Example

import dream_postgres/client as postgres

let db = postgres.from_url("postgresql://postgres:secret@localhost:5432/myapp")

host

</> 
pub fn host(config: pog.Config, value: String) -> pog.Config

Set the database host

Sets the hostname or IP address of the PostgreSQL server.

Parameters

  • config: The configuration to modify
  • value: The hostname (e.g., “localhost” or “db.example.com”)

Returns

A new Config with the host updated.

Example

config
|> postgres.host("localhost")

new

</> 
pub fn new(pool_name: process.Name(pog.Message)) -> pog.Config

Create a new default PostgreSQL configuration

Creates a configuration with sensible defaults. You must provide a pool name which is used to identify the connection pool in the process registry.

Parameters

  • pool_name: A process name for the connection pool

Returns

A new Config with default values. Use builder functions to customize it.

Example

import dream_postgres/client as postgres
import gleam/erlang/process

let pool_name = process.new_name("my_db_pool")
let config = postgres.new(pool_name)

password

</> 
pub fn password(config: pog.Config, value: String) -> pog.Config

Set the database password

Sets the password for authenticating to PostgreSQL.

Parameters

  • config: The configuration to modify
  • value: The password

Returns

A new Config with the password updated.

Example

config
|> postgres.password("secret123")

pool_size

</> 
pub fn pool_size(config: pog.Config, value: Int) -> pog.Config

Set the connection pool size

Sets the maximum number of connections in the pool. The pool manages connections automatically, creating and reusing them as needed.

Parameters

  • config: The configuration to modify
  • value: The maximum number of connections (e.g., 15)

Returns

A new Config with the pool size updated.

Example

config
|> postgres.pool_size(20)  // Allow up to 20 concurrent connections

port

</> 
pub fn port(config: pog.Config, value: Int) -> pog.Config

Set the database port

Sets the port number for the PostgreSQL server. Defaults to 5432.

Parameters

  • config: The configuration to modify
  • value: The port number

Returns

A new Config with the port updated.

Example

config
|> postgres.port(5432)

user

</> 
pub fn user(config: pog.Config, value: String) -> pog.Config

Set the database user

Sets the username for authenticating to PostgreSQL.

Parameters

  • config: The configuration to modify
  • value: The username

Returns

A new Config with the user updated.

Example

config
|> postgres.user("postgres")
✨ Search Document