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.
19 This is of course not needed for DBI drivers which already support con‐
21 necting to a remote database, but there are engines which don't offer
22 network connectivity.
23 Another application is offering database access through a firewall, as
25 the driver offers query based restrictions. For example you can
26 restrict queries to exactly those that are used in a given CGI applica‐
27 tion.
28 Speaking of CGI, another application is (or rather, will be) to reduce
30 the database connect/disconnect overhead from CGI scripts by using
31 proxying the connect_cached method. The proxy server will hold the
32 database connections open in a cache. The CGI script then trades the
33 database connect/disconnect overhead for the DBD::Proxy connect/discon‐
34 nect overhead which is typically much less. Note that the con‐
35 nect_cached method is new and still experimental.
36
38 Before connecting to a remote database, you must ensure, that a Proxy
39 server is running on the remote machine. There's no default port, so
40 you have to ask your system administrator for the port number. See
41 DBI::ProxyServer for details.
42 Say, your Proxy server is running on machine "alpha", port 3334, and
44 you'd like to connect to an ODBC database called "mydb" as user "joe"
45 with password "hello". When using DBD::ODBC directly, you'd do a
46 $dbh = DBI->connect("DBI:ODBC:mydb", "joe", "hello");
48 With DBD::Proxy this becomes
50 $dsn = "DBI:Proxy:hostname=alpha;port=3334;dsn=DBI:ODBC:mydb";
52 $dbh = DBI->connect($dsn, "joe", "hello");
53 You see, this is mainly the same. The DBD::Proxy module will create a
55 connection to the Proxy server on "alpha" which in turn will connect to
56 the ODBC database.
57 Refer to the DBI documentation on the "connect" method for a way to
59 automatically use DBD::Proxy without having to change your code.
60 DBD::Proxy's DSN string has the format
62 $dsn = "DBI:Proxy:key1=val1; ... ;keyN=valN;dsn=valDSN";
64 In other words, it is a collection of key/value pairs. The following
66 keys are recognized:
67 hostname
69 port
70 Hostname and port of the Proxy server; these keys must be present,
71 no defaults. Example:
72 hostname=alpha;port=3334
74 dsn The value of this attribute will be used as a dsn name by the Proxy
76 server. Thus it must have the format "DBI:driver:...", in particu‐
77 lar it will contain colons. The dsn value may contain semicolons,
78 hence this key *must* be the last and it's value will be the com‐
79 plete remaining part of the dsn. Example:
80 dsn=DBI:ODBC:mydb
82 cipher
84 key
85 usercipher
86 userkey
87 By using these fields you can enable encryption. If you set, for
88 example,
89 cipher=$class;key=$key
91 (note the semicolon) then DBD::Proxy will create a new cipher
93 object by executing
94 $cipherRef = $class->new(pack("H*", $key));
96 and pass this object to the RPC::PlClient module when creating a
98 client. See RPC::PlClient. Example:
99 cipher=IDEA;key=97cd2375efa329aceef2098babdc9721
101 The usercipher/userkey attributes allow you to use two phase
103 encryption: The cipher/key encryption will be used in the login and
104 authorisation phase. Once the client is authorised, he will change
105 to usercipher/userkey encryption. Thus the cipher/key pair is a
106 host based secret, typically less secure than the userci‐
107 pher/userkey secret and readable by anyone. The usercipher/userkey
108 secret is your private secret.
109 Of course encryption requires an appropriately configured server.
111 See <DBD::ProxyServer/CONFIGURATION FILE>.
112 debug
114 Turn on debugging mode
115 stderr
117 This attribute will set the corresponding attribute of the
118 RPC::PlClient object, thus logging will not use syslog(), but redi‐
119 rected to stderr. This is the default under Windows.
120 stderr=1
122 logfile
124 Similar to the stderr attribute, but output will be redirected to
125 the given file.
126 logfile=/dev/null
128 RowCacheSize
130 The DBD::Proxy driver supports this attribute (which is DBI stan‐
131 dard, as of DBI 1.02). It's used to reduce network round-trips by
132 fetching multiple rows in one go. The current default value is 20,
133 but this may change.
134 proxy_no_finish
136 This attribute can be used to reduce network traffic: If the appli‐
137 cation is calling $sth->finish() then the proxy tells the server to
138 finish the remote statement handle. Of course this slows down
139 things quite a lot, but is prefectly good for reducing memory usage
140 with persistent connections.
141 However, if you set the proxy_no_finish attribute to a TRUE value,
143 either in the database handle or in the statement handle, then fin‐
144 ish() calls will be supressed. This is what you want, for example,
145 in small and fast CGI applications.
146 proxy_quote
148 This attribute can be used to reduce network traffic: By default
149 calls to $dbh->quote() are passed to the remote driver. Of course
150 this slows down things quite a lot, but is the safest default be‐
151 haviour.
152 However, if you set the proxy_quote attribute to the value
154 '"local"' either in the database handle or in the statement handle,
155 and the call to quote has only one parameter, then the local
156 default DBI quote method will be used (which will be faster but may
157 be wrong).
158
160 Unproxied method calls
161 If a method isn't being proxied, try declaring a stub sub in the appro‐
163 priate package (DBD::Proxy::db for a dbh method, and DBD::Proxy::st for
164 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
183 refs and not simple strings or integers. For example, with DBD::CSV,
184 you would like to write something like
185 $dbh->{"csv_tables"}->{"passwd"} =
187 { "sep_char" => ":", "eol" => "\n";
188 The above example would advice the CSV driver to assume the file
190 "passwd" to be in the format of the /etc/passwd file: Colons as separa‐
191 tors and a line feed without carriage return as line terminator.
192 Surprisingly this example doesn't work with the proxy driver. To under‐
194 stand the reasons, you should consider the following: The Perl compiler
195 is executing the above example in two steps:
196 1 The first step is fetching the value of the key "csv_tables" in the
198 handle $dbh. The value returned is complex, a hash ref.
199 2 The second step is storing some value (the right hand side of the
201 assignment) as the key "passwd" in the hash ref from step 1.
202 This becomes a little bit clearer, if we rewrite the above code:
204 $tables = $dbh->{"csv_tables"};
206 $tables->{"passwd"} = { "sep_char" => ":", "eol" => "\n";
207 While the examples work fine without the proxy, the fail due to a sub‐
209 tile difference in step 1: By DBI magic, the hash ref
210 $dbh->{'csv_tables'} is returned from the server to the client. The
211 client creates a local copy. This local copy is the result of step 1.
212 In other words, step 2 modifies a local copy of the hash ref, but not
213 the server's hash ref.
214 The workaround is storing the modified local copy back to the server:
216 $tables = $dbh->{"csv_tables"};
218 $tables->{"passwd"} = { "sep_char" => ":", "eol" => "\n";
219 $dbh->{"csv_tables"} = $tables;
220
222 This module is Copyright (c) 1997, 1998
223 Jochen Wiedmann
225 Am Eisteich 9
226 72555 Metzingen
227 Germany
228 Email: joe@ispsoft.de
230 Phone: +49 7123 14887
231 The DBD::Proxy module is free software; you can redistribute it and/or
233 modify it under the same terms as Perl itself. In particular permission
234 is granted to Tim Bunce for distributing this as a part of the DBI.
235
237 DBI, RPC::PlClient, Storable
238perl v5.8.8 2006-02-07 DBD::Proxy(3)