/ 
DBIO-0.900004
/ DBIO::ChangeLog

NAME

DBIO::ChangeLog - Row-level change tracking component

VERSION

version 0.900004

SYNOPSIS

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

__PACKAGE__->load_components('ChangeLog');
__PACKAGE__->table('artist');
__PACKAGE__->add_columns(
  id            => { data_type => 'integer', is_auto_increment => 1 },
  name          => { data_type => 'varchar', size => 100 },
  password_hash => { data_type => 'varchar', size => 255, changelog => 0 },
);
__PACKAGE__->set_primary_key('id');

See t/changelog/ for a runnable example.

DESCRIPTION

Automatically tracks insert, update, and delete operations on a Result class. Load via load_components('ChangeLog') on any Result class whose changes you want to record.

Changelog entries are written to a per-source <table>_changelog table that is auto-generated by DBIO::ChangeLog::Schema.

METHODS

add_columns

Component override: translates the changelog => 0 column-info flag into the internal _changelog_exclude marker _changelog_excluded_columns reads, then delegates to next::method. Called the same way as the plain add_columns; not normally called directly.

changelog_column_definitions

my %cols = $self->changelog_column_definitions;

Returns the column definitions hash for the changes column of the changelog entry table. The base implementation returns a text column; a driver or application component can override this to use a native type (e.g. jsonb for PostgreSQL).

changelog_serialize_changes

my $json_str = $self->changelog_serialize_changes(\%changes);

Serializes the changes hashref for storage. Base implementation uses JSON::MaybeXS.

changelog_deserialize_changes

my $href = $self->changelog_deserialize_changes($raw);

Deserializes stored changes back to a hashref. Base implementation uses JSON::MaybeXS.

changelog_write_entry

$self->changelog_write_entry(\%entry);

Writes a single changelog entry to the changelog table. The base implementation uses resultset->create on the changelog source.

Error handling: If the write fails (e.g., foreign key constraint violation, disk full), the exception propagates to the caller. This allows the transaction to be rolled back if the changelog write is critical. Wrap in try/catch if you need to handle failures gracefully.

Drivers can override this to batch writes, use COPY, or async insert.

changelog_notify

$self->changelog_notify($event, \%entry);

Called after a changelog entry is written. No-op in the base implementation. Drivers can override to send notifications (e.g. PostgreSQL pg_notify).

insert

After next::method, creates a changelog entry recording all column values (excluding columns flagged changelog => 0, see "COLUMN FLAGS").

update

Before next::method, captures dirty columns. After a successful update, creates a changelog entry with { col => [old, new] } diffs. Skips if no tracked columns changed.

delete

Before next::method, captures the tracked column values. After a successful delete, creates a changelog entry with the deleted values. The changelog entry is written after the delete to ensure the audit-log guarantee that a changelog entry implies the operation succeeded.

log_event

$row->log_event('approved', { by => $admin_id, reason => 'verified' });

Creates a custom changelog entry. The changeset_id is set if called inside a "txn_do" in DBIO::ChangeLog::Schema, otherwise it is NULL.

changelog

my $rs = $row->changelog;

Returns a ResultSet of changelog entries for this row, filtered by row_id. A binding made with "with_context" in DBIO::Row goes with it.

COLUMN FLAGS

changelog => 0

The column is omitted from changelog entries for insert and delete events; changes to it are not recorded in update events. Useful for sensitive fields like password hashes.

OVERRIDABLE METHODS

A driver or application component can override these via next::method to customize storage formats, write paths, and notification.

changelog_column_definitions

Column definitions hash for the changes column of the changelog entry table. Drivers can override to use native types (e.g. jsonb for PostgreSQL).

changelog_serialize_changes($href)

Serialise the changes hashref for storage. Default: JSON::MaybeXS.

changelog_deserialize_changes($raw)

Inverse of the above.

changelog_write_entry($entry)

Write a single changelog entry. Default: create on the companion <source>_ChangeLog resultset. Drivers can override for batch writes, COPY, or async insert.

changelog_notify($event, $entry)

Called after a changelog entry is written. No-op by default. Drivers can override to e.g. send a pg_notify.

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.