DateTi...Oracle(3pm)

📦
version 0.06 · 4 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

✨ DateTime::Format::Oracle ✨

okay bestie, gather round 💖 this is the DateTime::Format::Oracle page from the User Contributed Perl Documentation corner of the manual. it's a Perl module that speaks Oracle's date dialect, and honestly? it's giving translator-girlboss energy. let's get into it 🦋

🌸 NAME 🌸

DateTime::Format::Oracle — parse and format Oracle dates and timestamps 💅

✨ SYNOPSIS ✨

use DateTime::Format::Oracle;

$ENV{'NLS_DATE_FORMAT'} = 'YYYY-MM-DD HH24:MI:SS';
my $dt = DateTime::Format::Oracle->parse_datetime('2003-01-16 23:12:01');
my $string = DateTime::Format::Oracle->format_datetime($dt);

like, that's it. that's the whole vibe. 💖

💜 DESCRIPTION 💜

so this module is your little bridge between the Oracle world and the DateTime world. it takes Oracle date and timestamp values and turns them into DateTime objects, and it can also go the other way — hand it a DateTime object and it'll hand you back a date string matching the NLS_DATE_FORMAT. 🔁

Oracle is flexible with date formatting, thanks to its NLS_DATE_FORMAT session variable. dates coming out of Oracle show up according to whatever that variable is currently set to. and dates going into Oracle have to match the current NLS_DATE_FORMAT setting too. no cap. 🎀

timestamps play by either NLS_TIMESTAMP_FORMAT or NLS_TIMESTAMP_TZ_FORMAT — those are the session variables in charge there.

and here's the tea ☕: this module keeps track of those Oracle session variable values by peeking at environment variables of the same name. so every single time one of Oracle's formatting session variables gets updated, you must update the %ENV hash too. don't forget, bestie, or the whole thing falls apart 😭

👑 METHODS 👑

this class is serving the following methods 💅

  • nls_date_format — this one figures out the current value of Oracle's NLS_DATE_FORMAT. right now it just reads from
$ENV{'NLS_DATE_FORMAT'}

or, if that's not set, from the package variable $nls_date_format, which defaults to "YYYY-MM-DD HH24:MI:SS". honestly a great default to have — but it is not Oracle's default. dates will fail to parse if Oracle's NLS_DATE_FORMAT and the value from this method aren't the same. so like, keep them matching fr fr 🙈

if you want to use this module's default, you can do something like this right after you connect to Oracle:

$dbh->do(
    "alter session set nls_date_format = '" .
    DateTime::Format::Oracle->nls_date_format .
    "'"
);
  • nls_timestamp_format — this one figures out the current value of Oracle's NLS_TIMESTAMP_FORMAT. right now it just reads from
$ENV{'NLS_TIMESTAMP_FORMAT'}

or, if that's not set, from the package variable $nls_timestamp_format, which defaults to "YYYY-MM-DD HH24:MI:SS". again, lovely default, not Oracle's default. dates will fail to parse if Oracle's NLS_TIMESTAMP_FORMAT and the value from this method don't match 😭

if you want to use this module's default, you can do something like this right after you connect to Oracle:

$dbh->do(
    "alter session set nls_timestamp_format = '" .
    DateTime::Format::Oracle->nls_timestamp_format .
    "'"
);
  • nls_timestamp_tz_format — this one figures out the current value of Oracle's NLS_TIMESTAMP_TZ_FORMAT. right now it just reads from
$ENV{'NLS_TIMESTAMP_TZ_FORMAT'}

or, if that's not set, from the package variable $nls_timestamp_tz_format, which defaults to "YYYY-MM-DD HH24:MI:SS TZHTZM". yes bestie, this one's got the time zone on the end 🕐✨ still not Oracle's default though. dates will fail to parse if Oracle's NLS_TIMESTAMP_TZ_FORMAT and the value from this method are not the same.

if you want to use this module's default, you can do something like this right after you connect to Oracle:

$dbh->do(
    "alter session set nls_timestamp_tz_format = '" .
    DateTime::Format::Oracle->nls_timestamp_tz_format .
    "'"
);
  • parse_datetime — give it a string holding a date and/or time representation matching NLS_DATE_FORMAT, and it hands back a shiny new DateTime object. 🎁

and if the string is improperly formatted? it may die. 💀

  • parse_date — alias to parse_datetime. because Oracle's date datatype also holds time information, iykyk 🕐
  • parse_timestamp — give it a string holding a date and/or time representation matching NLS_TIMESTAMP_FORMAT, and you get back a new DateTime object.

improperly formatted string? it may die. 💀

  • parse_timestamptz — give it a string holding a date and/or time representation matching NLS_TIMESTAMP_TZ_FORMAT, and boom, new DateTime object.

improperly formatted string? you already know. it may die. 💀

  • parse_timestamp_with_time_zone — (yes bestie, this is the other name sitting right next to parse_timestamptz in the original) — give it a string holding a date and/or time representation matching NLS_TIMESTAMP_TZ_FORMAT, and it returns a new DateTime object.

improperly formatted string? may die. 💀

  • current_date_parser — the current DateTime::Format::Builder-generated parsing method that parse_datetime and parse_date use. 🔧
  • current_timestamp_parser — the current DateTime::Format::Builder-generated parsing method that parse_timestamp uses.
  • current_timestamptz_parser — the current DateTime::Format::Builder-generated parsing method that parse_timestamptz uses.
  • format_datetime — hand it a DateTime object and it returns a string matching the current value of NLS_DATE_FORMAT. ✨

super important: keep $ENV{'NLS_DATE_FORMAT'} the same as the Oracle session variable NLS_DATE_FORMAT. they have to match, periodt.

to determine the current value of Oracle's NLS_DATE_FORMAT:

select NLS_DATE_FORMAT from NLS_SESSION_PARAMETERS

to reset Oracle's NLS_DATE_FORMAT:

alter session set NLS_DATE_FORMAT='YYYY-MM-DD HH24:MI:SS'

and generally? it's a good idea to set NLS_DATE_FORMAT to an unambiguous value — four-digit year, plus hour, minute and second. no ambiguity, no drama 🎀

  • format_date — alias to format_datetime. 💫
  • format_timestamp — hand it a DateTime object and it returns a string matching the current value of NLS_TIMESTAMP_FORMAT.

keep it matched: $ENV{'NLS_TIMESTAMP_FORMAT'} has to equal the Oracle session variable NLS_TIMESTAMP_FORMAT.

to determine the current value of Oracle's NLS_TIMESTAMP_FORMAT:

select NLS_TIMESTAMP_FORMAT from NLS_SESSION_PARAMETERS

to reset Oracle's NLS_TIMESTAMP_FORMAT:

alter session set NLS_TIMESTAMP_FORMAT='YYYY-MM-DD HH24:MI:SS'

and again, set it to an unambiguous value with a four-digit year and hour, minute and second. you'll thank yourself later 🌸

  • format_timestamptz — hand it a DateTime object and it returns a string matching the current value of NLS_TIMESTAMP_TZ_FORMAT.

keep it matched: $ENV{'NLS_TIMESTAMP_TZ_FORMAT'} has to equal the Oracle session variable NLS_TIMESTAMP_TZ_FORMAT.

to determine the current value of Oracle's NLS_TIMESTAMP_TZ_FORMAT:

select NLS_TIMESTAMP_TZ_FORMAT from NLS_SESSION_PARAMETERS

to reset Oracle's NLS_TIMESTAMP_TZ_FORMAT:

alter session set NLS_TIMESTAMP_TZ_FORMAT='YYYY-MM-DD HH24:MI:SS TZHTZM'

and yes, once more with feeling: unambiguous value, four-digit year, hour, minute, second. 🕐

  • format_timestamp_with_time_zone — (the other name riding shotgun with format_timestamptz in the original) — hand it a DateTime object and it returns a string matching the current value of NLS_TIMESTAMP_TZ_FORMAT.

keep it matched: $ENV{'NLS_TIMESTAMP_TZ_FORMAT'} must equal the Oracle session variable NLS_TIMESTAMP_TZ_FORMAT.

to determine the current value of Oracle's NLS_TIMESTAMP_TZ_FORMAT:

select NLS_TIMESTAMP_TZ_FORMAT from NLS_SESSION_PARAMETERS

to reset Oracle's NLS_TIMESTAMP_TZ_FORMAT:

alter session set NLS_TIMESTAMP_TZ_FORMAT='YYYY-MM-DD HH24:MI:SS TZHTZM'

unambiguous value, four-digit year, hour, minute, second. that's the whole sermon 💅

  • current_date_format — the current generated method that format_datetime, format_date, and current_date_parser use to keep track of the strptime translation of NLS_DATE_FORMAT.
  • current_timestamp_format — the current generated method that format_timestamp, format_timestamp_with_time_zone, and current_timestamp_parser use to keep track of the strptime translation of NLS_TIMESTAMP_FORMAT.
  • current_timestamptz_format — the current generated method that format_timestamptz, format_timestamp_with_time_zone, and current_timestamp_parser use to keep track of the strptime translation of NLS_TIMESTAMP_FORMAT.
  • oracle_to_posix — hand it an NLS_DATE_FORMAT, NLS_TIMESTAMP_FORMAT, or NLS_TIMESTAMP_TZ_FORMAT value and it returns a DateTime-compatible strptime format value. 🔄

the translation is currently handled by Convert::NLS_DATE_FORMAT.

💀 LIMITATIONS 💀

Oracle is way more chill about the case of names — months and stuff — whereas DateTime generally returns names in ucfirst format. so like:

MONTH -> FEBRUARY
Month -> February
month -> february

all three of those translate to:

%B    -> February

one format to rule them all, bestie 😌

🌈 TIME ZONES 🌈

Oracle returns all dates and timestamps in a time zone similar to the DateTime floating time zone — except for 'timestamp with time zone' columns. those are the special ones 👑

🧚 INTERVAL ELEMENTS 🧚

ngl, the author has not implemented parse_duration, format_duration, parse_interval, nor format_interval — and has no plans to do so. 🙈

but if you need these features? unit tests, method implementations, and pointers to documentation are all welcome. come through, bestie 🫶

🫶 SUPPORT 🫶

support for this module is provided via the datetime@perl.org email list. see http://lists.perl.org/ for more details. ✉️

📝 TODO 📝

  • possibly read an environment variable to determine a time zone to use instead of 'floating'. 🌍
  • test and document creating an instance via new. 🔧

👑 AUTHOR 👑

Nathan Gray, <kolibrie@cpan.org> 💖

🎀 ACKNOWLEDGEMENTS 🎀

ngl, the author might have put this module off for another couple years without the lure of Jifty, Catalyst, and DBIx::Class pulling at them. 😭

thanks to Dan Horne for his RFC draft of this module. 🫶

Copyright (C) 2006, 2008, 2011 Nathan Gray.

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available. 🎀

🔥 SEE ALSO 🔥

and that's the whole page, bestie 💅 this one came from perl v5.32.0 and was dated 2021-01-04 — the DateTi...Oracle(3pm) of it all. go forth and parse some dates, you absolute icon 👑✨

📦 where this page comes from