DateTi...at::Pg(3pm)

📦

version 0.16014 · 7 versions

0.16014 · opensuse-leap 16.0 (latest)
0.16014 · epel 9
0.16014 · epel 10
0.16014 · alpine 3.24
0.16014 · fedora 43
0.16014 · fedora 44
0.16014 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

DateTi...at::Pg(3pm) — okay bestie, this is the User Contributed Perl Documentation page for DateTime::Format::Pg: Parse and format PostgreSQL dates and times. 💅✨

🌸 SYNOPSIS 🌸

use DateTime::Format::Pg;

my $dt = DateTime::Format::Pg->parse_datetime( '2003-01-16 23:12:01' );

# 2003-01-16 23:12:01
DateTime::Format::Pg->format_datetime($dt);

🦋 DESCRIPTION 🦋

Okay so this module literally understands the formats PostgreSQL uses for its DATE, TIME, TIMESTAMP, and INTERVAL data types. It can parse those formats to make DateTime or DateTime::Duration objects, and it can take a DateTime or DateTime::Duration object and spit out a string that represents it in a format PostgreSQL accepts. No cap, that's the whole vibe. 💖

🎀 CONSTRUCTORS 🎀

These methods are how you make DateTime::Format::Pg objects. 🫶

new( name => value, ... ) — creates a new DateTime::Format::Pg instance. For simple operations you generally don't need this. But if you want a different parsing style from the default, making an object is more comfortable.

my $parser = DateTime::Format::Pg->new()
my $copy = $parser->new( 'european' => 1 );

This method accepts these options:

european — if european is set to non-zero, dates are assumed to be in european dd/mm/yyyy format. The default is to assume US mm/dd/yyyy format (because this is the default for PostgreSQL). This option only has an effect if PostgreSQL is set to output dates in the 'PostgreSQL' (DATE only) and 'SQL' (DATE and TIMESTAMP) styles. Note: you don't have to set this option if the PostgreSQL server has been set to use the 'ISO' format, which is the default. 🗓️
server_tz — this can be a DateTime::TimeZone object or a string containing a time zone name. You must set this value to the same value as the PostgreSQL server's time zone in order to parse TIMESTAMP WITH TIMEZONE values correctly in the 'PostgreSQL', 'SQL', and 'German' formats. Note: you don't have to set this option if the PostgreSQL server has been set to use the 'ISO' format, which is the default. 🌍

clone() — this method is provided for those who prefer to explicitly clone via a method called clone(). 🧬

my $clone = $original->clone();

If called as a class method it will die. 💀

👑 METHODS 👑

This class provides these methods. The parse_datetime, parse_duration, format_datetime, and format_duration methods are general-purpose methods provided for compatibility with other DateTime::Format modules.

The other methods are specific to the corresponding PostgreSQL date/time data types. Their names are derived from the name of the PostgreSQL data type. (Note: prior to PostgreSQL 7.3, the TIMESTAMP type was equivalent to the TIMESTAMP WITH TIME ZONE type. This data type corresponds to the format/parse_timestamp_with_time_zone method but not to the format/parse_timestamp method.) iykyk

🔍 PARSING METHODS 🔍

This class provides these parsing methods.

As a general rule, the parsing methods accept input in any format that the PostgreSQL server can produce. However, if PostgreSQL's DateStyle is set to 'SQL' or 'PostgreSQL', dates can only be parsed correctly if the 'european' option is set correctly (i.e. same as the PostgreSQL server). The same is true for time zones and the 'australian_timezones' option in all modes but 'ISO'.

The default DateStyle, 'ISO', will always produce unambiguous results and is also parsed most efficiently by this parser class. I strongly recommend using this setting unless you have a good reason not to. fr fr, ISO is the main character here. 👑

parse_datetime($string,...) — given a string containing a date and/or time representation, this returns a new DateTime object. If the input string does not contain a date, it is set to 1970-01-01. If the input string does not contain a time, it is set to 00:00:00. If the input string does not contain a time zone, it is set to the floating time zone. If you give it an improperly formatted string, this method may die. 😭
parse_timestamptz($string,...) / parse_timestamp_with_time_zone($string,...) — given a string containing a timestamp (date and time) representation, this returns a new DateTime object. This method is suitable for the TIMESTAMPTZ (or TIMESTAMP WITH TIME ZONE) type. If the input string does not contain a time zone, it is set to the floating time zone. Please note that PostgreSQL does not actually store a time zone along with the TIMESTAMP WITH TIME ZONE (or TIMESTAMPTZ) type — it will just return a time stamp converted for the server's local time zone. If you give it an improperly formatted string, this method may die. ⏰
parse_timestamp($string,...) / parse_timestamp_without_time_zone($string,...) — similar to the functions above, but always returns a DateTime object with a floating time zone. This method is suitable for the TIMESTAMP (or TIMESTAMP WITHOUT TIME ZONE) type. If the server does return a time zone, it is ignored. If you give it an improperly formatted string, this method may die. 🫥
parse_timetz($string,...) / parse_time_with_time_zone($string,...) — given a string containing a time representation, this returns a new DateTime object. The date is set to 1970-01-01. This method is suitable for the TIMETZ (or TIME WITH TIME ZONE) type. If the input string does not contain a time zone, it is set to the floating time zone. Please note that PostgreSQL stores a numerical offset with its TIME WITH TIME ZONE (or TIMETZ) type. It does not store a time zone name (such as 'Europe/Rome'). If you give it an improperly formatted string, this method may die. 🕰️
parse_time($string,...) / parse_time_without_time_zone($string,...) — similar to the functions above, but always returns a DateTime object with a floating time zone. If the server returns a time zone, it is ignored. This method is suitable for use with the TIME (or TIME WITHOUT TIME ZONE) type. This ensures that the resulting DateTime object will always have the time zone expected by your application. If you give it an improperly formatted string, this method may die. ✨
parse_date($string,...) — given a string containing a date representation, this returns a new DateTime object. The time is set to 00:00:00 (floating time zone). This method is suitable for the DATE type. If you give it an improperly formatted string, this method may die. 📅
parse_duration($string) / parse_interval($string) — given a string containing a duration (SQL type INTERVAL) representation, this returns a new DateTime::Duration object. If you give it an improperly formatted string, this method may die. ⏳

✨ FORMATTING METHODS ✨

This class provides these formatting methods.

The output is always in the format mandated by the SQL standard (derived from ISO 8601), which is parsed by PostgreSQL unambiguously in all DateStyle modes. periodt.

format_datetime($datetime,...) — given a DateTime object, this returns a string appropriate as input for all date and date/time types of PostgreSQL. It will contain date and time. If the time zone of the DateTime part is floating, the resulting string will contain no time zone, which will result in the server's time zone being used. Otherwise, the numerical offset of the time zone is used. 🦋
format_time($datetime,...) / format_time_without_time_zone($datetime,...) — given a DateTime object, this returns a string appropriate as input for the TIME type (also known as TIME WITHOUT TIME ZONE), which will contain the local time of the DateTime object and no time zone. 🎀
format_timetz($datetime) / format_time_with_time_zone($datetime) — given a DateTime object, this returns a string appropriate as input for the TIME WITH TIME ZONE type (also known as TIMETZ), which will contain the local part of the DateTime object and a numerical time zone. You should not use the TIME WITH TIME ZONE type to store dates with floating time zones. If the time zone of the DateTime part is floating, the resulting string will contain no time zone, which will result in the server's time zone being used. 🌀
format_date($datetime) — given a DateTime object, this returns a string appropriate as input for the DATE type, which will contain the date part of the DateTime object. 🌸
format_timestamp($datetime) / format_timestamp_without_time_zone($datetime) — given a DateTime object, this returns a string appropriate as input for the TIMESTAMP type (also known as TIMESTAMP WITHOUT TIME ZONE), which will contain the local time of the DateTime object and no time zone. 🕯️
format_timestamptz($datetime) / format_timestamp_with_time_zone($datetime) — given a DateTime object, this returns a string appropriate as input for the TIMESTAMP WITH TIME ZONE type, which will contain the local part of the DateTime object and a numerical time zone. You should not use the TIMESTAMP WITH TIME ZONE type to store dates with floating time zones. If the time zone of the DateTime part is floating, the resulting string will contain no time zone, which will result in the server's time zone being used. 💫
format_duration($du) / format_interval($du) — given a DateTime::Duration object, this returns a string appropriate as input for the INTERVAL type. 🍓

💀 LIMITATIONS 💀

okay so real talk: some PostgreSQL output formats are lowkey messy, and this class can only pass those limitations straight through to you — it can’t magically make them disappear. 💅

As a general rule, none of these limitations apply to the 'ISO' output format. It is strongly recommended to use this format — and to use PostgreSQL’s to_char function when another output format that’s not supposed to be handled by a parser of this class is desired. 'ISO' is the default, but you’re advised to explicitly set it at the beginning of the session by issuing:

SET DATESTYLE TO 'ISO';

…in case the server administrator changes that setting. 😭 When formatting DateTime objects, this class always uses a format that’s handled unambiguously by PostgreSQL. periodt.

🌍 TIME ZONES 🌍

If DateStyle is set to 'PostgreSQL', 'SQL', or 'German', PostgreSQL does not send numerical time zones for the TIMESTAMPTZ (or TIMESTAMP WITH TIME ZONE) type. And unfortunately, the time zone names used instead can be ambiguous: for example, 'EST' can mean -0500, +1000, or +1100. 🫠

You must set the server_tz variable to a time zone that is identical to that of the PostgreSQL server. If the server is set to a different time zone (or the underlying operating system interprets the time zone differently), the parser will return wrong times. no cap.

You can avoid such problems by setting the server’s time zone to UTC using the SET TIME ZONE 'UTC' command and setting the server_tz parameter to 'UTC' (or by using the ISO output format, of course). ✨

🗓️ EUROPEAN DATES 🗓️

For the SQL (for DATE and TIMSTAMP[TZ]) and the PostgreSQL (for DATE) output format, the server can send dates in both European-style 'dd/mm/yyyy' and in US-style 'mm/dd/yyyy' format. In order to parse these dates correctly, you have to pass the 'european' option to the constructor or to the "parse_xxx" routines. 💖

This problem does not occur when using the ISO or German output format (and for PostgreSQL with TIMESTAMP[TZ] as month names are used then). slay.

⏳ INTERVAL ELEMENTS ⏳

DateTime::Duration stores months, days, minutes and seconds separately. PostgreSQL only stores months and seconds and disregards the irregular length of days due to DST switching and the irregular length of minutes due to leap seconds. So, therefore, it is not possible to store DateTime::Duration objects as SQL INTERVALs without the loss of some information. 💀

➖ NEGATIVE INTERVALS ➖

In the SQL and German output formats, the server does not send an indication of the sign with intervals. This means that '1 month ago' and '1 month' are both returned as '1 mon'. 🙈

This problem can only be avoided by using the 'ISO' or 'PostgreSQL' output format. iykyk.

🫶 SUPPORT 🫶

Support for this module is provided via the datetime@perl.org email list. See http://lists.perl.org/ for more details. 💌

👑 AUTHOR 👑

Daisuke Maki <daisuke@endeworks.jp>

🌟 AUTHOR EMERITUS 🌟

Claus A. Faerber <perl@faerber.muc.de>

📜 COPYRIGHT 📜

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

The full text of the license can be found in the LICENSE file included with this module.

👀 SEE ALSO 👀

datetime@perl.org mailing list
http://datetime.perl.org/

That’s the whole vibe, bestie — source/version perl v5.42.0, dated 2021-03-16, from DateTi...at::Pg(3pm). Go forth and parse responsibly 💅✨💖

📦 where this page comes from

opensuse-leap 16.0: perl-DateTime-Format-Pg 0.16014-bp160.1.11 · Artistic-1.0 OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms