NAME

DBIO::PostgreSQL::EV::ConnectInfo - PostgreSQL connection string utilities for DBIO async driver

VERSION

version 0.900007

METHODS

escape_conninfo

my $escaped = escape_conninfo($value);

Escape a single connection parameter value for use in a libpq conninfo string. Handles whitespace, single quotes, and backslashes. A NUL byte in the value is refused, naming the optional $key and never the value: libpq reads the string as a C string, so every parameter behind the NUL would be lost.

conninfo_string

my $str = conninfo_string({ host => 'localhost', port => 5432 });

Convert a hashref of connection parameters into a libpq connection string. Skips undefined values. Dies with a refusal naming the key when a value holds a NUL byte.

with_connect_timeout

my $str = with_connect_timeout("host=db1 dbname=app");
# "host=db1 dbname=app connect_timeout=10"

Every connection this transport opens has a connect timeout: a conninfo string that sets no connect_timeout gets connect_timeout=10 (seconds), one that sets it is returned as it is, whatever the value. libpq's own default waits for ever. A postgresql:// URI and a string this function cannot read as keyword=value pairs come back unchanged.

is_libpq_parameter

is_libpq_parameter('sslmode');   # true
is_libpq_parameter('Sslmode');   # true, in whatever case
is_libpq_parameter('pool_size'); # false

True when $name, lower-cased, is the name of a libpq connection parameter. Used to tell a connection parameter that stands where only DBI attributes are read from the attribute it is spelled like. The list is the keyword list of libpq's PQconninfoOptions (PQconndefaults, libpq 17, read from the installed library), with the keywords the PostgreSQL 18 documentation adds (min_protocol_version, max_protocol_version, sslkeylogfile, the oauth_* keywords, scram_client_key, scram_server_key) and requiressl, which libpq still accepts. It is a superset on purpose: a name libpq does not know it refuses when the connection is opened, so a name here that the linked libpq lacks costs nothing.

dbi_to_conninfo

my $async_info = dbi_to_conninfo([ 'dbi:Pg:dbname=test;host=localhost', $user, $pass, \%attrs ]);
my $async_info = dbi_to_conninfo($connect_info, env => 1);   # DBI_USER, DBI_PASS
my $async_info = dbi_to_conninfo([ $dsn, $user, $pass, \%attrs, \%extra_attributes ]);

Translate a DBI-style connect-info arrayref ([$dsn, $user, $pass, \%attrs, \%extra_attributes], as produced by the sync DBIO::PostgreSQL::Storage) into the async [ \%conninfo, \%opts ] shape consumed by DBIO::PostgreSQL::EV::Storage.

The connect info is read as DBI and DBD::Pg read it, so that the pool connects where, and as whom, the owning storage's dbh does from the same connect info (before it the DSN was split at every ; and at the first = of each piece). That reading is DBI's of the DSN and the attributes, DBD::Pg's rewriting of what DBI hands it, and libpq's of the result:

  • DBI attributes may stand in front of the parameters, dbi:Pg(RaiseError=>1,AutoCommit=>0):dbname=.... They are taken off as DBI takes them off ("dbi_dsn_parts") and count as attributes, over the same name in \%attrs and \%extra_attributes; what follows the : behind them is the DSN DBD::Pg gets.

  • DBI's Username and Password attributes, when defined, are the user and the password, in place of $user and $pass: DBI connects with them, whether they stand in front of the DSN or in an attribute hash, the later of \%attrs and \%extra_attributes winning and the DSN's over both. Defined is enough: an empty Username takes $user away. Pool and dbh are opened as the same user.

  • The first db= or database= names the database, as dbname=; a database name in double quotes is one in single quotes.

  • Parameters are separated by ; or by whitespace. Inside single quotes a ; separates nothing.

  • A parameter is keyword=value, with whitespace allowed around the =. A value in single quotes is the value without them, and may hold whitespace and ;; a backslash takes the next character as it is, quoted or not, so \' and \\ are a quote and a backslash. An empty value is written '': after host=; libpq takes what follows as the host.

  • A keyword is taken as written, in its case, and not checked: libpq refuses one it does not know when the connection is opened. Of a keyword given twice the later value counts.

  • The user and the password -- $user and $pass, or DBI's Username and Password in their place -- when defined and not empty, are the user and password, over a user= or password= in the DSN, which count only without them. DBD::Pg appends its two arguments, quoted, behind the DSN's parameters, and so does this: a DSN that ends in keyword= takes the appended user for that keyword's value.

Dies unless the DSN is one for DBD::Pg -- dbi:Pg:, with or without DBI attributes in front, and with or without parameters behind it, quoting the DSN with its passwords shown as *** (DBIO::Util::mask_connect_secrets): the value of a password, passwd, pwd or pass key, DBI's Password attribute, the password of a URI, and the password beside the DSN wherever the DSN repeats it. The driver and the rest of the DSN stay, so the message still shows what was given -- another driver's DSN, say. Dies as well where libpq would refuse to read the parameters -- one without =, which is also what a bare value with a blank in it leaves behind, or a quote that is never closed -- saying which of the two and nothing of the DSN, where libpq's own message quotes the piece it stopped at.

dbi:Pg: with nothing behind it is a DSN: the dbh connects from it, libpq filling the rest from its environment, and the parameters are the user and the password alone, or none. This function translates it; the transport does not connect from it: "connect_info" in DBIO::PostgreSQL::EV::Storage refuses a DSN that names no dbname, host, port, service or hostaddr. A DSN that names pool_size among its parameters dies, naming pool_size and no value: libpq refuses it, so the dbh of the same connect info fails; it is an attribute (\%attrs, \%extra_attributes or in front of the DSN).

The environment is read for what DBI reads it for when env => 1 is given, and for nothing otherwise: DBI_USER and DBI_PASS are the user and the password where they are still undefined, after DBI's Username and Password. The caller gives it for static connect info; a broker's answer is read without, the broker deciding what it answers. DBI_DSN and DBI_DRIVER are not read: core refuses a DSN that is not given, and the driver is the DSN's.

A postgresql:// or postgres:// URI in place of the parameters (dbi:Pg:postgresql://app:s%40cret@db1:5433/appdb?sslmode=require) is read into the parameters it stands for, as libpq reads it (conninfo_uri_parse): user, password, host, port, dbname and the query's keywords, every part percent-decoded. An IPv6 host is written in brackets; several hosts, h1:5432,h2:5433, make a host and a port of comma-separated lists, and ssl=true is sslmode=require. An empty part sets nothing, and a keyword libpq does not know is left for libpq to refuse when the connection is opened. The scheme counts in lower case and at the start of the parameters only, as for libpq; the rewrites DBD::Pg makes of every DSN's rest -- db=, ; -- come first.

A user and a password beside the URI are read as they are beside keyword=value parameters: when not empty they win over the URI's own. The dbh does not do that -- DBD::Pg appends them to the URI, which libpq then does not read as one, and the connection fails -- so a schema connected like that has a pool and no dbh. A URI libpq cannot read dies saying why, and nothing of the URI: libpq's own message quotes it whole, password included.

The arrayref and the hashes in it are left as they were given.

Of the attributes -- the two hashes and those in front of the DSN -- three are read: Username and Password, as above, and pool_size, which is carried into the conninfo hash; given more than once, \%extra_attributes wins over \%attrs, as the sync storage merges the two ("connect_info" in DBIO::Storage::DBI), and the DSN's over both. Every other attribute is dropped: they are DBD::Pg's or DBI's (pg_enable_utf8, AutoCommit, ...) or the owning storage's own (async, on_connect_do, quote_names, ...), and libpq refuses a connection parameter it does not know. A libpq parameter among them is not dropped but refused: sslmode, connect_timeout and the like belong in the DSN, and DBI's attribute hash would take one without a word and leave the pool connecting without it. This dies naming the keys, never a value, in whichever of the three places the attribute stands and whatever case it is spelled in (Sslmode is a DBI attribute by its capital and sslmode to libpq; see "is_libpq_parameter"). DBI's own Password is the one name that is both, and is read as above. (Given beside an AccessBroker instead, such a parameter is refused by the storage: "connect_info" in DBIO::PostgreSQL::EV::Storage.)

dbi_dsn_parts

my ($driver, $attributes, $parameters) = dbi_dsn_parts($dsn);
# 'dbi:Pg(RaiseError=>1):dbname=app' -> ('Pg', 'RaiseError=>1', 'dbname=app')

A DSN taken apart the way DBI does it before it calls the driver (DBI->connect and DBI->parse_dsn, DBI 1.651): the driver's name, the attributes in parentheses behind it as they are written -- undefined when there are no parentheses -- and what follows the next :, which is the driver's. The pattern is DBI's own, so a DSN is cut where DBI cuts it: the attributes end at the first ):, and a line break among them is no attribute list. The empty list when DBI would find no dbi:driver: in front, or $dsn is not a string. The environment is not read: a DSN that names no driver (dbi::...) has the empty string for one, where DBI takes DBI_DRIVER.

AUTHOR

DBIO Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.