MAN page from openSUSE Leap 15 perl-URI-db-0.19-lp150.8.1.noarch.rpm

URI::db

Section: User Contributed Perl Documentation (3)
Updated: 2018-07-20
Index

Name

URI::db - Database URIs

Synopsis

  use URI;  my $db_uri = URI->new('db:pg://userAATTlocalhost');  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 byJDBC URIs <http://docs.oracle.com/cd/B14117_01/java.101/b10979/urls.htm#BEIJFHHB> andPostgreSQL 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 isdocumented in README.md <https:/github.com/theory/db-uri/>.

Warning: This is an alpha release. I will do my best to preservefunctionality going forward, especially as Sqitch uses thismodule. However, as the database URI specification moves forward, changesmay 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. Optionalfor 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 whichcase it may be a complete or local path, as appropriate.
params: A URI-standard GET query string representing additional parameters to bepassed to the engine.
fragment: Identifies a database part, such as a table or view.

Examples

Some examples:

*: "db:sqlite"
*: "db:sqlite:dbname"
*: "db:sqlite:/path/to/some.db"
*: "sqlite:../relative.db"
*: "db:firebird://localhost/%2Fpath/to/some.db"
*: "db:firebird://localhost//path/to/some.db"
*: "firebird://localhost/relative.db"
*: "db:pg://"
*: "db:pg://localhost"
*: "db:pg://localhost:5433"
*: "db:pg://localhost/mydb"
*: "db:pg://userAATTlocalhost"
*: "db:pg://user:secret@/mydb"
*: "pg:///mydb"
*: "pg://otherAATTlocalhost/otherdb?connect_timeout=10&application_name=myapp"
*: "db://localhost/mydb"
*: "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 definedby 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 ifit 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 bechanged to any value other than ``db'' (or any case variation thereof). Fornon-"db:" URIs, the scheme may be changed to any value, though the URI objectmay 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 schemevalue, 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 classof 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 otherengines. 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 canonicalengine "mysql".

"dbname"

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

Gets or sets the name of the database. If called with an argument, the pathwill 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 bethe URI that follows. For database URIs without "db:", the URI itself will bereturned.

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. Arecognized 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 avoidassigning 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 thatkey:

  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->password );

Returns a DBI DSN appropriate for use in a call to "DBI->connect". Theattributes will usually be pulled from the URI host name, port, and databasename, 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. If theURI supports multiple drivers, pass the name of the one you want to"dbi_dsn()". Currently only URI::myssql supports alternate drivers, ADO,ODBC, or Sybase. Otherwise, each database URI does its best to create a validDBI 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 bereturned 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 otherURIs, 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 openGitHub repository <https://github.com/theory/uri-db/>. Feel free to fork andcontribute!

Please file bug reports viaGitHub Issues <https://github.com/theory/uri-db/issues/> or by sending mail tobug-URI-db@rt.cpan.org <mailto:bug-URI-dbAATTrt.cpan.org>.

Author

David E. Wheeler <davidAATTjustatheory.com>

Copyright and License

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

Support

Author

Copyright and License

This document was created byman2html,using the manual pages.