SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

MAN page from openSUSE Leap 15 perl-URI-db-0.19-lp150.7.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

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

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


 

Index

Name
Synopsis
Description
Interface
Class Method
Constructors
Accessors
Instance Methods
Support
Author
Copyright and License

This document was created byman2html,using the manual pages.