Time::...:MySQL(3pm)

🌸 Time::Piece::MySQL 🌸

okay bestie, welcome to Time::Piece::MySQL — it's a Perl module, it's in the 3pm section, and the header calls it "User Contributed Perl Documentation" which is giving ✨community-built, community-loved✨. If you've ever wanted your Time::Piece objects to speak fluent MySQL, this is literally the module for you. 🫶

---

✨ NAME ✨

Time::Piece::MySQL — adds MySQL-specific methods to Time::Piece. that's it, that's the whole job, and it does it slayfully 💅

---

🎀 SYNOPSIS 🎀

use Time::Piece::MySQL;

my $time = localtime;

print $time->mysql_datetime;
print $time->mysql_date;
print $time->mysql_time;

my $time = Time::Piece->from_mysql_datetime( $mysql_datetime );
my $time = Time::Piece->from_mysql_date( $mysql_date );
my $time = Time::Piece->from_mysql_timestamp( $mysql_timestamp );

look at her go 😭 so clean, so concise, so iconic.

---

💖 DESCRIPTION 💖

so here's the vibe: if you use this module instead of Time::Piece, or in addition to Time::Piece (both are valid, we don't gatekeep), it sprinkles a few MySQL-specific date-time methods onto your Time::Piece objects. that's the whole glow-up. no cap. ✨

---

🦋 OBJECT METHODS 🦋

mysql_date / mysql_time / mysql_datetime / mysql_timestamp

these four besties return the date and/or time in a format that MySQL will actually accept. it's giving "translation layer but make it fashion" 💅

---

🌈 CONSTRUCTORS 🌈

from_mysql_date / from_mysql_datetime / from_mysql_timestamp

you hand these ones a date, a datetime, or a timestamp value exactly as MySQL spat it out, and they hand you back a brand new Time::Piece object. so generous of them 🥰

and if the value is NULL? they return undef. no drama, no crash, just undef. periodt.

⚠️ CAVEAT ⚠️

okay bestie, sit down, we need to talk, this part is important 🙈

Time::Piece itself only works with times in the Unix epoch, and this module has the exact same limitation. that's the inherited family trauma, we don't make the rules. but — and this is the messy part — MySQL itself handles date and datetime columns from '1000-01-01' all the way to '9999-12-31'. so if you feed times from outside the Unix epoch into any of the constructors, you get unpredictable results. not "a little off", not "close enough" — unpredictable. fr fr. 💀

and there's more 😭 MySQL does not validate dates (because in its opinion, that's your application's job, and honestly? fair). it only checks that dates are in the right format. so your database might be out here holding dates like 2004-00-00 or 2001-02-31 like it's normal. passing invalid dates to any of the constructors is a bad idea:

• the zero-y kind, like 2004-00-00? on the author's system it returns undef (previous versions used to die, so, glow-up)
• the impossible-day kind, like 2001-02-31? it returns a date in the following month. yes really. it just rolls with it. main character energy but make it calendar math 🫠

so like. validate your dates. your future self will thank you. 💜

---

👑 AUTHOR 👑

• Original author: Dave Rolsky <autarch@urth.org>
• Current maintainer: Marty Pauley <marty+perl@kasei.com>

shoutout to the legends who built and kept this thing alive 🫶

---

⭐ COPYRIGHT ⭐

• (c) 2002 Dave Rolsky
• (c) 2004 Marty Pauley

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. free as in freedom, bestie, go wild 💖

---

🔥 SEE ALSO 🔥

• Time::Piece

go read it, it's the parent module, it's iconic, it's where all the actual time math lives 👑

---

and that's the whole page, bestie ✨ this one came from the perl v5.32.0 docs, dated 2020-12-28, and honestly? still serving. go format some timestamps, you absolute queen 👑💅🎀