release 0.900001_06

[dbsrgits/DBIx-Class-Journal.git] / lib / DBIx / Class / Journal.pm

diff --git a/lib/DBIx/Class/Journal.pm b/lib/DBIx/Class/Journal.pm
index 11b18fc..54e0b9d 100644 (file)
--- a/lib/DBIx/Class/Journal.pm
+++ b/lib/DBIx/Class/Journal.pm
@@ -5,7 +5,7 @@ use base qw/DBIx::Class/;
 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
@@ -40,8 +40,9 @@ sub journal_log_insert {
 
 sub delete {
     my $self = shift;
-    $self->next::method(@_);
+    my $ret = $self->next::method(@_);
     $self->journal_log_delete(@_);
+    return $ret
 }
 
 sub journal_log_delete {
@@ -57,8 +58,9 @@ 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 {
@@ -84,8 +86,8 @@ Load the module into your L<DBIx::Class> Schema Class:
 
  __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:
 
@@ -129,7 +131,7 @@ 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;
 
@@ -240,6 +242,15 @@ journalling.
 
 =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
@@ -249,12 +260,21 @@ 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
+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
+
+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.
 
-Not recommended, but present for backwards compatibility.
+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
 
@@ -279,6 +299,24 @@ Currently nested C<txn_do> calls cause a single ChangeSet object to be created.
 
 =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