.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "URI::db 3pm" .TH URI::db 3pm 2024-04-13 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH Name .IX Header "Name" URI::db \- Database URIs .SH Synopsis .IX Header "Synopsis" .Vb 4 \& use URI; \& my $db_uri = URI\->new(\*(Aqdb:pg://user@localhost\*(Aq); \& my $pg_uri = URI\->new(\*(Aqpostgres://example.com/template1\*(Aq); \& my $sl_uri = URI\->new(\*(Aqsqlite:/var/db/widgets.db\*(Aq); .Ve .SH Description .IX Header "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 \fIREADME.md\fR . .PP \&\fBWarning:\fR 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 \&\fImay\fR require backwards-incompatible changes. Caveat Hackor. .PP \fIFormat\fR .IX Subsection "Format" .PP A database URI is made up of these parts: .PP .Vb 1 \& db:engine:[//[user[:password]@][host][:port]/][dbname][?params][#fragment] .Ve .ie n .IP """db""" 4 .el .IP \f(CWdb\fR 4 .IX Item "db" The literal string \f(CW\*(C`db\*(C'\fR is the scheme that defines a database URI. Optional for well-known engines. .ie n .IP """engine""" 4 .el .IP \f(CWengine\fR 4 .IX Item "engine" A string identifying the database engine. .ie n .IP """user""" 4 .el .IP \f(CWuser\fR 4 .IX Item "user" The user name to use when connecting to the database. .ie n .IP """password""" 4 .el .IP \f(CWpassword\fR 4 .IX Item "password" The password to use when connecting to the database. .ie n .IP """host""" 4 .el .IP \f(CWhost\fR 4 .IX Item "host" The host address to connect to. .ie n .IP """port""" 4 .el .IP \f(CWport\fR 4 .IX Item "port" The network port to connect to. .ie n .IP """dbname""" 4 .el .IP \f(CWdbname\fR 4 .IX Item "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. .ie n .IP """params""" 4 .el .IP \f(CWparams\fR 4 .IX Item "params" A URI-standard GET query string representing additional parameters to be passed to the engine. .ie n .IP """fragment""" 4 .el .IP \f(CWfragment\fR 4 .IX Item "fragment" Identifies a database part, such as a table or view. .PP \fIExamples\fR .IX Subsection "Examples" .PP Some examples: .IP \(bu 4 \&\f(CW\*(C`db:sqlite\*(C'\fR .IP \(bu 4 \&\f(CW\*(C`db:sqlite:dbname\*(C'\fR .IP \(bu 4 \&\f(CW\*(C`db:sqlite:/path/to/some.db\*(C'\fR .IP \(bu 4 \&\f(CW\*(C`sqlite:../relative.db\*(C'\fR .IP \(bu 4 \&\f(CW\*(C`db:firebird://localhost/%2Fpath/to/some.db\*(C'\fR .IP \(bu 4 \&\f(CW\*(C`db:firebird://localhost//path/to/some.db\*(C'\fR .IP \(bu 4 \&\f(CW\*(C`firebird://localhost/relative.db\*(C'\fR .IP \(bu 4 \&\f(CW\*(C`db:pg://\*(C'\fR .IP \(bu 4 \&\f(CW\*(C`db:pg://localhost\*(C'\fR .IP \(bu 4 \&\f(CW\*(C`db:pg://localhost:5433\*(C'\fR .IP \(bu 4 \&\f(CW\*(C`db:pg://localhost/mydb\*(C'\fR .IP \(bu 4 \&\f(CW\*(C`db:pg://user@localhost\*(C'\fR .IP \(bu 4 \&\f(CW\*(C`db:pg://user:secret@/mydb\*(C'\fR .IP \(bu 4 \&\f(CW\*(C`pg:///mydb\*(C'\fR .IP \(bu 4 \&\f(CW\*(C`pg://other@localhost/otherdb?connect_timeout=10&application_name=myapp\*(C'\fR .IP \(bu 4 \&\f(CW\*(C`db://localhost/mydb\*(C'\fR .IP \(bu 4 \&\f(CW\*(C`db:unknown://example.com/mydb\*(C'\fR .SH Interface .IX Header "Interface" The following differences exist compared to the \f(CW\*(C`URI\*(C'\fR class interface: .SS "Class Method" .IX Subsection "Class Method" \fR\f(CI\*(C`default_port\*(C'\fR\fI\fR .IX Subsection "default_port" .PP Returns the default port for the engine. This is a class method value defined by each recognized URI engine. .SS Constructors .IX Subsection "Constructors" \fR\f(CI\*(C`new\*(C'\fR\fI\fR .IX Subsection "new" .PP .Vb 2 \& my $uri = URI::db\->new($string); \& my $uri = URI::db\->new($string, $base); .Ve .PP Always returns a URI::db object. \f(CW$base\fR may be another URI object or string. Unlike in URI's \f(CWnew()\fR, the scheme will always be applied to the URI if it does not already have one. .SS Accessors .IX Subsection "Accessors" \fR\f(CI\*(C`scheme\*(C'\fR\fI\fR .IX Subsection "scheme" .PP .Vb 2 \& my $scheme = $uri\->scheme; \& $uri\->scheme( $new_scheme ); .Ve .PP Gets or sets the scheme part of the URI. For \f(CW\*(C`db:\*(C'\fR URIs, the scheme cannot be changed to any value other than "db" (or any case variation thereof). For non\-\f(CW\*(C`db:\*(C'\fR URIs, the scheme may be changed to any value, though the URI object may no longer be a database URI. .PP \fR\f(CI\*(C`engine\*(C'\fR\fI\fR .IX Subsection "engine" .PP .Vb 2 \& my $engine = $uri\->engine; \& $uri\->engine( $new_engine ); .Ve .PP 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 \&\f(CWdefault_port()\fR and a driver-specific \f(CWdbi_dsn()\fR. .PP If called with an argument, it updates the engine, possibly changing the class of the URI, and returns the old engine value. .PP \fR\f(CI\*(C`canonical_engine\*(C'\fR\fI\fR .IX Subsection "canonical_engine" .PP .Vb 1 \& my $canonical_engine = $uri\->canonical_engine; .Ve .PP 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 \&\f(CW\*(C`postgres\*(C'\fR engine will return the canonical engine \f(CW\*(C`pg\*(C'\fR, the \f(CW\*(C`sqlite3\*(C'\fR returns the canonical engine \f(CW\*(C`sqlite\*(C'\fR, and \f(CW\*(C`maria\*(C'\fR returns the canonical engine \f(CW\*(C`mysql\*(C'\fR. .PP \fR\f(CI\*(C`dbname\*(C'\fR\fI\fR .IX Subsection "dbname" .PP .Vb 2 \& my $dbname = $uri\->dbname; \& $uri\->dbname( $new_dbname ); .Ve .PP Gets or sets the name of the database. If called with an argument, the path will also be updated. .PP \fR\f(CI\*(C`host\*(C'\fR\fI\fR .IX Subsection "host" .PP .Vb 2 \& my $host = $uri\->host; \& $uri\->host( $new_host ); .Ve .PP Gets or sets the host to connect to. .PP \fR\f(CI\*(C`port\*(C'\fR\fI\fR .IX Subsection "port" .PP .Vb 2 \& my $port = $uri\->port; \& $uri\->port( $new_port ); .Ve .PP Gets or sets the port to connect to. .PP \fR\f(CI\*(C`user\*(C'\fR\fI\fR .IX Subsection "user" .PP .Vb 2 \& my $user = $uri\->user; \& $uri\->user( $new_user ); .Ve .PP Gets or sets the user name. .PP \fR\f(CI\*(C`password\*(C'\fR\fI\fR .IX Subsection "password" .PP .Vb 2 \& my $password = $uri\->password; \& $uri\->password( $new_password ); .Ve .PP Gets or sets the password. .PP \fR\f(CI\*(C`uri\*(C'\fR\fI\fR .IX Subsection "uri" .PP Returns the underlying engine URI. For URIs starting with \f(CW\*(C`db:\*(C'\fR, this will be the URI that follows. For database URIs without \f(CW\*(C`db:\*(C'\fR, the URI itself will be returned. .SS "Instance Methods" .IX Subsection "Instance Methods" \fR\f(CI\*(C`has_recognized_engine\*(C'\fR\fI\fR .IX Subsection "has_recognized_engine" .PP .Vb 1 \& my $has_recognized_engine = $uri\->has_recognized_engine; .Ve .PP 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 \f(CW\*(C`URI::_db\*(C'\fR. .PP \fR\f(CI\*(C`query_params\*(C'\fR\fI\fR .IX Subsection "query_params" .PP .Vb 1 \& my @params = $uri\->query_params; .Ve .PP 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 \&\f(CWquery_from_hash()\fR, where duplicate keys lead to an array of values for that key: .PP .Vb 2 \& use URI::QueryParam; \& my $params = $uri\->query_form_hash; .Ve .PP \fR\f(CI\*(C`dbi_driver\*(C'\fR\fI\fR .IX Subsection "dbi_driver" .PP .Vb 3 \& if ( my $driver = $uri\->dbi_driver ) { \& eval "require DBD::$driver" or die; \& } .Ve .PP Returns a string representing the DBI driver name for the database engine, if one is known. Returns \f(CW\*(C`undef\*(C'\fR if no driver is known. .PP \fR\f(CI\*(C`dbi_dsn\*(C'\fR\fI\fR .IX Subsection "dbi_dsn" .PP .Vb 1 \& DBI\->connect( $uri\->dbi_dsn, $uri\->user, $uri\->password ); .Ve .PP Returns a DBI DSN appropriate for use in a call to \f(CW\*(C`DBI\->connect\*(C'\fR. 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 \&\f(CW\*(C`dbi:$driver:\*(C'\fR part of the DSN will be omitted, in which case you can use the \&\f(CW$DBI_DRIVER\fR environment variable to identify an appropriate driver. If the URI supports multiple drivers, pass the name of the one you want to \&\f(CWdbi_dsn()\fR. 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: .PP .Vb 7 \& | 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 | .Ve .PP \fR\f(CI\*(C`dbi_params\*(C'\fR\fI\fR .IX Subsection "dbi_params" .PP .Vb 1 \& my @params = $uri\->dbi_params; .Ve .PP 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. .PP \fR\f(CI\*(C`abs\*(C'\fR\fI\fR .IX Subsection "abs" .PP .Vb 1 \& my $abs = $uri\->abs( $base_uri ); .Ve .PP For \f(CW\*(C`db:\*(C'\fR URIs, simply returns the URI::db object itself. For Non\-\f(CW\*(C`db:\*(C'\fR URIs, the behavior is the same as for URI including respect for \&\f(CW$URI::ABS_ALLOW_RELATIVE_SCHEME\fR. .PP \fR\f(CI\*(C`rel\*(C'\fR\fI\fR .IX Subsection "rel" .PP .Vb 1 \& my $rel = $uri\->rel( $base_uri ); .Ve .PP For \f(CW\*(C`db:\*(C'\fR URIs, simply returns the URI::db object itself. For Non\-\f(CW\*(C`db:\*(C'\fR URIs, the behavior is the same as for URI. .PP \fR\f(CI\*(C`canonical\*(C'\fR\fI\fR .IX Subsection "canonical" .PP .Vb 1 \& my $canonical_uri = $uri\->canonical; .Ve .PP 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 \&\f(CW\*(C`canonical_engine\*(C'\fR if it is not already the canonical engine. .SH Support .IX Header "Support" This module is stored in an open GitHub repository . Feel free to fork and contribute! .PP Please file bug reports via GitHub Issues or by sending mail to bug\-URI\-db@rt.cpan.org . .SH Author .IX Header "Author" David E. Wheeler .SH "Copyright and License" .IX Header "Copyright and License" Copyright (c) 2013\-2023 David E. Wheeler. Some Rights Reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.