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.02';
   9
  10 ## On create/insert, add new entry to AuditLog
  11
  12 # sub new
  13 # {
  14 #     my ($class, $attrs, @rest) = @_;
  15
  16 #     $class->result_source->schema->_journal_schema->current_user(delete $attrs->{user_id});
  17
  18 #     $class->next::method($attrs, @rest);
  19 # }
  20
  21 sub insert
  22 {
  23     my ($self) = @_;
  24
  25     return if($self->in_storage);
  26     ## create new transaction here?
  27     my $res = $self->next::method();
  28     if($self->in_storage)
  29     {
  30         my $s_name = $self->result_source->source_name();
  31         my $al = $self->result_source->schema->_journal_schema->resultset("${s_name}AuditLog");
  32         $al->update_or_create({
  33             ( map { $_ => $self->get_column($_)} $self->primary_columns ),
  34             created => { changeset_id => $al->result_source->schema->current_changeset },
  35         });
  36     }
  37
  38     return $res;
  39 }
  40
  41 ## On delete, update delete_id of AuditLog
  42
  43 sub delete
  44 {
  45     my ($self, @rest) = @_;
  46     $self->next::method(@rest);
  47
  48     if(!$self->in_storage)
  49     {
  50         my $s_name = $self->result_source->source_name();
  51         my $al = $self->result_source->schema->_journal_schema->resultset("${s_name}AuditLog");
  52         my $alentry = $al->find_or_create({ map { $_ => $self->get_column($_)} $self->primary_columns });
  53
  54         ## bulk_update doesnt do "create new item on update of rel-accessor with hashref, yet
  55         my $change = $self->result_source->schema->_journal_schema->resultset('ChangeLog')->create({ changeset_id => $self->result_source->schema->_journal_schema->current_changeset });
  56         $alentry->delete_id($change->id);
  57         $alentry->update();
  58     }
  59
  60 }
  61
  62 ## On update, copy previous row's contents to AuditHistory
  63
  64 sub update
  65 {
  66     my ($self, $upd, @rest) = @_;
  67
  68     if($self->in_storage)
  69     {
  70         my $s_name = $self->result_source->source_name();
  71         my $ah = $self->result_source->schema->_journal_schema->resultset("${s_name}AuditHistory");
  72
  73         my $obj = $self->result_source->resultset->find( $self->ident_condition );
  74         $ah->create({
  75             $obj->get_columns,
  76             change => { changeset_id => $ah->result_source->schema->current_changeset },
  77         });
  78     }
  79
  80     $self->next::method($upd, @rest);
  81 }
  82
  83 =head1 NAME
  84
  85 DBIx::Class::Journal - auditing for tables managed by DBIx::Class
  86
  87 =head1 SYNOPSIS
  88
  89   package My::Schema;
  90   use base 'DBIx::Class::Schema';
  91
  92   __PACKAGE__->load_components(qw/+DBIx::Class::Schema::Journal/);
  93
  94   __PACKAGE__->journal_connection(['dbi:SQLite:t/var/Audit.db']);
  95   __PACKAGE__->journal_user(['My::Schema::User', {'foreign.userid' => 'self.user_id'}]);
  96
  97
  98  ########
  99
 100   $schema->changeset_user($user->id);
 101   my $new_artist = $schema->txn_do( sub {
 102    return = $schema->resultset('Artist')->create({ name => 'Fred' });
 103   });
 104
 105
 106 =head1 DESCRIPTION
 107
 108 The purpose of this L<DBIx::Class> component module is to create an
 109 audit-trail for all changes made to the data in your database (via a
 110 DBIx::Class schema). It creates changesets and assigns each
 111 create/update/delete operation an id. The creation and deletion date
 112 of each row is stored, as well as the previous contents of any row
 113 that gets changed.
 114
 115 All queries which want auditing should be called using
 116 L<DBIx::Class::Schema/txn_do>, which is used to create changesets for
 117 each transaction.
 118
 119 To track who did which changes, the user_id (an integer) of the
 120 current user can be set, a session_id can also be set, both are
 121 optional.
 122
 123 To access the auditing schema to look at the auditdata or revert a
 124 change, use C<< $schema->_journal_schema >>.
 125
 126 =head2 TABLES
 127
 128 The journal schema contains a number of tables.
 129
 130 =over
 131
 132 =item ChangeSet
 133
 134 Each changeset row has an auto-incremented ID, optional user_id and
 135 session_id, and a set_date which defaults to the current datetime.
 136
 137 A ChangeSet has_many Changes.
 138
 139 =item ChangeLog
 140
 141 Each change/operation done in the transaction is recorded as a row in
 142 the ChangeLog table. It contains an auto-incrementing ID, the
 143 changeset_id and an order column for the ordering of each change in
 144 the changeset.
 145
 146 =item AuditLog
 147
 148 For every table in the original database that is to be audited, an
 149 AuditLog table is created. Each auditlog row has an id which will
 150 contain the primary key of the table it is associated with. (NB:
 151 currently only supports integer-based single column PKs). The
 152 create_id and delete_id fields contain the IDs of the Changes that
 153 created or deleted this row.
 154
 155 =item AuditHistory
 156
 157 For every table in the original database to be audited, an
 158 AuditHistory table is created. Each row has a change_id field
 159 containing the ID of the ChangeLog row. The other fields correspond to
 160 all the fields from the original table. Each time a column value in
 161 the original table is changed, the entire row contents before the
 162 change are added as a new row in this table.
 163
 164 =back
 165
 166 =head2 METHODS
 167
 168 =over
 169
 170 =item journal_connection
 171
 172 =item Arguments: \@connect_info
 173
 174 =back
 175
 176 Set the connection information for the database to save your audit
 177 information to. Leaving this blank assumes you want to store the audit
 178 data into your current database.
 179
 180 =over
 181
 182 =item journal_sources
 183
 184 =item Arguments: \@source_names
 185
 186 =back
 187
 188 Set a list of source names you would like to audit, if unset, all
 189 sources are used.
 190
 191 NOTE: Currently only sources with a single-column PK are supported, so
 192 use this method if you have sources with multi-column PKs.
 193
 194 =over
 195
 196 =item journal_storage_type
 197
 198 =item Arguments: $storage_type
 199
 200 =back
 201
 202 Enter the special storage type of your journal schema if needed. See
 203 L<DBIx::Class::Storage::DBI> for more information on storage types.
 204
 205 =over
 206
 207 =item journal_user
 208
 209 =item Arguments: \@relation_args
 210
 211 =back
 212
 213 The user_id column in the L</ChangeSet> will be linked to your user id
 214 with a belongs_to relation, if this is set with the appropriate
 215 arguments.
 216
 217 =over
 218
 219 =item changeset_user
 220
 221 =item Arguments: $user_id
 222
 223 =back
 224
 225 Set the user_id for the following changeset(s). This must be an integer.
 226
 227 =over
 228
 229 =item changeset_session
 230
 231 =item Arguments: $user_id
 232
 233 =back
 234
 235 Set the session_id for the following changeset(s). This must be an integer.
 236
 237 =over
 238
 239 =item txn_do
 240
 241 =iitem Arguments: $code_ref
 242
 243 =back
 244
 245 Overloaded L<DBIx::Class::Schema/txn_do>, this must be used to start a
 246 new changeset to cover a group of changes. Each subsequent change to
 247 an audited table will use the changeset_id created in the most recent
 248 txn_do call.
 249
 250 =head1 SEE ALSO
 251
 252 L<DBIx::Class> - You'll need it to use this.
 253
 254 =head1 NOTES
 255
 256 Only single-column integer primary key'd tables are supported for auditing so far.
 257
 258 Updates made via L<DBIx::Class::ResultSet/update> are not yet supported.
 259
 260 No API for viewing or restoring changes yet.
 261
 262 Patches for the above welcome ;)
 263
 264 =head1 AUTHOR
 265
 266 Jess Robinson <castaway@desert-island.me.uk>
 267
 268 Matt S. Trout <mst@shadowcatsystems.co.uk> (ideas and prodding)
 269
 270 =head1 LICENCE
 271
 272 You may distribute this code under the same terms as Perl itself.
 273
 274 =cut
 275
 276 1;