node-pg

A type-safe PostgreSQL client library for Gleam, wrapping the battle-tested node-postgres library.

🚀 Quick Start

import node_pg
import gleam/javascript/promise
import gleam/option.{Some}

pub fn main() {
  // Create a configuration
  let config = node_pg.create_config(
    user: Some("postgres"),
    password: Some("secret"),
    host: Some("localhost"),
    port: Some(5432),
    database: Some("mydb")
  )

  // Create a client
  let client = node_pg.new_client(config)

  // Connect and query
  promise.await(node_pg.connect(client), fn(result) {
    case result {
      Ok(_) -> {
        promise.await(node_pg.query(client, "SELECT * FROM users", []), fn(query_result) {
          case query_result {
            Ok(result) -> {
              // Process result.rows
              promise.await(node_pg.end(client), fn(_) {
                promise.resolve(Nil)
              })
            }
            Error(error) -> {
              // Handle error
              promise.reject(error.message)
            }
          }
        })
      }
      Error(error) -> {
        promise.reject(error.message)
      }
    }
  })
}

⬇️ Install

Since node-pg depends on node-postgres, please install it in advance.

Node.js

npm install pg

Bun

bun add pg

Deno

deno add npm:pg

Add node_pg to your Gleam project:

gleam add node_pg

⛏️ Development

Setup

This project uses Nix with devenv for development environment management:

# Enter the development shell
nix develop

# Or with direnv (recommended)
direnv allow

The Nix flake provides:

• Gleam (latest version)
• Erlang runtime
• Bun runtime
• Pre-commit hooks (treefmt, gitleaks, gitlint)

Building

gleam build        # Build the project
gleam run          # Run the project
gleam test         # Run all tests (mock-based, no database required)

Testing

All tests are mock-based and run without requiring a PostgreSQL database:

gleam test

📝 Todo

• Add transaction support (BEGIN, COMMIT, ROLLBACK)
• Implement connection pooling wrapper
• Add prepared statement support
• Create higher-level query builder API
• Add TypeScript type definitions for FFI
• Improve error type granularity

📜 License

MIT License

🧩 Dependencies

Runtime Dependencies

• gleam_stdlib - Gleam standard library
• gleam_javascript - JavaScript runtime support
• pg (npm) - Node.js PostgreSQL client (^8.16.3)

Development Dependencies

• gleeunit - Testing framework

👏 Inspired By

• pgo - PostgreSQL client for Gleam targeting Erlang

💕 Special Thanks

• node-postgres - The battle-tested PostgreSQL client for Node.js
• gleam-lang - The Gleam programming language