pg.zig

A Mapper is an optimized way to convert rows into a custom Zig struct T. It is significantly more efficient than using row.to with name-based mapping because it performs the name-to-index lookup only once.

Requirements:

• The query must be executed with {.column_names = true} or the column_names build option must be set.

Mapping Rules:

• Columns with no matching field in the struct are ignored.
• Fields with no matching column are set to their default value. If no default is defined, mapper.next() returns error.FieldColumnMismatch.

Configuration Options (ToOpts):

• dupe: If true, string columns are duplicated using an internal arena. This allows non-scalar values to persist until the row/result is deinitialized.
• allocator: An explicit allocator for duplicating non-scalar values. Setting this implies dupe = true.
• map: Determines mapping strategy. .ordinal (default) matches by position; .name matches by column name.

const User = struct {
  id: i32,
  name: []const u8,
};

var result = try conn.queryOpts("select id, name from users", .{}, .{.column_names = true});
defer result.deinit();

var mapper = result.mapper(User, .{});
while (try mapper.next()) |user| {
  // use: user.id and user.name
}

TLS is supported through OpenSSL. To enable it, you must configure the pg dependency in your build.zig to include OpenSSL settings.

Setup Steps:

1. In build.zig, provide .openssl_lib_name (e.g., "ssl" or "openssl"). You may also need to provide .openssl_lib_path and .openssl_include_path if OpenSSL is in a non-standard location.
2. Set the connection's tls option to .required or provide a specific configuration like .{ .verify_full = null } or .{ .verify_full = "/path/to/root.crt" }.

Debugging TLS:

• Define pub const pg_stderr_tls = true; in your main file to print TLS errors to stderr.
• Call pg.printSSLError(); in a catch block to attempt to print SSL-specific error details.

// build.zig configuration
const pg_module = b.dependency("pg", .{
  .target = target,
  .optimize = optimize,
  .openssl_lib_name = @as([]const u8, "ssl"),
  .openssl_lib_path = std.Build.LazyPath{.cwd_relative = "/path/to/openssl/lib"},
  .openssl_include_path = std.Build.LazyPath{.cwd_relative = "/path/to/openssl/include"},
}).module("pg");

// Connection configuration
var pool = try pg.Pool.init(allocator, .{
  .connect = .{ .port = 5432, .host = "ip_or_hostname", .tls = .{.verify_full = null}},
  .auth = .{ ... },
  .size = 5,
});

You can use PostgreSQL's LISTEN and NOTIFY features using the pg.Listener type. You can create a listener directly (similar to a standard connection) or via a pg.Pool using pool.newListener().

Key behaviors:

• Blocking: listener.next() blocks until a notification is received or an error occurs.
• Timeouts: You can specify a timeout in milliseconds when calling listen. If no message is received within that window, next() returns null and listener.err will contain error.WouldBlock.
• No Auto-Reconnect: Listeners do not automatically reconnect. To handle disconnects, wrap your listener logic in a while (true) loop.
• Stopping: Calling listener.stop() from any thread will cause next() to return null and set listener.stopped to true.

// Creating a listener directly
var listener = try pg.Listener.open(allocator, .{
  .host = "127.0.0.1",
  .port = 5432,
});
defer listener.deinit();

try listener.auth(.{
  .username = "leto",
  .password = "ghanima",
  .database = "caladan",
});

try listener.listen("chan_1", .{});

while (listener.next()) |notification| {
  std.debug.print("Channel: {s}\nPayload: {s}", .{notification.channel, notification.payload});
}

// Handling errors in the listener
switch (listener.err.?) {
  .pg => |pg| std.debug.print("{s}\n", .{pg.message}),
  .err => |err| std.debug.print("{s}\n", .{@errorName(err)}),
}

To handle PostgreSQL array columns, use row.get(pg.Iterator(T), col). This returns an iterator that can be traversed using .next().

Supported Array Types:

• u8, ?u8 $\rightarrow$ char[]
• i16, ?i16 $\rightarrow$ smallint[]
• i32, ?i32 $\rightarrow$ int[]
• i64, ?i64 $\rightarrow$ bigint[] or timestamp(tz)[]
• f32, ?f32 $\rightarrow$ float4
• f64, ?f64 $\rightarrow$ float8
• bool, ?bool $\rightarrow$ bool[]
• []const u8, []?const u8 $\rightarrow$ text[], char(n)[], bytea[], uuid[], json[], jsonb[]
• pg.Numeric and pg.Cidr

Iterator Methods:

• next() ?T: Returns the next value or null if the end is reached.
• alloc(it, allocator): Allocates a slice and populates it with all values. Note: if the type is a string, the caller is responsible for freeing both the slice and the string values.
• fill(it, into): Fills an existing slice into with values from the iterator. This is faster than multiple next() calls.

var names = try row.get(pg.Iterator([]const u8), 0);
while (names.next()) |name| {
  // process name
}