use strict;
use warnings;
-our $VERSION = '0.900001_04';
+our $VERSION = '0.900001_06';
$VERSION = eval $VERSION; # no errors in dev versions
## On create/insert, add new entry to AuditLog and new content to AuditHistory
sub delete {
my $self = shift;
- $self->next::method(@_);
+ my $ret = $self->next::method(@_);
$self->journal_log_delete(@_);
+ return $ret
}
sub journal_log_delete {
sub update {
my $self = shift;
- $self->next::method(@_);
+ my $ret = $self->next::method(@_);
$self->journal_log_update(@_);
+ return $ret
}
sub journal_log_update {
=head1 SYNOPSIS
+Load the module into your L<DBIx::Class> Schema Class:
+
package My::Schema;
use base 'DBIx::Class::Schema';
__PACKAGE__->load_components(qw/Schema::Journal/);
-And then call C<< $schema->journal_schema_deploy >> to create all the tables
-necessary for the journal, in your database.
+And then call C<< $schema->bootstrap_journal >> (I<once only>) to create all
+the tables necessary for the journal, in your database.
Optionally set where the journal is stored:
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
+All queries which need auditing B<must> be called using
L<DBIx::Class::Schema/txn_do>, which is used to create changesets for each
transaction.
To track who did which changes, the C<user_id> (an integer) of the current
-user can be set, and a C<session_id> can also be set; both are optional.
-
-To access the auditing schema to look at the auditdata or revert a change, use
+user can be set, and a C<session_id> 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 >>.
=head1 DEPLOYMENT
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.
+and track all changes from first entry. To do that you need to create some
+tables in which to store the journal, and you can opitonally configure which
+data sources (tables) have their operations journalled by the module.
Connect to your schema and deploy the journal tables as below. The module
automatically scans your schema and sets up storage for journal entries.
+ # optional - defaults to all sources
My::Schema->journal_sources([qw/ table1 table2 /]);
-
+
$schema = My::Schema->connect(...);
$schema->journal_schema_deploy;
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.
+If you ever update your original schema, remember that you must then also
+update the journal's schema to match, so that the AuditHistory has the
+corresponding new columns in which to save data.
+
=head1 TABLES
The journal schema contains a number of tables. These track row creation,
=over 4
+=item bootstrap_journal
+
+This calls C<journal_schema_deploy> followed by C<prepopulate_journal> to
+create your journal tables and if necessary populate them with a snapshot of
+your current original schema data.
+
+Do not run this method more than once on your database, as redeploying the
+journal schema is not supported.
+
=item journal_schema_deploy
Will use L<DBIx::Class::Schema/deploy> to set up the tables for journalling in
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
+Do not run this method more than once on your database, as redeploying the
+journal schema is not supported.
-If set to a true value will cause C<journal_schema_deploy> to be called on
-C<connect>.
+=item prepopulate_journal
-Not recommended, but present for backwards compatibility.
+Will load the current state of your original source tables into the audit
+history as fake inserts in a single initial changeset. The advantage to this
+is that later deletetions of the row will be consistent in the journal with an
+initial state.
+
+Note that this can be an intensive and time consuming task, depending on how
+much data you have in your original sources; all of it will be copied to the
+journal history. However this step is essential if you are retrofitting
+Journalling to a schema with existing data, otherwise when you delete a row
+the Journal will die because it cannot relate that to an initial row insert.
=item changeset_user $user_id
=back
+=head2 Deprecated Methods
+
+=over 4
+
+=item journal_deploy_on_connect $bool
+
+If set to a true value will cause C<journal_schema_deploy> to be called on
+C<connect>. Not recommended (because re-deploy of a schema is not supported),
+but present for backwards compatibility.
+
+=back
+
+=head1 TROUBLESHOOTING
+
+For PostgreSQL databases you must enable quoting on SQL command generation by
+passing C<< { quote_char => q{`}, name_sep => q{.} } >> when connecting to the
+database.
+
=head1 SEE ALSO
=over 4
projects / dbsrgits/DBIx-Class-Journal.git / blobdiff