pg.zig

# Native PostgreSQL driver for Zig

A native PostgresSQL driver / client for Zig. Supports [LISTEN](#listen--notify).

See or run [example/main.zig](https://github.com/karlseguin/pg.zig/blob/master/example/main.zig) for a number of examples.

## Zig Version
This is for Zig 0.17.0. See branches for other versions.

## Install
1) Add pg.zig as a dependency in your `build.zig.zon`:

```bash
zig fetch --save git+https://github.com/karlseguin/pg.zig#master
```

2) In your `build.zig`, add the `pg` module as a dependency to your program:

```zig
const pg_module = b.dependency("pg", .{}).module("pg");

// the executable from your executable/library
const exe = b.addExecutable(.{
  .name = "example",
  ...
  .imports = &.{
    .{ .name = "pg", .module = pg_module },
  },
});
```

## Example
```zig
var pool = try pg.Pool.init(io, allocator, .{
  .size = 5,
  .connect = .{
    .port = 5432,
    .host = "127.0.0.1",
  },
  .auth = .{
    .username = "postgres",
    .database = "postgres",
    .password = "postgres",
    .timeout = 10_000,
  }
});
defer pool.deinit();

var result = try pool.query("select id, name from users where power > $1", .{9000});
defer result.deinit();

while (try result.next()) |row| {
  const id = try row.get(i32, 0);
  // this is only valid until the next call to next(), deinit() or drain()
  const name = try row.get([]u8, 1);
}
```

## Pool
The pool holds up to `size` database connections. The `acquire()` method is used to retrieve a connection from the pool. When no idle connection is available and the pool holds fewer than `size` connections, `acquire()` opens a new one. A connection released in an invalid state (e.g. after an error mid-query) is closed, and a new one is opened the next time one is needed.

### init(io: std.Io, allocator: std.mem.allocator, opts: Opts) !\*Pool
Initializes a connection pool. Pool options are:

* `size` - Maximum number of connections. Defaults to `10`.
* `auth`: - See [Conn.auth](#authopts-opts-void)
* `connect`: - See the [Conn.open](#openallocator-stdmemallocator-opts-opts-conn).
* `timeout`: - The amount of time, in milliseconds, to wait for a connection to be available when `acquire()` is called.
* `connect_on_init_count`:  - The # of connections in the pool to eagerly connect during `init`. Defaults to `null` which will initiliaze all connections (`size`). The remaining (`size - connect_on_init_count`) connections are opened on demand by `acquire()`. This can be set to `0`, to prevent `init` from failing except in extreme cases (i.e. OOM), but that will hide any configuration/connection issue until the first query is executed.

### initUri(io: std.Io, allocator: std.mem.Allocator, uri: std.Uri, opts: Opts) !\*Pool
Initializes a connection pool using a std.Uri. When using this function, the `auth` and `connect` fields of `opts` should **not** be set, as these will automatically set based on the provided `uri`.

```zig
const uri = try std.Uri.parse("postgresql://username:password@localhost:5432