lib/DBIx/Class/Journal.pm

   1 package DBIx::Class::Journal;
   2
   3 use base qw/DBIx::Class/;
   4
   5 use strict;
   6 use warnings;
   7
   8 our $VERSION = '0.900001_04';
   9 $VERSION = eval $VERSION; # no errors in dev versions
  10
  11 ## On create/insert, add new entry to AuditLog and new content to AuditHistory
  12
  13 sub _journal_schema {
  14     my $self = shift;
  15     $self->result_source->schema->_journal_schema;
  16 }
  17
  18 sub insert {
  19     my ($self, @args) = @_;
  20     return if $self->in_storage;
  21
  22     my $res = $self->next::method(@args);
  23     $self->journal_log_insert;
  24
  25     return $res;
  26 }
  27
  28 sub journal_log_insert {
  29     my ($self) = @_;
  30
  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 );
  36     }
  37 }
  38
  39 ## On delete, update delete_id of AuditLog
  40
  41 sub delete {
  42     my $self = shift;
  43     $self->next::method(@_);
  44     $self->journal_log_delete(@_);
  45 }
  46
  47 sub journal_log_delete {
  48     my ($self) = @_;
  49
  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 );
  53     }
  54 }
  55
  56 ## On update, copy row's new contents to AuditHistory
  57
  58 sub update {
  59     my $self = shift;
  60     $self->next::method(@_);
  61     $self->journal_log_update(@_);
  62 }
  63
  64 sub journal_log_update {
  65     my $self = shift;
  66
  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 );
  71     }
  72 }
  73
  74 =head1 NAME
  75
  76 DBIx::Class::Journal - Auditing for tables managed by DBIx::Class
  77
  78 =head1 SYNOPSIS
  79
  80 Load the module into your L<DBIx::Class> Schema Class:
  81
  82  package My::Schema;
  83  use base 'DBIx::Class::Schema';
  84
  85  __PACKAGE__->load_components(qw/Schema::Journal/);
  86
  87 And then call C<< $schema->journal_schema_deploy >> to create all the tables
  88 necessary for the journal, in your database.
  89
  90 Optionally set where the journal is stored:
  91
  92  __PACKAGE__->journal_connection(['dbi:SQLite:t/var/Audit.db']);
  93
  94 Later on, in your application, wrap operations in transactions, and optionally
  95 associate a user with the changeset:
  96
  97  $schema->changeset_user($user->id);
  98  my $new_artist = $schema->txn_do( sub {
  99     return $schema->resultset('Artist')->create({ name => 'Fred' });
 100  });
 101
 102 =head1 DESCRIPTION
 103
 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
 109 changed.
 110
 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
 113 transaction.
 114
 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 >>.
 119
 120 =head1 DEPLOYMENT
 121
 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.
 126
 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.
 129
 130  # optional - defaults to all sources
 131  My::Schema->journal_sources([qw/ table1 table2 /]);
 132
 133  $schema = My::Schema->connect(...);
 134  $schema->journal_schema_deploy;
 135
 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.
 139
 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.
 143
 144 =head1 TABLES
 145
 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.
 149
 150 =over 4
 151
 152 =item ChangeSet
 153
 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
 158 transaction.
 159
 160 =item ChangeLog
 161
 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.
 165
 166 =item AuditLog
 167
 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.
 174
 175 Note that currently only integer-based single column primary keys are
 176 supported in your original database tables.
 177
 178 =item AuditHistory
 179
 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.
 183
 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
 188 row in this table.
 189
 190 =back
 191
 192 =head1 CLASS METHODS
 193
 194 Call these in your Schema Class such as the C<My::Schema> package file, as in
 195 the SYNOPSIS, above.
 196
 197 =over 4
 198
 199 =item journal_connection \@connect_info
 200
 201 Set the connection information for the database to save your audit information
 202 to.
 203
 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
 206 journalling schema.
 207
 208 =item journal_components @components
 209
 210 If you want to add components to your journal
 211 (L<DBIx::Class::Schema::Versioned> for example) pass them here.
 212
 213 =item journal_sources \@source_names
 214
 215 Set a list of source names you would like to audit. If unset, all sources are
 216 used.
 217
 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.
 220
 221 =item journal_storage_type $type
 222
 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.
 225
 226 =item journal_user \@rel
 227
 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
 230 example:
 231
 232  __PACKAGE__->journal_user(['My::Schema::User', {'foreign.userid' => 'self.user_id'}]);
 233
 234 =back
 235
 236 =head1 OBJECT METHODS
 237
 238 Once you have a connection to your database, call these methods to manage the
 239 journalling.
 240
 241 =over 4
 242
 243 =item journal_schema_deploy
 244
 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.
 247
 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.
 251
 252 =item journal_deploy_on_connect $bool
 253
 254 If set to a true value will cause C<journal_schema_deploy> to be called on
 255 C<connect>.
 256
 257 Not recommended, but present for backwards compatibility.
 258
 259 =item prepopulate_journal
 260
 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
 264 initial state.
 265
 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.
 271
 272 =item changeset_user $user_id
 273
 274 Set the C<user_id> for the following changeset(s). This must be an integer.
 275
 276 =item changeset_session $session_id
 277
 278 Set the C<session_id> for the following changeset(s). This must be an integer.
 279
 280 =item deploy
 281
 282 Overloaded L<DBIx::Class::Schema/deploy> which will deploy your original
 283 database schema and following that will deploy the journal schema.
 284
 285 =item txn_do $code_ref, @args
 286
 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.
 290
 291 Currently nested C<txn_do> calls cause a single ChangeSet object to be created.
 292
 293 =back
 294
 295 =head1 SEE ALSO
 296
 297 =over 4
 298
 299 =item *
 300
 301 L<DBIx::Class> - You'll need it to use this.
 302
 303 =back
 304
 305 =head1 LIMITATIONS
 306
 307 =over 4
 308
 309 =item *
 310
 311 Only single-column integer primary key'd tables are supported for auditing.
 312
 313 =item *
 314
 315 Updates made via L<DBIx::Class::ResultSet/update> are not yet supported.
 316
 317 =item *
 318
 319 No API for viewing or restoring changes yet.
 320
 321 =back
 322
 323 Patches for the above are welcome ;-)
 324
 325 =head1 AUTHOR
 326
 327 Jess Robinson <castaway@desert-island.me.uk>
 328
 329 Matt S. Trout <mst@shadowcatsystems.co.uk> (ideas and prodding)
 330
 331 =head1 LICENCE
 332
 333 You may distribute this code under the same terms as Perl itself.
 334
 335 =cut
 336
 337 1;