--- name: "URI::db" section: "3pm" platform: "linux" package: "liburi-db-perl" version: "0.23-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/URI::db" --- # URI::db(3pm) Database URIs ## Name URI::db - Database URIs ## 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 \ and PostgreSQL URIs \, though they're a bit more formal. The specification for their format is documented in *README.md* \. **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. *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: - • `"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://user@localhost"` - • `"db:pg://user:secret@/mydb"` - • `"pg:///mydb"` - • `"pg://other@localhost/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 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->password ); ``` 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. If the URI 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 valid DBI DSN. Some examples: ``` | URI | DSN | |--------------------------------------+--------------------------------------------------| | db:pg:try | dbi:Pg:dbname=try | | db:mysql://localhost:33/foo | dbi:MariaDB: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 \. Feel free to fork and contribute! Please file bug reports via GitHub Issues \ or by sending mail to bug-URI-db@rt.cpan.org \. ## Author David E. Wheeler \ ## Copyright and License Copyright (c) 2013-2023 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.