Author: timbo
Date: Fri Feb 16 17:22:41 2007
New Revision: 9118
Modified:
dbi/trunk/Changes
dbi/trunk/Makefile.PL
dbi/trunk/lib/DBD/Gofer/Transport/Base.pm
dbi/trunk/lib/DBD/Gofer/Transport/http.pm
dbi/trunk/lib/DBD/Gofer/Transport/null.pm
dbi/trunk/lib/DBD/Gofer/Transport/pipeone.pm
dbi/trunk/lib/DBD/Gofer/Transport/stream.pm
dbi/trunk/lib/DBI/Gofer/Transport/mod_perl.pm
dbi/trunk/lib/DBI/Gofer/Transport/pipeone.pm
dbi/trunk/lib/DBI/Gofer/Transport/stream.pm
dbi/trunk/t/85gofer.t
Log:
Added basic docs to all gofer modules.
Make t/85gofer.t warn if DBI_AUTOPROXY is set (unexpectedly)
Modified: dbi/trunk/Changes
==============================================================================
--- dbi/trunk/Changes (original)
+++ dbi/trunk/Changes Fri Feb 16 17:22:41 2007
@@ -7,11 +7,14 @@
=cut
Add attr-passthru to prepare()?
-Test policies.
Guard against version skew.
+Terminology
+routing %dsn_attr to both transport and DBD::Gofer + warn about unknown ones.
+I could make the short name do a lookup in both DBD::Gofer::Transport and
DBIx::Gofer::Transport.
+Document user/passwd issues at the various levels of the stack
-=head2 Changes in DBI 1.54 (svn rev 8791), 2nd February 2007
+=head2 Changes in DBI 1.54 (svn rev 9118), 16th February 2007
NOTE: This release includes the 'next big thing' for DBI: DBD::Gofer.
Take a look!
Modified: dbi/trunk/Makefile.PL
==============================================================================
--- dbi/trunk/Makefile.PL (original)
+++ dbi/trunk/Makefile.PL Fri Feb 16 17:22:41 2007
@@ -99,7 +99,7 @@
You do *not* need these modules for typical DBI usage.
MSG
- sleep 2;
+ sleep 1;
}
if (@missing) {
@@ -111,7 +111,7 @@
ftp://ftp.funet.fi/pub/languages/perl/CPAN/modules/by-module
MSG
- sleep 4;
+ sleep 1;
}
Modified: dbi/trunk/lib/DBD/Gofer/Transport/Base.pm
==============================================================================
--- dbi/trunk/lib/DBD/Gofer/Transport/Base.pm (original)
+++ dbi/trunk/lib/DBD/Gofer/Transport/Base.pm Fri Feb 16 17:22:41 2007
@@ -24,3 +24,26 @@
sub _init_trace { $ENV{DBD_GOFER_TRACE} || 0 }
1;
+
+=head1 NAME
+
+DBD::Gofer::Transport::Base - base class for DBD::Gofer client transports
+
+=head1 SEE ALSO
+
+L<DBD::Gofer>
+
+and some example transports:
+
+L<DBD::Gofer::Transport::stream>
+
+L<DBD::Gofer::Transport::http>
+
+L<DBI::Gofer::Transport::mod_perl>
+
+=cut
+
+
+=cut
+
+
Modified: dbi/trunk/lib/DBD/Gofer/Transport/http.pm
==============================================================================
--- dbi/trunk/lib/DBD/Gofer/Transport/http.pm (original)
+++ dbi/trunk/lib/DBD/Gofer/Transport/http.pm Fri Feb 16 17:22:41 2007
@@ -96,3 +96,26 @@
1;
__END__
+
+=head1 NAME
+
+DBD::Gofer::Transport::http - DBD::Gofer client transport using http
+
+=head1 SYNOPSIS
+
+ my $remote_dsn = "..."
+
DBI->connect("dbi:Gofer:transport=http;url=http://gofer.example.com/gofer;dsn=$remote_dsn";,...)
+
+or, enable by setting the DBI_AUTOPROXY environment variable:
+
+ export
DBI_AUTOPROXY='dbi:Gofer:transport=http;url=http://gofer.example.com/gofer'
+
+=head1 DESCRIPTION
+
+Connect with DBI::Gofer servers that use http transports, i.e.,
L<DBI::Gofer::Transport::mod_perl>.
+
+=head1 SEE ALSO
+
+L<DBD::Gofer> and L<DBI::Gofer::Transport::mod_perl>
+
+=cut
Modified: dbi/trunk/lib/DBD/Gofer/Transport/null.pm
==============================================================================
--- dbi/trunk/lib/DBD/Gofer/Transport/null.pm (original)
+++ dbi/trunk/lib/DBD/Gofer/Transport/null.pm Fri Feb 16 17:22:41 2007
@@ -65,3 +65,40 @@
1;
+__END__
+
+=head1 NAME
+
+DBD::Gofer::Transport::null - DBD::Gofer client transport for testing
+
+=head1 SYNOPSIS
+
+ my $original_dsn = "..."
+ DBI->connect("dbi:Gofer:transport=null;dsn=$original_dsn",...)
+
+or, enable by setting the DBI_AUTOPROXY environment variable:
+
+ export DBI_AUTOPROXY="dbi:Gofer:transport=null"
+
+=head1 DESCRIPTION
+
+Connect via DBD::Gofer but execute the requests within the same process.
+
+This is a quick and simple way to test applications for compatibility with the
+(few) restrictions that DBD::Gofer imposes.
+
+It also provides a simple, portable way for the DBI test suite to be used to
+test DBD::Gofer on all platforms with no setup.
+
+Also, by measuring the difference in performance between normal connections and
+connections via C<dbi:Gofer:transport=null> the basic cost of using DBD::Gofer
+can be measured. Furthermore, the additional cost of more advanced transports
can be
+isolated by comparing their performance with the null transport.
+
+The C<t/85gofer.t> script in the DBI distribution includes a comparative
benchmark.
+
+=head1 SEE ALSO
+
+L<DBD::Gofer>
+
+=cut
Modified: dbi/trunk/lib/DBD/Gofer/Transport/pipeone.pm
==============================================================================
--- dbi/trunk/lib/DBD/Gofer/Transport/pipeone.pm (original)
+++ dbi/trunk/lib/DBD/Gofer/Transport/pipeone.pm Fri Feb 16 17:22:41 2007
@@ -124,7 +124,34 @@
__END__
-Spectacularly inefficient.
+=head1 NAME
+
+DBD::Gofer::Transport::pipeone - DBD::Gofer client transport for testing
+
+=head1 SYNOPSIS
+
+ $original_dsn = "...";
+ DBI->connect("dbi:Gofer:transport=pipeone;dsn=$original_dsn",...)
+
+or, enable by setting the DBI_AUTOPROXY environment variable:
+
+ export DBI_AUTOPROXY="dbi:Gofer:transport=pipeone"
+
+=head1 DESCRIPTION
+
+Connect via DBD::Gofer and execute each request by starting executing a
subprocess.
+
+This is, as you might imagine, spectacularly inefficient!
+
+It's only intended for testing. Specifically it demonstrates that the server
+side is completely stateless.
+
+It also provides a base class for the much more useful
L<DBD::Gofer::Transport::stream>
+transport.
+
+=head1 SEE ALSO
+
+L<DBD::Gofer>
+
+=cut
-Intended as a test of the truely stateless nature of the Gofer servers,
-and an example implementation of a transport that talks to another process.
Modified: dbi/trunk/lib/DBD/Gofer/Transport/stream.pm
==============================================================================
--- dbi/trunk/lib/DBD/Gofer/Transport/stream.pm (original)
+++ dbi/trunk/lib/DBD/Gofer/Transport/stream.pm Fri Feb 16 17:22:41 2007
@@ -128,3 +128,44 @@
__END__
+=head1 NAME
+
+DBD::Gofer::Transport::stream - DBD::Gofer transport for stdio streaming
+
+=head1 SYNOPSIS
+
+ DBI->connect('dbi:Gofer:transport=stream;url=ssh:[EMAIL
PROTECTED];dsn=dbi:...',...)
+
+or, enable by setting the DBI_AUTOPROXY environment variable:
+
+ export DBI_AUTOPROXY='dbi:Gofer:transport=stream;url=ssh:[EMAIL PROTECTED]'
+
+=head1 DESCRIPTION
+
+Without the C<url=> parameter it launches a subprocess as
+
+ perl -MDBI::Gofer::Transport::stream -e run_stdio_hex
+
+and feeds requests into it and reads responses from it. But that's not very
useful.
+
+With a C<url=ssh:[EMAIL PROTECTED]> parameter it launches a subprocess as
+something like
+
+ ssh -q ssh:[EMAIL PROTECTED] bash -c $setup $run
+
+where $run is the command shown above, and $command is
+
+ source .bash_profile 2>/dev/null \
+ || source .bash_login 2>/dev/null \
+ || source .profile 2>/dev/null \
+ ; eval "$@"
+
+which is trying (in a limited an unportable way) to setup the environment
+(PATH, PERL5LIB etc) as it would be if you had logged in to that system.
+
+=head1 SEE ALSO
+
+L<DBD::Gofer>
+
+=cut
+
Modified: dbi/trunk/lib/DBI/Gofer/Transport/mod_perl.pm
==============================================================================
--- dbi/trunk/lib/DBI/Gofer/Transport/mod_perl.pm (original)
+++ dbi/trunk/lib/DBI/Gofer/Transport/mod_perl.pm Fri Feb 16 17:22:41 2007
@@ -97,3 +97,84 @@
__END__
also need a CGI/FastCGI transport
+
+=head1 NAME
+
+DBI::Gofer::Transport::mod_perl - DBD::Gofer server-side transport for http
+
+=head1 SYNOPSIS
+
+In httpd.conf:
+
+ <Location /gofer>
+ SetHandler perl-script
+ PerlHandler DBI::Gofer::Transport::mod_perl
+ </Location>
+
+For the client-side see L<DBD::Gofer::Transport::http>.
+
+=head1 DESCRIPTION
+
+This module implements a DBD::Gofer server-side http transport for mod_perl.
+After configuring this into your httpd.conf, users will be able to use the DBI
+to connect to databases via your apache httpd.
+
+=head1 CONFIGURATION
+
+Rather than provide a DBI proxy that will connect to any database as any user,
+you may well want to restrict access to just one or a few databases.
+
+Or perhaps you want the database passwords to be stored only in httpd.conf so
+you don't have to maintain them in all your clients. In this case you'd
+probably want to use standard https security and authentication.
+
+These kinds of configurations are supported by DBI::Gofer::Transport::mod_perl.
+
+The most simple configuration looks like:
+
+ <Location /gofer>
+ SetHandler perl-script
+ PerlHandler DBI::Gofer::Transport::mod_perl
+ </Location>
+
+That's equivalent to:
+
+ <Perl>
+ DBI::Gofer::Transport::mod_perl->configuration({
+ default => {
+ default_connect_dsn => undef,
+ forced_connect_dsn => undef,
+ default_connect_attributes => { },
+ forced_connect_attributes => { },
+ },
+ });
+ </Perl>
+
+ <Location /gofer/example>
+ SetHandler perl-script
+ PerlSetVar GoferConfig default
+ PerlHandler DBI::Gofer::Transport::mod_perl
+ </Location>
+
+The DBI::Gofer::Transport::mod_perl->configuration({...}) call defines named
configurations.
+The C<PerlSetVar GoferConfig> clause specifies the configuration to be used
for that location.
+
+XXX add detail inclusing specific examples
+
+A single location can specify multiple configurations using C<PerlAddVar>:
+
+ PerlSetVar GoferConfig default
+ PerlAddVar GoferConfig example_foo
+ PerlAddVar GoferConfig example_bar
+
+in which case the configurations are merged with any entries in later
+configurations overriding those in earlier ones. In this way a small number of
+configurations can be mix-n-matched to create specific configurations for
+specific location urls.
+
+=head1 SEE ALSO
+
+L<DBD::Gofer> and L<DBD::Gofer::Transport::http>.
+
+=cut
+
Modified: dbi/trunk/lib/DBI/Gofer/Transport/pipeone.pm
==============================================================================
--- dbi/trunk/lib/DBI/Gofer/Transport/pipeone.pm (original)
+++ dbi/trunk/lib/DBI/Gofer/Transport/pipeone.pm Fri Feb 16 17:22:41 2007
@@ -33,5 +33,16 @@
print $frozen_response;
}
-
1;
+__END__
+
+=head1 NAME
+
+DBI::Gofer::Transport::pipeone - DBD::Gofer server-side transport for pipeone
+
+=head1 SYNOPSIS
+
+See L<DBD::Gofer::Transport::pipeone>.
+
+=cut
+
Modified: dbi/trunk/lib/DBI/Gofer/Transport/stream.pm
==============================================================================
--- dbi/trunk/lib/DBI/Gofer/Transport/stream.pm (original)
+++ dbi/trunk/lib/DBI/Gofer/Transport/stream.pm Fri Feb 16 17:22:41 2007
@@ -38,5 +38,16 @@
}
}
-
1;
+__END__
+
+=head1 NAME
+
+DBI::Gofer::Transport::stream - DBD::Gofer server-side transport for stream
+
+=head1 SYNOPSIS
+
+See L<DBD::Gofer::Transport::stream>.
+
+=cut
+
Modified: dbi/trunk/t/85gofer.t
==============================================================================
--- dbi/trunk/t/85gofer.t (original)
+++ dbi/trunk/t/85gofer.t Fri Feb 16 17:22:41 2007
@@ -23,8 +23,13 @@
my $remote_driver_dsn = "dbm_type=$dbm;lockfile=0";
my $remote_dsn = "dbi:DBM:$remote_driver_dsn";
-# use DBD::Gofer directly.
-# when combined with DBI_AUTOPROXY this means we have DBD::Gofer => DBD::Gofer
=> DBD::DBM!
+if ($ENV{DBI_AUTOPROXY}) {
+ # this means we have DBD::Gofer => DBD::Gofer => DBD::DBM!
+ # rather than disable it we let it run because we're twisted
+ # and because it helps find more bugs (though debugging can be painful)
+ warn "\n$0 is running with DBI_AUTOPROXY enabled ($ENV{DBI_AUTOPROXY})\n"
+ unless $0 =~ /\bzv/; # don't warn for t/zvg_85gofer.t
+}
my $username = getpwuid($>);
my %transports = (
