/ 
DBIO-0.900004
/ DBIO::Timestamp

NAME

DBIO::Timestamp - Automatically set and update timestamp columns

VERSION

version 0.900004

SYNOPSIS

package MyApp::Schema::Result::Article;
use base 'DBIO::Core';

__PACKAGE__->load_components(qw/Timestamp/);
__PACKAGE__->table('article');
__PACKAGE__->add_columns(
  id         => { data_type => 'integer',  is_auto_increment => 1 },
  title      => { data_type => 'varchar',  size => 255 },
  created_at => { data_type => 'datetime', set_on_create => 1 },
  updated_at => { data_type => 'datetime', set_on_create => 1, set_on_update => 1 },
);
__PACKAGE__->set_primary_key('id');

Or use the helpers to declare both standard columns in one go:

__PACKAGE__->cols_updated_created;

See t/timestamp_runtime.t for a runnable example of the auto-population on insert and update; the column-metadata the helpers install is covered by t/test/10_timestamp_helpers.t.

DESCRIPTION

Automatically populates timestamp columns on insert and update. Columns flagged with set_on_create => 1 are filled in when a new row is inserted; columns flagged with set_on_update => 1 are refreshed on every update.

Explicit values are respected: create is no-clobber, update always refreshes.

The timestamp objects are built by "get_timestamp", which calls timestamp_class->now. The default "timestamp_class" is DateTime::Tiny — a lightweight value class with no compile-time dependency on the full DateTime distribution. A DateTime::Tiny stringifies to an ISO 8601 timestamp literal (YYYY-MM-DDTHH:MM:SS) and can be promoted to a real DateTime on demand via its ->DateTime method (which loads DateTime lazily).

Choosing full DateTime objects

If you would rather store full DateTime objects, set the class once:

__PACKAGE__->timestamp_class('DateTime');

Interoperating with InflateColumn::DateTime

A column may carry both Timestamp and DBIO::InflateColumn::DateTime. InflateColumn::DateTime deflates the column through the storage datetime formatter (format_datetime), which requires a full DateTime object. For any column it manages, Timestamp therefore inflates a default DateTime::Tiny to a real DateTime automatically before storing it, so the combination behaves exactly as it would with a hand-set DateTime. You do not need to set "timestamp_class" for that case; it only affects columns without InflateColumn::DateTime.

METHODS

timestamp_class

__PACKAGE__->timestamp_class('DateTime');   # opt into full DateTime

Class-data accessor naming the class whose ->now constructor "get_timestamp" calls. Defaults to DateTime::Tiny, a lightweight timestamp value class that carries no compile-time dependency on the full DateTime stack. Set it in your Result class (or a shared base class) to any class exposing a now constructor — e.g. 'DateTime' to get full DateTime objects. The named class is loaded on demand.

add_columns

Component override: translates the set_on_create / set_on_update column-info flags into the internal _timestamp_on_create / _timestamp_on_update markers "prepare_insert" and "prepare_update" read, then delegates to next::method. Called the same way as the plain add_columns; not normally called directly.

prepare_insert

Component override of "prepare_insert" in DBIO::Row: fills every set_on_create column that has no value already set with a fresh "get_timestamp", then delegates to next::method. Called by insert and insert_async alike; not normally called directly.

prepare_update

Component override of "prepare_update" in DBIO::Row: refreshes every set_on_update column with a fresh "get_timestamp" (unconditionally, unlike "prepare_insert"'s no-clobber rule), then delegates to next::method. A value for such a column in the update hashref is dropped: the timestamp wins. Called by update and update_async alike; not normally called directly.

get_timestamp

Returns the current-time object used to populate timestamp columns, built as $self->timestamp_class->now — a DateTime::Tiny by default. Set "timestamp_class" to change the class, or override this method entirely in your Result class for full control (e.g. to force a specific timezone).

col_created

__PACKAGE__->col_created;              # creates 'created_at'
__PACKAGE__->col_created('born_at');   # custom name

Adds a NOT NULL timestamp column with set_on_create.

col_updated

__PACKAGE__->col_updated;                # creates 'updated_at'
__PACKAGE__->col_updated('modified_at'); # custom name

Adds a NOT NULL timestamp column with set_on_create and set_on_update.

cols_updated_created

__PACKAGE__->cols_updated_created;

Adds both created_at and updated_at columns in one call.

COLUMN FLAGS

set_on_create => 1

The column receives a fresh timestamp on insert if no value was supplied.

set_on_update => 1

The column is refreshed on every update.

HELPER METHODS

col_created($name)

Adds a set_on_create timestamp column. Default name: created_at.

col_updated($name)

Adds a column with both set_on_create and set_on_update. Default name: updated_at.

cols_updated_created

Adds both standard columns in one call.

OVERRIDABLE METHODS

get_timestamp

Returns the current-time object (timestamp_class->now) used to fill timestamp columns. Override in your Result class to customize, e.g. to set a specific timezone; or set "timestamp_class" to swap the class without overriding the method.

timestamp_class

Class-data accessor naming the class whose ->now constructor "get_timestamp" uses. Defaults to DateTime::Tiny; set to 'DateTime' (or any class exposing now) to change it.

AUTHOR

DBIO & DBIx::Class Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors Portions Copyright (C) 2005-2025 DBIx::Class Authors Based on DBIx::Class, heavily modified.

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