Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
URI::db(3)	      User Contributed Perl Documentation	    URI::db(3)

       URI::db - Database URIs

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

       This class provides support for database	URIs. They're inspired by JDBC
       and PostgreSQL URIs <
       connect.html#LIBPQ-CONNSTRING>, though they're a	bit more formal. The
       specification for their format is documented in

       Warning:	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.


       A database URI is made up of these parts:


	   The literal string "db" is the scheme that defines a	database URI.
	   Optional for	well-known engines.

	   A string identifying	the database engine.

	   The user name to use	when connecting	to the database.

	   The password	to use when connecting to the database.

	   The host address to connect to.

	   The network port to connect to.

	   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

	   A URI-standard GET query string representing	additional parameters
	   to be passed	to the engine.

	   Identifies a	database part, such as a table or view.


       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://"

       The following differences exist compared	to the "URI" class interface:

   Class Method

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


	 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.


	 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.


	 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.


	 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".


	 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.


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

       Gets or sets the	host to	connect	to.


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

       Gets or sets the	port to	connect	to.


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

       Gets or sets the	user name.


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

       Gets or sets the	password.


       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

	 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".


	 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;


	 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->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://	|;Database=pubs;Driver=MSSQL |


	 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.


	 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


	 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.


	 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.

       This module is stored in	an open	GitHub repository
       <>. Feel	free to	fork and contribute!

       Please file bug reports via GitHub Issues
       <> or by sending mail to <>.

       David E.	Wheeler	<>

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.

perl v5.32.0			  2020-08-09			    URI::db(3)

Name | Synopsis | Description | Interface | Support | Author | Copyright and License

Want to link to this manual page? Use this URL:

home | help