From: Oliver Gorwits Date: Mon, 26 Apr 2010 23:49:38 +0000 (+0000) Subject: more documentation updates X-Git-Tag: v0.900201~26 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=b468e28b8023b5eb3a879b4784a6e689fc98ac5d;p=dbsrgits%2FDBIx-Class-Journal.git more documentation updates --- diff --git a/lib/DBIx/Class/Journal.pm b/lib/DBIx/Class/Journal.pm index 6ba9cd0..78ef04d 100644 --- a/lib/DBIx/Class/Journal.pm +++ b/lib/DBIx/Class/Journal.pm @@ -85,89 +85,115 @@ DBIx::Class::Journal - Auditing for tables managed by DBIx::Class And then call C<< $schema->journal_schema_deploy >> to create all the tables necessary for the journal, in your database. -Optionally set where the journal is stored, and associate a user ID with -each changeset. +Optionally set where the journal is stored: __PACKAGE__->journal_connection(['dbi:SQLite:t/var/Audit.db']); - __PACKAGE__->journal_user(['My::Schema::User', {'foreign.userid' => 'self.user_id'}]); - - ####### +Later on, in your application, wrap operations in transactions, and optionally +associate a user with the changeset: $schema->changeset_user($user->id); my $new_artist = $schema->txn_do( sub { return $schema->resultset('Artist')->create({ name => 'Fred' }); }); - =head1 DESCRIPTION The purpose of this L component module is to create an audit-trail for all changes made to the data in your database (via a -DBIx::Class schema). It creates changesets and assigns each -create/update/delete operation an id. The creation and deletion date -of each row is stored, as well as the previous contents of any row -that gets changed. +DBIx::Class schema). It creates I and assigns each +create/update/delete operation an I. The creation and deletion date of +each row is stored, as well as the historical contents of any row that gets +changed. All queries which need auditing must be called using -L, which is used to create changesets for -each transaction. +L, which is used to create changesets for each +transaction. -To track who did which changes, the user_id (an integer) of the -current user can be set, a session_id can also be set, both are -optional. +To track who did which changes, the C (an integer) of the current +user can be set, and a C can also be set; both are optional. -To access the auditing schema to look at the auditdata or revert a -change, use C<< $schema->_journal_schema >>. +To access the auditing schema to look at the auditdata or revert a change, use +C<< $schema->_journal_schema >>. -=head2 TABLES +=head1 DEPLOYMENT -The journal schema contains a number of tables. +Currently the module expects to be deployed alongside a new database schema, +and track all changes from first entry. Do do that you need to add some tables +for the journal, and you can configure which tables have their operations +journalled by the module. -=over +Connect to your schema and deploy the journal tables as below. The module +automatically scans your schema and sets up storage for journal entries. -=item ChangeSet + My::Schema->journal_sources([qw/ table1 table2 /]); + + $schema = My::Schema->connect(...); + $schema->journal_schema_deploy; -Each changeset row has an auto-incremented ID, optional user_id and -session_id, and a set_date which defaults to the current datetime. +Note that if you are retrofitting journalling to an existing database, then as +well as creating the journal you will need to populate it with a history so +that when rows are deleted they can be mapped back to a (fake) creation. -A ChangeSet has_many Changes. +=head1 TABLES + +The journal schema contains a number of tables. These track row creation, +update and deletion, and also are aware of multiple operations taking place +within one transaction. + +=over 4 + +=item ChangeSet + +Each changeset row has an auto-incremented C, optional C and +C, and a C which defaults to the current datetime. This +is the authoritative log of one discrete change to your database, which may +possible consist of a number of ChangeLog operations within a single +transaction. =item ChangeLog -Each change/operation done in the transaction is recorded as a row in -the ChangeLog table. It contains an auto-incrementing ID, the -changeset_id and an order column for the ordering of each change in -the changeset. +Each operation done within the transaction is recorded as a row in the +ChangeLog table. It contains an auto-incrementing C, the C +and an C column to establish the order in which changes took place. =item AuditLog -For every table in the original database that is to be audited, an -AuditLog table is created. Each auditlog row has an id which will -contain the primary key of the table it is associated with. (NB: -currently only supports integer-based single column PKs). The -create_id and delete_id fields contain the IDs of the Changes that -created or deleted this row. +For every table in the original database that is to be audited, an AuditLog +table is created. When a row appears in the original database a corresponding +row is added here with a ChangeLog ID in the C column, and when +that original row is deleted the AuditLog is updated to add another ChangeLog +ID this time into the C column. A third id column contains the +primary key of the original row, so you can find it in the AuditHistory. + +Note that currently only integer-based single column primary keys are +supported in your original database tables. =item AuditHistory -For every table in the original database to be audited, an -AuditHistory table is created. Each row has a change_id field -containing the ID of the ChangeLog row. The other fields correspond to -all the fields from the original table. Each time a column value in -the original table is changed, the entire row contents before the -change are added as a new row in this table. +For every table in the original database to be audited, an AuditHistory table +is created. This is where the actual field data from your original table rows +are stored on creation and on each update. + +Each row in the AuditHistory has a C field containing the ID of the +ChangeLog row. The other fields correspond to all the fields from the original +table (with any constraints removed). Each time a column value in the original +table is changed, the entire row contents after the change are added as a new +row in this table. =back -=head2 METHODS +=head1 CLASS METHODS + +Call these in your Schema Class such as the C package file, as in +the SYNOPSIS, above. -=over +=over 4 =item journal_connection \@connect_info -Set the connection information for the database to save your audit -information to. +Set the connection information for the database to save your audit information +to. Leaving this blank assumes you want to store the audit data into your current database. The storage object will be shared by the regular schema and the @@ -180,11 +206,11 @@ If you want to add components to your journal =item journal_sources \@source_names -Set a list of source names you would like to audit, if unset, all -sources are used. +Set a list of source names you would like to audit. If unset, all sources are +used. -NOTE: Currently only sources with a single-column PK are supported, so -use this method if you have sources with multi-column PKs. +NOTE: Currently only sources with a single-column integer PK are supported, so +use this method if you have sources which don't comply with that limitation. =item journal_storage_type $type @@ -193,14 +219,29 @@ L for more information on storage types. =item journal_user \@rel -The user_id column in the L will be linked to your user id -with a belongs_to relation, if this is set with the appropriate -arguments. +The user_id column in the L will be linked to your user id with a +C relation, if this is set with the appropriate arguments. For +example: + + __PACKAGE__->journal_user(['My::Schema::User', {'foreign.userid' => 'self.user_id'}]); + +=back + +=head1 OBJECT METHODS + +Once you have a connection to your database, call these methods to manage the +journalling. + +=over 4 =item journal_schema_deploy -Will use L to set up the tables for -journalling in your schema. Use this method to set up your journal. +Will use L to set up the tables for journalling in +your schema. Use this method to set up your journal. + +Note that if you are retrofitting journalling to an existing database, then as +well as creating the journal you will need to populate it with a history so +that when rows are deleted they can be mapped back to a (fake) creation. =item journal_deploy_on_connect $bool @@ -211,23 +252,22 @@ Not recommended, but present for backwards compatibility. =item changeset_user $user_id -Set the user_id for the following changeset(s). This must be an integer. +Set the C for the following changeset(s). This must be an integer. =item changeset_session $session_id -Set the session_id for the following changeset(s). This must be an integer. +Set the C for the following changeset(s). This must be an integer. =item deploy -Overloaded L which will deploy your primary +Overloaded L which will deploy your original database schema and following that will deploy the journal schema. =item txn_do $code_ref, @args -Overloaded L, this must be used to start a -new changeset to cover a group of changes. Each subsequent change to -an audited table will use the changeset_id created in the most recent -txn_do call. +Overloaded L, this must be used to start a new +ChangeSet to cover a group of changes. Each subsequent change to an audited +table will use the C created in the most recent C call. Currently nested C calls cause a single ChangeSet object to be created. @@ -235,17 +275,33 @@ Currently nested C calls cause a single ChangeSet object to be created. =head1 SEE ALSO +=over 4 + +=item * + L - You'll need it to use this. -=head1 NOTES +=back -Only single-column integer primary key'd tables are supported for auditing so far. +=head1 LIMITATIONS + +=over 4 + +=item * + +Only single-column integer primary key'd tables are supported for auditing. + +=item * Updates made via L are not yet supported. +=item * + No API for viewing or restoring changes yet. -Patches for the above welcome ;) +=back + +Patches for the above are welcome ;-) =head1 AUTHOR