Added how to '.. fetch a single (or topmost) row?' to the FAQ
[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Storage / Statistics.pm
1 package DBIx::Class::Storage::Statistics;
2 use strict;
3
4 use base qw/DBIx::Class::AccessorGroup Class::Data::Accessor/;
5 __PACKAGE__->mk_group_accessors(simple => qw/callback debugfh/);
6
7 =head1 NAME
8
9 DBIx::Class::Storage::Statistics - SQL Statistics
10
11 =head1 SYNOPSIS
12
13 =head1 DESCRIPTION
14
15 This class is called by DBIx::Class::Storage::DBI as a means of collecting
16 statistics on it's actions.  Using this class alone merely prints the SQL
17 executed, the fact that it completes and begin/end notification for
18 transactions.
19
20 To really use this class you should subclass it and create your own method
21 for collecting the statistics as discussed in L<DBIx::Class::Manual::Cookbook>.
22
23 =head1 METHODS
24
25 =cut
26
27 =head2 new
28
29 Returns a new L<DBIx::Class::Storage::Statistics> object.
30
31 =cut
32 sub new {
33   my $self = {};
34   bless $self, (ref($_[0]) || $_[0]);
35
36   return $self;
37 }
38
39 =head2 debugfh
40
41 Sets or retrieves the filehandle used for trace/debug output.  This should
42 be an IO::Handle compatible object (only the C<print> method is used). Initially
43 should be set to STDERR - although see information on the
44 L<DBIC_TRACE> environment variable.
45
46 =head2 txn_begin
47
48 Called when a transaction begins.
49
50 =cut
51 sub txn_begin {
52   my $self = shift;
53
54   $self->debugfh->print("BEGIN WORK\n");
55 }
56
57 =head2 txn_rollback
58
59 Called when a transaction is rolled back.
60
61 =cut
62 sub txn_rollback {
63   my $self = shift;
64
65   $self->debugfh->print("ROLLBACK\n");
66 }
67
68 =head2 txn_commit
69
70 Called when a transaction is committed.
71
72 =cut
73 sub txn_commit {
74   my $self = shift;
75
76   $self->debugfh->print("COMMIT\n");
77 }
78
79 =head2 query_start
80
81 Called before a query is executed.  The first argument is the SQL string being
82 executed and subsequent arguments are the parameters used for the query.
83
84 =cut
85 sub query_start {
86   my ($self, $string, @bind) = @_;
87
88   my $message = "$string: ".join(', ', @bind)."\n";
89
90   if(defined($self->callback)) {
91     $string =~ m/^(\w+)/;
92     $self->callback->($1, $message);
93     return;
94   }
95
96   $self->debugfh->print($message);
97 }
98
99 =head2 query_end
100
101 Called when a query finishes executing.  Has the same arguments as query_start.
102
103 =cut
104 sub query_end {
105   my ($self, $string) = @_;
106 }
107
108 1;
109
110 =head1 AUTHORS
111
112 Cory G. Watson <gphat@cpan.org>
113
114 =head1 LICENSE
115
116 You may distribute this code under the same license as Perl itself.
117
118 =cut