1 package DBIx::Class::Journal;
3 use base qw/DBIx::Class/;
8 our $VERSION = '0.900001_04';
9 $VERSION = eval $VERSION; # no errors in dev versions
11 ## On create/insert, add new entry to AuditLog and new content to AuditHistory
15 $self->result_source->schema->_journal_schema;
19 my ($self, @args) = @_;
20 return if $self->in_storage;
22 my $res = $self->next::method(@args);
23 $self->journal_log_insert;
28 sub journal_log_insert {
31 if ( $self->in_storage ) {
32 my $j = $self->_journal_schema;
33 my $change_id = $j->journal_create_change()->id;
34 $j->journal_update_or_create_log_entry( $self, create_id => $change_id );
35 $j->journal_record_in_history( $self, audit_change_id => $change_id );
39 ## On delete, update delete_id of AuditLog
43 $self->next::method(@_);
44 $self->journal_log_delete(@_);
47 sub journal_log_delete {
50 unless ($self->in_storage) {
51 my $j = $self->_journal_schema;
52 $j->journal_update_or_create_log_entry( $self, delete_id => $j->journal_create_change->id );
56 ## On update, copy row's new contents to AuditHistory
60 $self->next::method(@_);
61 $self->journal_log_update(@_);
64 sub journal_log_update {
67 if ($self->in_storage) {
68 my $j = $self->_journal_schema;
69 my $change_id = $j->journal_create_change->id;
70 $j->journal_record_in_history( $self, audit_change_id => $change_id );
76 DBIx::Class::Journal - Auditing for tables managed by DBIx::Class
80 Load the module into your L<DBIx::Class> Schema Class:
83 use base 'DBIx::Class::Schema';
85 __PACKAGE__->load_components(qw/Schema::Journal/);
87 And then call C<< $schema->journal_schema_deploy >> to create all the tables
88 necessary for the journal, in your database.
90 Optionally set where the journal is stored:
92 __PACKAGE__->journal_connection(['dbi:SQLite:t/var/Audit.db']);
94 Later on, in your application, wrap operations in transactions, and optionally
95 associate a user with the changeset:
97 $schema->changeset_user($user->id);
98 my $new_artist = $schema->txn_do( sub {
99 return $schema->resultset('Artist')->create({ name => 'Fred' });
104 The purpose of this L<DBIx::Class> component module is to create an
105 audit-trail for all changes made to the data in your database (via a
106 DBIx::Class schema). It creates I<changesets> and assigns each
107 create/update/delete operation an I<id>. The creation and deletion date of
108 each row is stored, as well as the historical contents of any row that gets
111 All queries which need auditing B<must> be called using
112 L<DBIx::Class::Schema/txn_do>, which is used to create changesets for each
115 To track who did which changes, the C<user_id> (an integer) of the current
116 user can be set, and a C<session_id> can also be set; both are optional. To
117 access the auditing schema to look at the auditdata or revert a change, use
118 C<< $schema->_journal_schema >>.
122 Currently the module expects to be deployed alongside a new database schema,
123 and track all changes from first entry. To do that you need to create some
124 tables in which to store the journal, and you can opitonally configure which
125 data sources (tables) have their operations journalled by the module.
127 Connect to your schema and deploy the journal tables as below. The module
128 automatically scans your schema and sets up storage for journal entries.
130 # optional - defaults to all sources
131 My::Schema->journal_sources([qw/ table1 table2 /]);
133 $schema = My::Schema->connect(...);
134 $schema->journal_schema_deploy;
136 Note that if you are retrofitting journalling to an existing database, then as
137 well as creating the journal you will need to populate it with a history so
138 that when rows are deleted they can be mapped back to a (fake) creation.
140 If you ever update your original schema, remember that you must then also
141 update the journal's schema to match, so that the AuditHistory has the
142 corresponding new columns in which to save data.
146 The journal schema contains a number of tables. These track row creation,
147 update and deletion, and also are aware of multiple operations taking place
148 within one transaction.
154 Each changeset row has an auto-incremented C<ID>, optional C<user_id> and
155 C<session_id>, and a C<set_date> which defaults to the current datetime. This
156 is the authoritative log of one discrete change to your database, which may
157 possible consist of a number of ChangeLog operations within a single
162 Each operation done within the transaction is recorded as a row in the
163 ChangeLog table. It contains an auto-incrementing C<ID>, the C<changeset_id>
164 and an C<order> column to establish the order in which changes took place.
168 For every table in the original database that is to be audited, an AuditLog
169 table is created. When a row appears in the original database a corresponding
170 row is added here with a ChangeLog ID in the C<create_id> column, and when
171 that original row is deleted the AuditLog is updated to add another ChangeLog
172 ID this time into the C<delete_id> column. A third id column contains the
173 primary key of the original row, so you can find it in the AuditHistory.
175 Note that currently only integer-based single column primary keys are
176 supported in your original database tables.
180 For every table in the original database to be audited, an AuditHistory table
181 is created. This is where the actual field data from your original table rows
182 are stored on creation and on each update.
184 Each row in the AuditHistory has a C<change_id> field containing the ID of the
185 ChangeLog row. The other fields correspond to all the fields from the original
186 table (with any constraints removed). Each time a column value in the original
187 table is changed, the entire row contents after the change are added as a new
194 Call these in your Schema Class such as the C<My::Schema> package file, as in
199 =item journal_connection \@connect_info
201 Set the connection information for the database to save your audit information
204 Leaving this blank assumes you want to store the audit data into your current
205 database. The storage object will be shared by the regular schema and the
208 =item journal_components @components
210 If you want to add components to your journal
211 (L<DBIx::Class::Schema::Versioned> for example) pass them here.
213 =item journal_sources \@source_names
215 Set a list of source names you would like to audit. If unset, all sources are
218 NOTE: Currently only sources with a single-column integer PK are supported, so
219 use this method if you have sources which don't comply with that limitation.
221 =item journal_storage_type $type
223 Enter the special storage type of your journal schema if needed. See
224 L<DBIx::Class::Storage::DBI> for more information on storage types.
226 =item journal_user \@rel
228 The user_id column in the L</ChangeSet> will be linked to your user id with a
229 C<belongs_to> relation, if this is set with the appropriate arguments. For
232 __PACKAGE__->journal_user(['My::Schema::User', {'foreign.userid' => 'self.user_id'}]);
236 =head1 OBJECT METHODS
238 Once you have a connection to your database, call these methods to manage the
243 =item journal_schema_deploy
245 Will use L<DBIx::Class::Schema/deploy> to set up the tables for journalling in
246 your schema. Use this method to set up your journal.
248 Note that if you are retrofitting journalling to an existing database, then as
249 well as creating the journal you will need to populate it with a history so
250 that when rows are deleted they can be mapped back to a (fake) creation.
252 =item journal_deploy_on_connect $bool
254 If set to a true value will cause C<journal_schema_deploy> to be called on
257 Not recommended, but present for backwards compatibility.
259 =item prepopulate_journal
261 Will load the current state of your original source tables into the audit
262 history as fake inserts in a single initial changeset. The advantage to this
263 is that later deletetions of the row will be consistent in the journal with an
266 Note that this can be an intensive and time consuming task, depending on how
267 much data you have in your original sources; all of it will be copied to the
268 journal history. However this step is essential if you are retrofitting
269 Journalling to a schema with existing data, otherwise when you delete a row
270 the Journal will die because it cannot relate that to an initial row insert.
272 =item changeset_user $user_id
274 Set the C<user_id> for the following changeset(s). This must be an integer.
276 =item changeset_session $session_id
278 Set the C<session_id> for the following changeset(s). This must be an integer.
282 Overloaded L<DBIx::Class::Schema/deploy> which will deploy your original
283 database schema and following that will deploy the journal schema.
285 =item txn_do $code_ref, @args
287 Overloaded L<DBIx::Class::Schema/txn_do>, this must be used to start a new
288 ChangeSet to cover a group of changes. Each subsequent change to an audited
289 table will use the C<changeset_id> created in the most recent C<txn_do> call.
291 Currently nested C<txn_do> calls cause a single ChangeSet object to be created.
301 L<DBIx::Class> - You'll need it to use this.
311 Only single-column integer primary key'd tables are supported for auditing.
315 Updates made via L<DBIx::Class::ResultSet/update> are not yet supported.
319 No API for viewing or restoring changes yet.
323 Patches for the above are welcome ;-)
327 Jess Robinson <castaway@desert-island.me.uk>
329 Matt S. Trout <mst@shadowcatsystems.co.uk> (ideas and prodding)
333 You may distribute this code under the same terms as Perl itself.