1DBD::Proxy(3) User Contributed Perl Documentation DBD::Proxy(3)
2
6 DBD::Proxy - A proxy driver for the DBI
7
9 use DBI;
10 $dbh = DBI->connect("dbi:Proxy:hostname=$host;port=$port;dsn=$db",
12 $user, $passwd);
13 # See the DBI module documentation for full details
15
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 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 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 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
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 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 $dbh = DBI->connect("DBI:ODBC:mydb", "joe", "hello");
49 With DBD::Proxy this becomes
51 $dsn = "DBI:Proxy:hostname=alpha;port=3334;dsn=DBI:ODBC:mydb";
53 $dbh = DBI->connect($dsn, "joe", "hello");
54 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 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 DBD::Proxy's DSN string has the format
63 $dsn = "DBI:Proxy:key1=val1; ... ;keyN=valN;dsn=valDSN";
65 In other words, it is a collection of key/value pairs. The following
67 keys are recognized:
68 hostname
70 port
71 Hostname and port of the Proxy server; these keys must be present,
72 no defaults. Example:
73 hostname=alpha;port=3334
75 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 dsn=DBI:ODBC:mydb
83 cipher
85 key
86 usercipher
87 userkey
88 By using these fields you can enable encryption. If you set, for
89 example,
90 cipher=$class;key=$key
92 (note the semicolon) then DBD::Proxy will create a new cipher
94 object by executing
95 $cipherRef = $class->new(pack("H*", $key));
97 and pass this object to the RPC::PlClient module when creating a
99 client. See RPC::PlClient. Example:
100 cipher=IDEA;key=97cd2375efa329aceef2098babdc9721
102 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 Of course encryption requires an appropriately configured server.
112 See <DBD::ProxyServer/CONFIGURATION FILE>.
113 debug
115 Turn on debugging mode
116 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 stderr=1
123 logfile
125 Similar to the stderr attribute, but output will be redirected to
126 the given file.
127 logfile=/dev/null
129 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 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 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 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 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
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 sub DBD::Proxy::db::selectall_arrayref;
167 That will enable selectall_arrayref to be proxied.
169 Currently many methods aren't explicitly proxied and so you get the
171 DBI's default methods executed on the client.
172 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 This may all change in a later version.
179 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 $dbh->{"csv_tables"}->{"passwd"} =
186 { "sep_char" => ":", "eol" => "\n";
187 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 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 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 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 This becomes a little bit clearer, if we rewrite the above code:
203 $tables = $dbh->{"csv_tables"};
205 $tables->{"passwd"} = { "sep_char" => ":", "eol" => "\n";
206 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 The workaround is storing the modified local copy back to the server:
215 $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 Jochen Wiedmann
224 Am Eisteich 9
225 72555 Metzingen
226 Germany
227 Email: joe@ispsoft.de
229 Phone: +49 7123 14887
230 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
236 DBI, RPC::PlClient, Storable
237perl v5.10.1 2007-10-10 DBD::Proxy(3)