GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  URI::DB (3)

.ds Aq ’

Name

URI::db - Database URIs

CONTENTS

Synopsis



  use URI;
  my $db_uri = URI->new(db:pg://user@localhost);
  my $pg_uri = URI->new(postgres://example.com/template1);
  my $sl_uri = URI->new(sqlite:/var/db/widgets.db);



Description

This class provides support for database URIs. They’re inspired by JDBC URIs <http://docs.oracle.com/cd/B14117_01/java.101/b10979/urls.htm#BEIJFHHB> and PostgreSQL URIs <http://www.postgresql.org/docs/9.3/static/libpq-connect.html#LIBPQ-CONNSTRING>, though they’re a bit more formal. The specification for their format is documented in README.md <https:/github.com/theory/db-uri/>.

<B>Warning:B> This is an alpha release. I will do my best to preserve functionality going forward, especially as Sqitch uses this module. However, as the database URI specification moves forward, changes may require backwards-incompatible changes. Caveat Hackor.

Format

A database URI is made up of these parts:



  db:engine:[//[user[:password]@][host][:port]/][dbname][?params][#fragment]



db The literal string db is the scheme that defines a database URI. Optional for well-known engines.
engine A string identifying the database engine.
user The user name to use when connecting to the database.
password The password to use when connecting to the database.
host The host address to connect to.
port The network port to connect to.
dbname The name of the database. For some engines, this will be a file name, in which case it may be a complete or local path, as appropriate.
params A URI-standard GET query string representing additional parameters to be passed to the engine.
fragment Identifies a database part, such as a table or view.
Examples

Some examples:
o db:sqlite
o db:sqlite:dbname
o db:sqlite:/path/to/some.db
o sqlite:../relative.db
o db:firebird://localhost/%2Fpath/to/some.db
o db:firebird://localhost//path/to/some.db
o firebird://localhost/relative.db
o db:pg://
o db:pg://localhost
o db:pg://localhost:5433
o db:pg://localhost/mydb
o db:pg://user@localhost
o db:pg://user:secret@/mydb
o pg:///mydb
o pg://other@localhost/otherdb?connect_timeout=10&application_name=myapp
o db://localhost/mydb
o db:unknown://example.com/mydb

Interface

The following differences exist compared to the URI class interface:

    Class Method

default_port

Returns the default port for the engine. This is a class method value defined by each recognized URI engine.

    Constructors

new



  my $uri = URI::db->new($string);
  my $uri = URI::db->new($string, $base);



Always returns a URI::db object. $base may be another URI object or string. Unlike in URI’s new(), the scheme will always be applied to the URI if it does not already have one.

    Accessors

scheme



  my $scheme = $uri->scheme;
  $uri->scheme( $new_scheme );



Gets or sets the scheme part of the URI. For db: URIs, the scheme cannot be changed to any value other than db (or any case variation thereof). For non-db: URIs, the scheme may be changed to any value, though the URI object may no longer be a database URI.

engine



  my $engine = $uri->engine;
  $uri->engine( $new_engine );



Gets or sets the engine part of the URI, which may be any valid URI scheme value, though recognized engines provide additional context, such as the default_port() and a driver-specific dbi_dsn().

If called with an argument, it updates the engine, possibly changing the class of the URI, and returns the old engine value.

canonical_engine



  my $canonical_engine = $uri->canonical_engine;



Returns the canonical engine. A number of engine names are aliases for other engines. This method will return the non-aliased engine name. For example, the postgres engine will return the canonical engine pg, the sqlite3 returns the canonical engine sqlite, and maria returns the canonical engine mysql.

dbname



  my $dbname = $uri->dbname;
  $uri->dbname( $new_dbname );



Gets or sets the name of the database. If called with an argument, the path will also be updated.

host



  my $host = $uri->host;
  $uri->host( $new_host );



Gets or sets the host to connect to.

port



  my $port = $uri->port;
  $uri->port( $new_port );



Gets or sets the port to connect to.

user



  my $user = $uri->user;
  $uri->user( $new_user );



Gets or sets the user name.

password



  my $password = $uri->password;
  $uri->password( $new_password );



Gets or sets the password.

uri

Returns the underlying engine URI. For URIs starting with db:, this will be the URI that follows. For database URIs without db:, the URI itself will be returned.

    Instance Methods

has_recognized_engine



  my $has_recognized_engine = $uri->has_recognized_engine;



Returns true if the engine is recognized by URI::db, and false if it is not. A recognized engine is simply one that inherits from URI::_db.

query_params



  my @params = $uri->query_params;



Returns a list of key/value pairs representing all query parameters. Parameters specified more than once will be returned more than once, so avoid assigning to a hash. If you want a hash, use URI::QueryParam’s query_from_hash(), where duplicate keys lead to an array of values for that key:



  use URI::QueryParam;
  my $params = $uri->query_form_hash;



dbi_driver



  if ( my $driver = $uri->dbi_driver ) {
      eval "require DBD::$driver" or die;
  }



Returns a string representing the DBI driver name for the database engine, if one is known. Returns undef if no driver is known.

dbi_dsn



  DBI->connect( $uri->dbi_dsn, $uri->user, $uri->pass );



Returns a DBI DSN appropriate for use in a call to DBI->connect. The attributes will usually be pulled from the URI host name, port, and database name, as well as the query parameters. If no driver is known for the URI, the dbi:$driver: part of the DSN will be omitted, in which case you can use the $DBI_DRIVER environment variable to identify an appropriate driver. Otherwise, each database URI does its best to create a valid DBI DSN. Some examples:



  | URI                                  | DSN                                              |
  |--------------------------------------+--------------------------------------------------|
  | db:pg:try                            | dbi:Pg:dbname=try                                |
  | db:mysql://localhost:33/foo          | dbi:mysql:host=localhost;port=33;database=foo    |
  | db:db2://localhost:33/foo            | dbi:DB2:HOSTNAME=localhost;PORT=33;DATABASE=foo  |
  | db:vertica:dbadmin                   | dbi:ODBC:DSN=dbadmin                             |
  | db:mssql://foo.com/pubs?Driver=MSSQL | dbi:ODBC:Host=foo.com;Database=pubs;Driver=MSSQL |



dbi_params



  my @params = $uri->dbi_params;



Returns a list of key/value pairs used as parameters in the DBI DSN, including query parameters. Parameters specified more than once will be returned more than once, so avoid assigning to a hash.

abs



  my $abs = $uri->abs( $base_uri );



For db: URIs, simply returns the URI::db object itself. For Non-db: URIs, the behavior is the same as for URI including respect for $URI::ABS_ALLOW_RELATIVE_SCHEME.

rel



  my $rel = $uri->rel( $base_uri );



For db: URIs, simply returns the URI::db object itself. For Non-db: URIs, the behavior is the same as for URI.

canonical



  my $canonical_uri = $uri->canonical;



Returns a normalized version of the URI. This behavior is the same for other URIs, except that the engine will be replaced with the value of canonical_engine if it is not already the canonical engine.

Support

This module is stored in an open GitHub repository <http://github.com/theory/uri-db/>. Feel free to fork and contribute!

Please file bug reports via GitHub Issues <http://github.com/theory/uri-db/issues/> or by sending mail to bug-URI-db@rt.cpan.org <mailto:bug-URI-db@rt.cpan.org>.

Author

David E. Wheeler <david@justatheory.com>

Copyright and License

Copyright (c) 2013 David E. Wheeler. Some Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 URI::DB (3) 2016-04-04

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.