1URI::db(3)            User Contributed Perl Documentation           URI::db(3)
2
3
4

Name

6       URI::db - Database URIs
7

Synopsis

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

Description

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

Interface

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 for
213       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

Support

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

Author

289       David E. Wheeler <david@justatheory.com>
290

Copyright and License

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.36.0                      2023-01-20                        URI::db(3)