1DBD::Proxy(3)         User Contributed Perl Documentation        DBD::Proxy(3)
2
3
4

NAME

6       DBD::Proxy - A proxy driver for the DBI
7

SYNOPSIS

9         use DBI;
10
11         $dbh = DBI->connect("dbi:Proxy:hostname=$host;port=$port;dsn=$db",
12                             $user, $passwd);
13
14         # See the DBI module documentation for full details
15

DESCRIPTION

17       DBD::Proxy is a Perl module for connecting to a database via a remote
18       DBI driver. See DBD::Gofer for an alternative with different trade-
19       offs.
20
21       This is of course not needed for DBI drivers which already support
22       connecting to a remote database, but there are engines which don't
23       offer network connectivity.
24
25       Another application is offering database access through a firewall, as
26       the driver offers query based restrictions. For example you can
27       restrict queries to exactly those that are used in a given CGI
28       application.
29
30       Speaking of CGI, another application is (or rather, will be) to reduce
31       the database connect/disconnect overhead from CGI scripts by using
32       proxying the connect_cached method. The proxy server will hold the
33       database connections open in a cache. The CGI script then trades the
34       database connect/disconnect overhead for the DBD::Proxy
35       connect/disconnect overhead which is typically much less.  Note that
36       the connect_cached method is new and still experimental.
37

CONNECTING TO THE DATABASE

39       Before connecting to a remote database, you must ensure, that a Proxy
40       server is running on the remote machine. There's no default port, so
41       you have to ask your system administrator for the port number. See
42       DBI::ProxyServer for details.
43
44       Say, your Proxy server is running on machine "alpha", port 3334, and
45       you'd like to connect to an ODBC database called "mydb" as user "joe"
46       with password "hello". When using DBD::ODBC directly, you'd do a
47
48         $dbh = DBI->connect("DBI:ODBC:mydb", "joe", "hello");
49
50       With DBD::Proxy this becomes
51
52         $dsn = "DBI:Proxy:hostname=alpha;port=3334;dsn=DBI:ODBC:mydb";
53         $dbh = DBI->connect($dsn, "joe", "hello");
54
55       You see, this is mainly the same. The DBD::Proxy module will create a
56       connection to the Proxy server on "alpha" which in turn will connect to
57       the ODBC database.
58
59       Refer to the DBI documentation on the "connect" method for a way to
60       automatically use DBD::Proxy without having to change your code.
61
62       DBD::Proxy's DSN string has the format
63
64         $dsn = "DBI:Proxy:key1=val1; ... ;keyN=valN;dsn=valDSN";
65
66       In other words, it is a collection of key/value pairs. The following
67       keys are recognized:
68
69       hostname
70       port
71           Hostname and port of the Proxy server; these keys must be present,
72           no defaults. Example:
73
74               hostname=alpha;port=3334
75
76       dsn The value of this attribute will be used as a dsn name by the Proxy
77           server. Thus it must have the format "DBI:driver:...", in
78           particular it will contain colons. The dsn value may contain
79           semicolons, hence this key *must* be the last and it's value will
80           be the complete remaining part of the dsn. Example:
81
82               dsn=DBI:ODBC:mydb
83
84       cipher
85       key
86       usercipher
87       userkey
88           By using these fields you can enable encryption. If you set, for
89           example,
90
91               cipher=$class;key=$key
92
93           (note the semicolon) then DBD::Proxy will create a new cipher
94           object by executing
95
96               $cipherRef = $class->new(pack("H*", $key));
97
98           and pass this object to the RPC::PlClient module when creating a
99           client. See RPC::PlClient. Example:
100
101               cipher=IDEA;key=97cd2375efa329aceef2098babdc9721
102
103           The usercipher/userkey attributes allow you to use two phase
104           encryption: The cipher/key encryption will be used in the login and
105           authorisation phase. Once the client is authorised, he will change
106           to usercipher/userkey encryption. Thus the cipher/key pair is a
107           host based secret, typically less secure than the
108           usercipher/userkey secret and readable by anyone.  The
109           usercipher/userkey secret is your private secret.
110
111           Of course encryption requires an appropriately configured server.
112           See <DBD::ProxyServer/CONFIGURATION FILE>.
113
114       debug
115           Turn on debugging mode
116
117       stderr
118           This attribute will set the corresponding attribute of the
119           RPC::PlClient object, thus logging will not use syslog(), but
120           redirected to stderr.  This is the default under Windows.
121
122               stderr=1
123
124       logfile
125           Similar to the stderr attribute, but output will be redirected to
126           the given file.
127
128               logfile=/dev/null
129
130       RowCacheSize
131           The DBD::Proxy driver supports this attribute (which is DBI
132           standard, as of DBI 1.02). It's used to reduce network round-trips
133           by fetching multiple rows in one go. The current default value is
134           20, but this may change.
135
136       proxy_no_finish
137           This attribute can be used to reduce network traffic: If the
138           application is calling $sth->finish() then the proxy tells the
139           server to finish the remote statement handle. Of course this slows
140           down things quite a lot, but is prefectly good for reducing memory
141           usage with persistent connections.
142
143           However, if you set the proxy_no_finish attribute to a TRUE value,
144           either in the database handle or in the statement handle, then
145           finish() calls will be supressed. This is what you want, for
146           example, in small and fast CGI applications.
147
148       proxy_quote
149           This attribute can be used to reduce network traffic: By default
150           calls to $dbh->quote() are passed to the remote driver.  Of course
151           this slows down things quite a lot, but is the safest default
152           behaviour.
153
154           However, if you set the proxy_quote attribute to the value
155           '"local"' either in the database handle or in the statement handle,
156           and the call to quote has only one parameter, then the local
157           default DBI quote method will be used (which will be faster but may
158           be wrong).
159

KNOWN ISSUES

161   Unproxied method calls
162       If a method isn't being proxied, try declaring a stub sub in the
163       appropriate package (DBD::Proxy::db for a dbh method, and
164       DBD::Proxy::st for an sth method).  For example:
165
166           sub DBD::Proxy::db::selectall_arrayref;
167
168       That will enable selectall_arrayref to be proxied.
169
170       Currently many methods aren't explicitly proxied and so you get the
171       DBI's default methods executed on the client.
172
173       Some of those methods, like selectall_arrayref, may then call other
174       methods that are proxied (selectall_arrayref calls fetchall_arrayref
175       which calls fetch which is proxied). So things may appear to work but
176       operate more slowly than the could.
177
178       This may all change in a later version.
179
180   Complex handle attributes
181       Sometimes handles are having complex attributes like hash refs or array
182       refs and not simple strings or integers. For example, with DBD::CSV,
183       you would like to write something like
184
185         $dbh->{"csv_tables"}->{"passwd"} =
186               { "sep_char" => ":", "eol" => "\n";
187
188       The above example would advice the CSV driver to assume the file
189       "passwd" to be in the format of the /etc/passwd file: Colons as
190       separators and a line feed without carriage return as line terminator.
191
192       Surprisingly this example doesn't work with the proxy driver. To
193       understand the reasons, you should consider the following: The Perl
194       compiler is executing the above example in two steps:
195
196       1.  The first step is fetching the value of the key "csv_tables" in the
197           handle $dbh. The value returned is complex, a hash ref.
198
199       2.  The second step is storing some value (the right hand side of the
200           assignment) as the key "passwd" in the hash ref from step 1.
201
202       This becomes a little bit clearer, if we rewrite the above code:
203
204         $tables = $dbh->{"csv_tables"};
205         $tables->{"passwd"} = { "sep_char" => ":", "eol" => "\n";
206
207       While the examples work fine without the proxy, the fail due to a
208       subtile difference in step 1: By DBI magic, the hash ref
209       $dbh->{'csv_tables'} is returned from the server to the client.  The
210       client creates a local copy. This local copy is the result of step 1.
211       In other words, step 2 modifies a local copy of the hash ref, but not
212       the server's hash ref.
213
214       The workaround is storing the modified local copy back to the server:
215
216         $tables = $dbh->{"csv_tables"};
217         $tables->{"passwd"} = { "sep_char" => ":", "eol" => "\n";
218         $dbh->{"csv_tables"} = $tables;
219
221       This module is Copyright (c) 1997, 1998
222
223           Jochen Wiedmann
224           Am Eisteich 9
225           72555 Metzingen
226           Germany
227
228           Email: joe@ispsoft.de
229           Phone: +49 7123 14887
230
231       The DBD::Proxy module is free software; you can redistribute it and/or
232       modify it under the same terms as Perl itself. In particular permission
233       is granted to Tim Bunce for distributing this as a part of the DBI.
234

SEE ALSO

236       DBI, RPC::PlClient, Storable
237
238
239
240perl v5.10.1                      2007-10-10                     DBD::Proxy(3)
Impressum