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_01';
   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 Set the connection information for the database to save your audit
 175 information to. Leaving this blank assumes you want to store the audit
 176 data into your current database.
 177
 178 =item journal_sources
 179
 180 =item Arguments: \@source_names
 181
 182 Set a list of source names you would like to audit, if unset, all
 183 sources are used.
 184
 185 NOTE: Currently only sources with a single-column PK are supported, so
 186 use this method if you have sources with multi-column PKs.
 187
 188 =item journal_storage_type
 189
 190 =item Arguments: $storage_type
 191
 192 Enter the special storage type of your journal schema if needed. See
 193 L<DBIx::Class::Storage::DBI> for more information on storage types.
 194
 195 =item journal_user
 196
 197 =item Arguments: \@relation_args
 198
 199 The user_id column in the L</ChangeSet> will be linked to your user id
 200 with a belongs_to relation, if this is set with the appropriate
 201 arguments.
 202
 203 =item changeset_user
 204
 205 =item Arguments: $user_id
 206
 207 Set the user_id for the following changeset(s). This must be an integer.
 208
 209 =item changeset_session
 210
 211 =item Arguments: $user_id
 212
 213 Set the session_id for the following changeset(s). This must be an integer.
 214
 215 =item txn_do
 216
 217 =item Arguments: $code_ref
 218
 219 =back
 220
 221 Overloaded L<DBIx::Class::Schema/txn_do>, this must be used to start a
 222 new changeset to cover a group of changes. Each subsequent change to
 223 an audited table will use the changeset_id created in the most recent
 224 txn_do call.
 225
 226 =back
 227
 228 =head1 SEE ALSO
 229
 230 L<DBIx::Class> - You'll need it to use this.
 231
 232 =head1 NOTES
 233
 234 Only single-column integer primary key'd tables are supported for auditing so far.
 235
 236 Updates made via L<DBIx::Class::ResultSet/update> are not yet supported.
 237
 238 No API for viewing or restoring changes yet.
 239
 240 Patches for the above welcome ;)
 241
 242 =head1 AUTHOR
 243
 244 Jess Robinson <castaway@desert-island.me.uk>
 245
 246 Matt S. Trout <mst@shadowcatsystems.co.uk> (ideas and prodding)
 247
 248 =head1 LICENCE
 249
 250 You may distribute this code under the same terms as Perl itself.
 251
 252 =cut
 253
 254 1;