1URI::db(3) User Contributed Perl Documentation URI::db(3)
2
3
4
6 URI::db - Database URIs
7
9 use URI;
10 my $db_uri = URI->new('db:pg://user@localhost');
11 my $pg_uri = URI->new('postgres://example.com/template1');
12 my $sl_uri = URI->new('sqlite:/var/db/widgets.db');
13
15 This class provides support for database URIs. They're inspired by JDBC
16 URIs
17 <http://docs.oracle.com/cd/B14117_01/java.101/b10979/urls.htm#BEIJFHHB>
18 and PostgreSQL URIs <http://www.postgresql.org/docs/9.3/static/libpq-
19 connect.html#LIBPQ-CONNSTRING>, though they're a bit more formal. The
20 specification for their format is documented in README.md
21 <https:/github.com/theory/db-uri/>.
22
23 Warning: This is an alpha release. I will do my best to preserve
24 functionality going forward, especially as Sqitch uses this module.
25 However, as the database URI specification moves forward, changes may
26 require backwards-incompatible changes. Caveat Hackor.
27
28 Format
29
30 A database URI is made up of these parts:
31
32 db:engine:[//[user[:password]@][host][:port]/][dbname][?params][#fragment]
33
34 "db"
35 The literal string "db" is the scheme that defines a database URI.
36 Optional for well-known engines.
37
38 "engine"
39 A string identifying the database engine.
40
41 "user"
42 The user name to use when connecting to the database.
43
44 "password"
45 The password to use when connecting to the database.
46
47 "host"
48 The host address to connect to.
49
50 "port"
51 The network port to connect to.
52
53 "dbname"
54 The name of the database. For some engines, this will be a file
55 name, in which case it may be a complete or local path, as
56 appropriate.
57
58 "params"
59 A URI-standard GET query string representing additional parameters
60 to be passed to the engine.
61
62 "fragment"
63 Identifies a database part, such as a table or view.
64
65 Examples
66
67 Some examples:
68
69 · "db:sqlite"
70
71 · "db:sqlite:dbname"
72
73 · "db:sqlite:/path/to/some.db"
74
75 · "sqlite:../relative.db"
76
77 · "db:firebird://localhost/%2Fpath/to/some.db"
78
79 · "db:firebird://localhost//path/to/some.db"
80
81 · "firebird://localhost/relative.db"
82
83 · "db:pg://"
84
85 · "db:pg://localhost"
86
87 · "db:pg://localhost:5433"
88
89 · "db:pg://localhost/mydb"
90
91 · "db:pg://user@localhost"
92
93 · "db:pg://user:secret@/mydb"
94
95 · "pg:///mydb"
96
97 · "pg://other@localhost/otherdb?connect_timeout=10&application_name=myapp"
98
99 · "db://localhost/mydb"
100
101 · "db:unknown://example.com/mydb"
102
104 The following differences exist compared to the "URI" class interface:
105
106 Class Method
107 "default_port"
108
109 Returns the default port for the engine. This is a class method value
110 defined by each recognized URI engine.
111
112 Constructors
113 "new"
114
115 my $uri = URI::db->new($string);
116 my $uri = URI::db->new($string, $base);
117
118 Always returns a URI::db object. $base may be another URI object or
119 string. Unlike in URI's "new()", the scheme will always be applied to
120 the URI if it does not already have one.
121
122 Accessors
123 "scheme"
124
125 my $scheme = $uri->scheme;
126 $uri->scheme( $new_scheme );
127
128 Gets or sets the scheme part of the URI. For "db:" URIs, the scheme
129 cannot be changed to any value other than "db" (or any case variation
130 thereof). For non-"db:" URIs, the scheme may be changed to any value,
131 though the URI object may no longer be a database URI.
132
133 "engine"
134
135 my $engine = $uri->engine;
136 $uri->engine( $new_engine );
137
138 Gets or sets the engine part of the URI, which may be any valid URI
139 scheme value, though recognized engines provide additional context,
140 such as the "default_port()" and a driver-specific "dbi_dsn()".
141
142 If called with an argument, it updates the engine, possibly changing
143 the class of the URI, and returns the old engine value.
144
145 "canonical_engine"
146
147 my $canonical_engine = $uri->canonical_engine;
148
149 Returns the canonical engine. A number of engine names are aliases for
150 other engines. This method will return the non-aliased engine name. For
151 example, the "postgres" engine will return the canonical engine "pg",
152 the "sqlite3" returns the canonical engine "sqlite", and "maria"
153 returns the canonical engine "mysql".
154
155 "dbname"
156
157 my $dbname = $uri->dbname;
158 $uri->dbname( $new_dbname );
159
160 Gets or sets the name of the database. If called with an argument, the
161 path will also be updated.
162
163 "host"
164
165 my $host = $uri->host;
166 $uri->host( $new_host );
167
168 Gets or sets the host to connect to.
169
170 "port"
171
172 my $port = $uri->port;
173 $uri->port( $new_port );
174
175 Gets or sets the port to connect to.
176
177 "user"
178
179 my $user = $uri->user;
180 $uri->user( $new_user );
181
182 Gets or sets the user name.
183
184 "password"
185
186 my $password = $uri->password;
187 $uri->password( $new_password );
188
189 Gets or sets the password.
190
191 "uri"
192
193 Returns the underlying engine URI. For URIs starting with "db:", this
194 will be the URI that follows. For database URIs without "db:", the URI
195 itself will be returned.
196
197 Instance Methods
198 "has_recognized_engine"
199
200 my $has_recognized_engine = $uri->has_recognized_engine;
201
202 Returns true if the engine is recognized by URI::db, and false if it is
203 not. A recognized engine is simply one that inherits from "URI::_db".
204
205 "query_params"
206
207 my @params = $uri->query_params;
208
209 Returns a list of key/value pairs representing all query parameters.
210 Parameters specified more than once will be returned more than once, so
211 avoid assigning to a hash. If you want a hash, use URI::QueryParam's
212 "query_from_hash()", where duplicate keys lead to an array of values
213 for that key:
214
215 use URI::QueryParam;
216 my $params = $uri->query_form_hash;
217
218 "dbi_driver"
219
220 if ( my $driver = $uri->dbi_driver ) {
221 eval "require DBD::$driver" or die;
222 }
223
224 Returns a string representing the DBI driver name for the database
225 engine, if one is known. Returns "undef" if no driver is known.
226
227 "dbi_dsn"
228
229 DBI->connect( $uri->dbi_dsn, $uri->user, $uri->password );
230
231 Returns a DBI DSN appropriate for use in a call to "DBI->connect". The
232 attributes will usually be pulled from the URI host name, port, and
233 database name, as well as the query parameters. If no driver is known
234 for the URI, the "dbi:$driver:" part of the DSN will be omitted, in
235 which case you can use the $DBI_DRIVER environment variable to identify
236 an appropriate driver. If the URI supports multiple drivers, pass the
237 name of the one you want to "dbi_dsn()". Currently only URI::myssql
238 supports alternate drivers, ADO, ODBC, or Sybase. Otherwise, each
239 database URI does its best to create a valid DBI DSN. Some examples:
240
241 | URI | DSN |
242 |--------------------------------------+--------------------------------------------------|
243 | db:pg:try | dbi:Pg:dbname=try |
244 | db:mysql://localhost:33/foo | dbi:mysql:host=localhost;port=33;database=foo |
245 | db:db2://localhost:33/foo | dbi:DB2:HOSTNAME=localhost;PORT=33;DATABASE=foo |
246 | db:vertica:dbadmin | dbi:ODBC:DSN=dbadmin |
247 | db:mssql://foo.com/pubs?Driver=MSSQL | dbi:ODBC:Host=foo.com;Database=pubs;Driver=MSSQL |
248
249 "dbi_params"
250
251 my @params = $uri->dbi_params;
252
253 Returns a list of key/value pairs used as parameters in the DBI DSN,
254 including query parameters. Parameters specified more than once will be
255 returned more than once, so avoid assigning to a hash.
256
257 "abs"
258
259 my $abs = $uri->abs( $base_uri );
260
261 For "db:" URIs, simply returns the URI::db object itself. For Non-"db:"
262 URIs, the behavior is the same as for URI including respect for
263 $URI::ABS_ALLOW_RELATIVE_SCHEME.
264
265 "rel"
266
267 my $rel = $uri->rel( $base_uri );
268
269 For "db:" URIs, simply returns the URI::db object itself. For Non-"db:"
270 URIs, the behavior is the same as for URI.
271
272 "canonical"
273
274 my $canonical_uri = $uri->canonical;
275
276 Returns a normalized version of the URI. This behavior is the same for
277 other URIs, except that the engine will be replaced with the value of
278 "canonical_engine" if it is not already the canonical engine.
279
281 This module is stored in an open GitHub repository
282 <https://github.com/theory/uri-db/>. Feel free to fork and contribute!
283
284 Please file bug reports via GitHub Issues
285 <https://github.com/theory/uri-db/issues/> or by sending mail to
286 bug-URI-db@rt.cpan.org <mailto:bug-URI-db@rt.cpan.org>.
287
289 David E. Wheeler <david@justatheory.com>
290
292 Copyright (c) 2013-2016 David E. Wheeler. Some Rights Reserved.
293
294 This module is free software; you can redistribute it and/or modify it
295 under the same terms as Perl itself.
296
297
298
299perl v5.30.1 2020-01-30 URI::db(3)