#mattn/postgres

#Features

• Connection management with PostgreSQL servers
• Simple and parameterized query execution
• Prepared statements for efficient repeated execution
• Result parsing (rows, columns, affected rows)
• Error handling with typed error enum
• Environment variable access

#Requirements

• PostgreSQL development libraries (libpq-dev)
• Ubuntu/Debian: sudo apt-get install libpq-dev
• macOS: brew install postgresql
• Fedora/RHEL: sudo dnf install postgresql-devel

#Installation

{
  "import": [
    {
      "path": "mattn/postgres"
    }
  ],
  "link": {
    "native": {
      "cc-link-flags": "-lpq"
    }
  }
}

#Quick Start

fn main {
  let conn = mattn/postgres::connect("postgresql://user:password@localhost/dbname")?

  // Simple query
  let result = conn.query("SELECT * FROM users")?
  let rows = result.rows()
  result.free()

  // Parameterized query with ToValue trait
  let result2 = conn.execute(
    "SELECT * FROM users WHERE id = $1",
    [42]
  )?
  result2.free()

  conn.close()
}

#API

#Connection

#connect(conninfo: String) -> Result[Connection, PgError]

#Connection::query(sql: String) -> Result[QueryResult, PgError]

#Connection::execute[T : ToValue](sql: String, params: Array[T]) -> Result[QueryResult, PgError]

#Connection::prepare(name: String, sql: String) -> Result[PreparedStatement, PgError]

#Connection::close() -> Unit

#QueryResult

#QueryResult::rows() -> Array[Array[String]]

#QueryResult::columns() -> Array[String]

#QueryResult::affected_rows() -> Int

#QueryResult::free() -> Unit

#PreparedStatement

#PreparedStatement::execute[T : ToValue](params: Array[T]) -> Result[QueryResult, PgError]

#PreparedStatement::close() -> Unit

#Value Creation

// Direct values - recommended
conn.execute("SELECT * FROM users WHERE id = $1", [42])?
conn.execute("SELECT * FROM users WHERE name = $1", ["Alice"])?
conn.execute("SELECT * FROM users WHERE active = $1", [true])?

// Mixed types
conn.execute(
  "INSERT INTO users (id, name, active) VALUES ($1, $2, $3)",
  [42, "Alice", true]
)?

• Int → Value::Int
• String → Value::String
• Bool → Value::Bool
• Int64 → Value::Int64
• Float → Value::Float
• Bytes → Value::Bytes
• Value → Value (passthrough)

• Value::Null - for NULL values
• Value::Int64(123L) - explicit Int64
• Value::Float(1.5) - explicit Float
• Value::Bytes(data) - binary data

#Error Handling

pub enum PgError {
  ConnectionError(String)
  AuthError(String)
  QueryError(String)
  ProtocolError(String)
}

error.to_string() -> String

#Utilities

#pg_get_env(name: String) -> String

#Examples

#SELECT

fn main {
  let conn = mattn/postgres::connect("postgresql://localhost/mydb")?
  let result = conn.query("SELECT id, name FROM users")?
  for row in result.rows() {
    println(row[0] + ": " + row[1])
  }
  result.free()
  conn.close()
}

#Parameterized Query

fn main {
  let conn = mattn/postgres::connect("postgresql://localhost/mydb")?
  // Direct value passing with ToValue trait
  let result = conn.execute(
    "SELECT * FROM users WHERE id = $1 AND active = $2",
    [42, true]
  )?
  result.free()
  conn.close()
}

#Prepared Statements

fn main {
  let conn = mattn/postgres::connect("postgresql://localhost/mydb")?
  let stmt = conn.prepare("get_user", "SELECT * FROM users WHERE id = $1")?
  for i = 1; i <= 100; i = i + 1 {
    let result = stmt.execute([i])?
    result.free()
  }
  stmt.close()
  conn.close()
}

#INSERT/UPDATE/DELETE

fn main {
  let conn = mattn/postgres::connect("postgresql://localhost/mydb")?
  let result = conn.execute(
    "UPDATE users SET active = $1 WHERE id = $2",
    [false, 123]
  )?
  println(result.affected_rows().to_string() + " rows updated")
  result.free()
  conn.close()
}

#Environment Variables

fn main {
  let host = mattn/postgres::pg_get_env("DB_HOST")
  let user = mattn/postgres::pg_get_env("DB_USER")
  let password = mattn/postgres::pg_get_env("DB_PASSWORD")
  let conninfo = "postgresql://" + user + ":" + password + "@" + host
  let conn = mattn/postgres::connect(conninfo)?
  conn.close()
}

#License