···4455See or run [example/main.zig](https://github.com/karlseguin/pg.zig/blob/master/example/main.zig) for a number of examples.
6677-## Experimental TLS
88-This branch has experimental TLS support via openssl. Custom certificates are not yet supported.
99-1010-When loading the module, you must enable openssl by including at least 1 openssl setting:
1111-1212-```zig
1313-const pg_module = b.dependency("pg", .{
1414- .target = target,
1515- .optimize = optimize,
1616- .openssl_lib_name = "ssl",
1717- .openssl_lib_path = std.Build.LazyPath{.cwd_relative = "/path/to/openssl/lib"},
1818- .openssl_include_path = std.Build.LazyPath{.cwd_relative = "/path/to/openssl/include"},
1919-}).module("pg")
2020-2121-The system defaults are use for the library and include paths. These should only be set if openssl is installed in a non-default location. In most cases specifying `.openssl_lib_name = "ssl"` or, for some systems `.openssl_lib_name = "openssl"` should be enough.
2222-2323-Set the connection's `tls` option to true, or specify `sslmode=required` when using a postgresql url path:
2424-2525-```zig
2626-var pool = try pg.Pool.init(allocator, .{
2727- .connect = .{ .port = 5432, .host = "ip_or_hostname", .tls = true},
2828- .auth = .{ .... },
2929- .size = 5,
3030-});
3131-3232-// OR
3333-const uri = try std.Uri.parse("postgresql://user:password@hostname/DBNAME?sslmode=require");
3434-var pool = try pg.Pool.initUri(allocator, uri, 10, 5_000);
3535-```
3636-3737-If you get an error, please call `pg.printSSLError();` to hopefully print an error message to stderr which can be included in a ticket. This can safely be called in a `catch` clause, and will display nothing if the error is NOT SSL-related.
3838-397## Install
4081) Add pg.zig as a dependency in your `build.zig.zon`:
419···6634 .auth = .{
6735 .username = "postgres",
6836 .database = "postgres",
6969- .password = "root_pw",
3737+ .password = "postgres",
7038 .timeout = 10_000,
7139 }
7240});
···594562* `pg_alloc_params` - counts the number of parameter states that were allocated. This indicates that your queries have more parameters than `result_state_size`. If this happens often, consider increasing `result_state_size`.
595563* `pg_alloc_columns` - counts the number of columns states that were allocated. This indicates that your queries are returning more columns than `result_state_size`. If this happens often, consider increasing `result_state_size`.
596564* `pg_alloc_reader` - counts the number of bytes allocated while reading messages from PostgreSQL. This generally happens as a result of large result (e.g. selecting large text fields). Controlled by the `read_buffer` configuration option.
565565+566566+## TLS (Experimental)
567567+TLS is supported via openssl. When loading the module, you must enable openssl by including at least 1 openssl setting:
568568+569569+```zig
570570+const pg_module = b.dependency("pg", .{
571571+ .target = target,
572572+ .optimize = optimize,
573573+ .openssl_lib_name = "ssl",
574574+ .openssl_lib_path = std.Build.LazyPath{.cwd_relative = "/path/to/openssl/lib"},
575575+ .openssl_include_path = std.Build.LazyPath{.cwd_relative = "/path/to/openssl/include"},
576576+}).module("pg")
577577+578578+When not specified, the system defaults are use for the library and include paths. These should only be set if openssl is installed in a non-default location. In most cases specifying `.openssl_lib_name = "ssl"` or, for some systems `.openssl_lib_name = "openssl"` should be enough.
579579+580580+Set the connection's `tls` option to either `.required` or `.{verify_full = null}`. When using a custom root certificate, specify the path: `.{verify_full = "/path/to/root.crt"}`.
581581+582582+```zig
583583+var pool = try pg.Pool.init(allocator, .{
584584+ .connect = .{ .port = 5432, .host = "ip_or_hostname", .tls = .{.verify_full = null}},
585585+ .auth = .{ .... },
586586+ .size = 5,
587587+});
588588+589589+// OR
590590+const uri = try std.Uri.parse("postgresql://user:password@hostname/DBNAME?sslmode=require");
591591+var pool = try pg.Pool.initUri(allocator, uri, 10, 5_000);
592592+```
593593+594594+In your main file, you can define a global `pub const pg_stderr_tls = true;` to have pg.zig print possible TLS-related errors to stderr. Alternatively, if you get an error, you `pg.printSSLError();` to hopefully print an error message to stderr which can be included in a ticket. This can safely be called in a `catch` clause, and will display nothing if the error is NOT SSL-related. Note that using the global `pg_stderr_tls` is more likely to print useful information in the case of certification verification problems.
597595598596## Tests
599597
···11+ALTER SYSTEM SET ssl_ca_file TO '/etc/postgresql/root.key';
22+ALTER SYSTEM SET ssl_key_file TO '/etc/postgresql/server.key';
33+ALTER SYSTEM SET ssl_cert_file TO '/etc/postgresql/server.crt';
44+ALTER SYSTEM SET ssl TO 'ON';
···11-local all postgres trust
11+local all postgres trust
22+host all postgres all trust
23host all pgz_user_clear all password
34host all pgz_user_nopass all trust
45host all pgz_user_scram_sha256 all scram-sha-256
55-host all all all scram-sha-256
66+hostssl all pgz_user_ssl all password