.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Rose::DB::Pg 3pm"
.TH Rose::DB::Pg 3pm "2023-03-04" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Rose::DB::Pg \- PostgreSQL driver class for Rose::DB.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Rose::DB;
\&
\&  Rose::DB\->register_db(
\&    domain   => \*(Aqdevelopment\*(Aq,
\&    type     => \*(Aqmain\*(Aq,
\&    driver   => \*(AqPg\*(Aq,
\&    database => \*(Aqdev_db\*(Aq,
\&    host     => \*(Aqlocalhost\*(Aq,
\&    username => \*(Aqdevuser\*(Aq,
\&    password => \*(Aqmysecret\*(Aq,
\&    server_time_zone => \*(AqUTC\*(Aq,
\&    european_dates   => 1,
\&  );
\&
\&  Rose::DB\->default_domain(\*(Aqdevelopment\*(Aq);
\&  Rose::DB\->default_type(\*(Aqmain\*(Aq);
\&  ...
\&
\&  $db = Rose::DB\->new; # $db is really a Rose::DB::Pg\-derived object
\&  ...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Rose::DB blesses objects into a class derived from Rose::DB::Pg when the driver is \*(L"pg\*(R".  This mapping of driver names to class names is configurable.  See the documentation for Rose::DB's \fBnew()\fR and \fBdriver_class()\fR methods for more information.
.PP
This class cannot be used directly.  You must use Rose::DB and let its \fBnew()\fR method return an object blessed into the appropriate class for you, according to its \fBdriver_class()\fR mappings.
.PP
Only the methods that are new or have different behaviors than those in Rose::DB are documented here.  See the Rose::DB documentation for the full list of methods.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.IP "\fBtimestamps_are_inlined [\s-1BOOL\s0]\fR" 4
.IX Item "timestamps_are_inlined [BOOL]"
Get or set a boolean value that indicates whether or not timestamp keywords should be inline. If \f(CW\*(C`timestamps_are_inlined\*(C'\fR is true, then keywords such as \s-1CURRENT_DATESTAMP\s0 and \s-1CURRENT_TIMESTAMP\s0 are inlined in the generated \s-1SQL\s0 queries. The default is false.
.SH "OBJECT METHODS"
.IX Header "OBJECT METHODS"
.IP "\fBeuropean_dates [\s-1BOOL\s0]\fR" 4
.IX Item "european_dates [BOOL]"
Get or set the boolean value that determines whether or not dates are assumed to be in european dd/mm/yyyy format.  The default is to assume \s-1US\s0 mm/dd/yyyy format (because this is the default for PostgreSQL).
.Sp
This value will be passed to DateTime::Format::Pg as the value of the \f(CW\*(C`european\*(C'\fR parameter in the call to the constructor \f(CW\*(C`new()\*(C'\fR.  This DateTime::Format::Pg object is used by Rose::DB::Pg to parse and format date-related column values in methods like parse_date, format_date, etc.
.IP "\fBnext_value_in_sequence \s-1SEQUENCE\s0\fR" 4
.IX Item "next_value_in_sequence SEQUENCE"
Advance the sequence named \s-1SEQUENCE\s0 and return the new value.  Returns undef if there was an error.
.IP "\fBserver_time_zone [\s-1TZ\s0]\fR" 4
.IX Item "server_time_zone [TZ]"
Get or set the time zone used by the database server software.  \s-1TZ\s0 should be a time zone name that is understood by DateTime::TimeZone.  The default value is \*(L"floating\*(R".
.Sp
This value will be passed to DateTime::Format::Pg as the value of the \f(CW\*(C`server_tz\*(C'\fR parameter in the call to the constructor \f(CW\*(C`new()\*(C'\fR.  This DateTime::Format::Pg object is used by Rose::DB::Pg to parse and format date-related column values in methods like parse_date, format_date, etc.
.Sp
See the DateTime::TimeZone documentation for acceptable values of \s-1TZ.\s0
.IP "\fBpg_enable_utf8 [\s-1BOOL\s0]\fR" 4
.IX Item "pg_enable_utf8 [BOOL]"
Get or set the pg_enable_utf8 database handle attribute.  This is set directly on the dbh, if one exists.  Otherwise, it will be set when the dbh is created.  If no value for this attribute is defined (the default) then it will not be set when the dbh is created, deferring instead to whatever default value DBD::Pg chooses.
.Sp
Returns the value of this attribute in the dbh, if one exists, or the value that will be set when the dbh is next created.
.Sp
See the DBD::Pg documentation to learn more about this attribute.
.IP "\fBsslmode [\s-1MODE\s0]\fR" 4
.IX Item "sslmode [MODE]"
Get or set the \s-1SSL\s0 mode of the connection.  Valid values for \s-1MODE\s0 are \f(CW\*(C`disable\*(C'\fR, \f(CW\*(C`allow\*(C'\fR, \f(CW\*(C`prefer\*(C'\fR, and \f(CW\*(C`require\*(C'\fR.  This attribute is used to build the \s-1DBI\s0 dsn.  Setting it has no effect until the next connection.  See the DBD::Pg documentation to learn more about this attribute.
.SS "Value Parsing and Formatting"
.IX Subsection "Value Parsing and Formatting"
.IP "\fBformat_array \s-1ARRAYREF\s0 | \s-1LIST\s0\fR" 4
.IX Item "format_array ARRAYREF | LIST"
Given a reference to an array or a list of values, return a string formatted according to the rules of PostgreSQL's \*(L"\s-1ARRAY\*(R"\s0 column type.  Undef is returned if \s-1ARRAYREF\s0 points to an empty array or if \s-1LIST\s0 is not passed.
.IP "\fBformat_interval \s-1DURATION\s0\fR" 4
.IX Item "format_interval DURATION"
Given a DateTime::Duration object, return a string formatted according to the rules of PostgreSQL's \*(L"\s-1INTERVAL\*(R"\s0 column type.  If \s-1DURATION\s0 is undefined, a DateTime::Duration object, a valid interval keyword (according to validate_interval_keyword), or if it looks like a function call (matches \f(CW\*(C`/^\ew+\e(.*\e)$/\*(C'\fR) and keyword_function_calls is true, then it is returned unmodified.
.IP "\fBparse_array \s-1STRING\s0\fR" 4
.IX Item "parse_array STRING"
Parse \s-1STRING\s0 and return a reference to an array.  \s-1STRING\s0 should be formatted according to PostgreSQL's \*(L"\s-1ARRAY\*(R"\s0 data type.  Undef is returned if \s-1STRING\s0 is undefined.
.IP "\fBparse_interval \s-1STRING\s0\fR" 4
.IX Item "parse_interval STRING"
Parse \s-1STRING\s0 and return a DateTime::Duration object.  \s-1STRING\s0 should be formatted according to the PostgreSQL native \*(L"interval\*(R" (years, months, days, hours, minutes, seconds) data type.
.Sp
If \s-1STRING\s0 is a DateTime::Duration object, a valid interval keyword (according to validate_interval_keyword), or if it looks like a function call (matches \f(CW\*(C`/^\ew+\e(.*\e)$/\*(C'\fR) and keyword_function_calls is true, then it is returned unmodified.  Otherwise, undef is returned if \s-1STRING\s0 could not be parsed as a valid \*(L"interval\*(R" value.
.IP "\fBvalidate_date_keyword \s-1STRING\s0\fR" 4
.IX Item "validate_date_keyword STRING"
Returns true if \s-1STRING\s0 is a valid keyword for the PostgreSQL \*(L"date\*(R" data type.  Valid (case-insensitive) date keywords are:
.Sp
.Vb 7
\&    current_date
\&    epoch
\&    now
\&    now()
\&    today
\&    tomorrow
\&    yesterday
.Ve
.Sp
The keywords are case sensitive.  Any string that looks like a function call (matches \f(CW\*(C`/^\ew+\e(.*\e)$/\*(C'\fR) is also considered a valid date keyword if keyword_function_calls is true.
.IP "\fBvalidate_datetime_keyword \s-1STRING\s0\fR" 4
.IX Item "validate_datetime_keyword STRING"
Returns true if \s-1STRING\s0 is a valid keyword for the PostgreSQL \*(L"datetime\*(R" data type, false otherwise.  Valid (case-insensitive) datetime keywords are:
.Sp
.Vb 10
\&    \-infinity
\&    allballs
\&    current_date
\&    current_time
\&    current_time()
\&    current_timestamp
\&    current_timestamp()
\&    epoch
\&    infinity
\&    localtime
\&    localtime()
\&    localtimestamp
\&    localtimestamp()
\&    now
\&    now()
\&    timeofday()
\&    today
\&    tomorrow
\&    yesterday
.Ve
.Sp
The keywords are case sensitive.  Any string that looks like a function call (matches \f(CW\*(C`/^\ew+\e(.*\e)$/\*(C'\fR) is also considered a valid datetime keyword if keyword_function_calls is true.
.IP "\fBvalidate_time_keyword \s-1STRING\s0\fR" 4
.IX Item "validate_time_keyword STRING"
Returns true if \s-1STRING\s0 is a valid keyword for the PostgreSQL \*(L"time\*(R" data type, false otherwise.  Valid (case-insensitive) timestamp keywords are:
.Sp
.Vb 8
\&    allballs
\&    current_time
\&    current_time()
\&    localtime
\&    localtime()
\&    now
\&    now()
\&    timeofday()
.Ve
.Sp
The keywords are case sensitive.  Any string that looks like a function call (matches \f(CW\*(C`/^\ew+\e(.*\e)$/\*(C'\fR) is also considered a valid timestamp keyword if keyword_function_calls is true.
.IP "\fBvalidate_timestamp_keyword \s-1STRING\s0\fR" 4
.IX Item "validate_timestamp_keyword STRING"
Returns true if \s-1STRING\s0 is a valid keyword for the PostgreSQL \*(L"timestamp\*(R" data type, false otherwise.  Valid (case-insensitive) timestamp keywords are:
.Sp
.Vb 10
\&    \-infinity
\&    allballs
\&    current_date
\&    current_time
\&    current_time()
\&    current_timestamp
\&    current_timestamp()
\&    epoch
\&    infinity
\&    localtime
\&    localtime()
\&    localtimestamp
\&    localtimestamp()
\&    now
\&    now()
\&    timeofday()
\&    today
\&    tomorrow
\&    yesterday
.Ve
.Sp
The keywords are case sensitive.  Any string that looks like a function call (matches \f(CW\*(C`/^\ew+\e(.*\e)$/\*(C'\fR) is also considered a valid timestamp keyword if keyword_function_calls is true.
.SH "AUTHOR"
.IX Header "AUTHOR"
John C. Siracusa (siracusa@gmail.com)
.SH "LICENSE"
.IX Header "LICENSE"
Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This program is
free software; you can redistribute it and/or modify it under the same terms
as Perl itself.