postgres

PostgreSQL bindings for Kit using libpq

Files

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-postgres.git

Usage

import Kit.Postgres

License

MIT License - see LICENSE for details.

Exported Functions & Types

connection-ok

Connection established successfully

connection-bad

Connection failed or was terminated

pgres-empty-query

Query returned no results (empty query string)

pgres-command-ok

Command completed successfully without returning rows (INSERT, UPDATE, DELETE, etc.)

pgres-tuples-ok

Query completed successfully and returned rows

pgres-copy-out

Server is ready to send COPY data to client

pgres-copy-in

Server is ready to receive COPY data from client

pgres-bad-response

Server sent a response the client could not understand

pgres-nonfatal-error

Non-fatal error occurred (notice or warning)

pgres-fatal-error

Fatal error occurred during query execution

PostgresError

PostgreSQL error type for typed error handling. Variants distinguish between different failure modes.

DbValue

Database value type representing PostgreSQL column values. Row records contain Option DbValue for each column: - None: SQL NULL - Some (DbString s): Scalar string value - Some (DbArray items): Array of strings

match Map.get "tags" row
  | Some (DbArray tags) -> List.each println tags
  | Some (DbString s) -> println s
  | None -> println "NULL"

is-connected?

Check if a database connection is currently valid and active.

Parameters:

Returns:

{connected: Bool} -> Bool

if Postgres.is-connected? db then
  # Perform queries

close

Close a database connection and release associated resources.

Parameters:

Returns:

Note: Always close connections when done to free resources.

{handle: Ptr} -> Unit

db = Postgres.connect "postgresql://localhost/mydb"
# ... use db ...
Postgres.close db

query

Execute a query and return all rows as a list of records.

Parameters:

Returns:

Row format: - Each row is a Record (map) with column names as keys - Values are Option DbValue: - None: SQL NULL - Some (DbString s): Scalar value as string - Some (DbArray items): PostgreSQL array as List String

Array columns are automatically parsed from PostgreSQL text format.

Ptr -> String -> Result [Map String (Option DbValue)] PostgresError

match Map.get "name" row
  | Some (DbString name) -> println "Name: ${name}"
  | _ -> println "No name"

match Map.get "tags" row
  | Some (DbArray tags) -> List.each println tags
  | _ -> println "No tags"

match query handle "SELECT id, name FROM users"
  | Ok rows ->
      List.each (fn(row) =>
        match Map.get "name" row
          | Some (Some name) -> print name
          | Some None -> print "NULL"
          | None -> print "Column not found"
      ) rows
  | Err e -> print "Error: ${PostgresError.show e}"

execute

Execute a SQL statement (INSERT, UPDATE, DELETE, CREATE, etc.).

Parameters:

Returns:

Note: Use for statements that don't return rows (INSERT, UPDATE, DELETE, CREATE, DROP, etc.)

Ptr -> String -> Result Int PostgresError

match execute handle "INSERT INTO users (name) VALUES ('Alice')"
  | Ok _ -> print "Statement executed"
  | Err e -> print "Error: ${PostgresError.show e}"

escape

Escape a string value for safe inclusion in SQL queries.

Parameters:

Returns:

Note: Uses libpq's PQescapeLiteral for proper escaping with correct memory management. The returned string includes surrounding quotes, so use it directly: "WHERE name = ${escaped}" NOT "WHERE name = '${escaped}'"

Ptr -> String -> String

escaped = escape handle "O'Brien"
# => "'O''Brien'"
query-str = "SELECT * FROM users WHERE name = ${escaped}"

query-params

Execute a query with parameterized values for SQL injection protection.

Parameters:

Returns:

Note: Uses native PQexecParams for proper parameterized queries. Parameters are 1-indexed ($1 is first parameter).

Ptr -> String -> [String] -> Result [Map String (Option DbValue)] PostgresError

match query-params handle "SELECT * FROM users WHERE name = $1 AND status = $2" ["Alice", "active"]
  | Ok rows -> process rows
  | Err e -> print "Error: ${PostgresError.show e}"

execute-params

Execute a statement with parameterized values for SQL injection protection.

Parameters:

Returns:

Ptr -> String -> [String] -> Result Int PostgresError

match execute-params handle "INSERT INTO users (name, email) VALUES ($1, $2)" ["Alice", "alice@example.com"]
  | Ok _ -> print "Inserted"
  | Err e -> print "Error: ${PostgresError.show e}"

parse-array

Parse a PostgreSQL text-format array string into a list of strings.

Handles the PostgreSQL array text representation format: - Empty arrays: {} -> [] - Simple values: {a,b,c} -> ["a", "b", "c"] - Quoted values: {"hello world","with,comma"} -> ["hello world", "with,comma"] - Escaped quotes: {"say \"hello\""} -> ["say \"hello\""] - Escaped backslashes: {"back\\slash"} -> ["back\slash"] - NULL values: {a,NULL,b} -> ["a", None, "b"] (represented as empty string)

Note: This handles 1-dimensional arrays. Nested arrays are returned as raw strings.

String -> [String]