/ 
DBIO-0.900000
/ DBIO::ChangeLog

NAME

DBIO::ChangeLog - Row-level change tracking component

VERSION

version 0.900000

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');

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

changelog_column_definitions

my %cols = $self->changelog_column_definitions;

Returns the column definitions hash for the changes column of the changelog entry table. Drivers override this to use native types (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::PP.

changelog_deserialize_changes

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

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

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 "changelog_exclude_columns").

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

After next::method, captures all column values. Creates a changelog entry with the deleted values, then performs the delete. 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.

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

Drivers (e.g. DBIO::PostgreSQL::ChangeLog) 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 override to use native types (e.g. jsonb for PostgreSQL).

changelog_serialize_changes($href)

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

changelog_deserialize_changes($raw)

Inverse of the above.

changelog_write_entry($entry)

Write a single changelog entry. Default: create_related on the changelog relationship. 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.