.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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 "DBIx::Class::Schema::Config 3pm" .TH DBIx::Class::Schema::Config 3pm "2020-05-07" "perl v5.30.0" "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" DBIx::Class::Schema::Config \- Credential Management for DBIx::Class .SH "DESCRIPTION" .IX Header "DESCRIPTION" DBIx::Class::Schema::Config is a subclass of DBIx::Class::Schema that allows the loading of credentials & configuration from a file. The actual code itself would only need to know about the name used in the configuration file. This aims to make it simpler for operations teams to manage database credentials. .PP A simple tutorial that compliments this documentation and explains converting an existing DBIx::Class Schema to use this software to manage credentials can be found at .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 6 \& /etc/dbic.yaml \& MY_DATABASE: \& dsn: "dbi:Pg:host=localhost;database=blog" \& user: "TheDoctor" \& password: "dnoPydoleM" \& TraceLevel: 1 \& \& package My::Schema \& use warnings; \& use strict; \& \& use base \*(AqDBIx::Class::Schema::Config\*(Aq; \& _\|_PACKAGE_\|_\->load_namespaces; \& \& package My::Code; \& use warnings; \& use strict; \& use My::Schema; \& \& my $schema = My::Schema\->connect(\*(AqMY_DATABASE\*(Aq); \& \& # arbitrary config access from anywhere in your $app \& my $level = My::Schema\->config\->{TraceLevel}; .Ve .SH "CONFIG FILES" .IX Header "CONFIG FILES" This module will load the files in the following order if they exist: .IP "\(bu" 4 \&\f(CW$ENV{DBIX_CONFIG_DIR}\fR . '/dbic', .Sp \&\f(CW$ENV{DBIX_CONFIG_DIR}\fR can be configured at run-time, for instance: .Sp .Vb 1 \& DBIX_CONFIG_DIR="/var/local/" ./my_program.pl .Ve .IP "\(bu" 4 \&./dbic.* .IP "\(bu" 4 ~/.dbic.* .IP "\(bu" 4 /etc/dbic.* .PP The files should have an extension that Config::Any recognizes, for example /etc/dbic.\fByaml\fR. .PP \&\s-1NOTE:\s0 The first available credential will be used. Therefore \fI\s-1DATABASE\s0\fR in ~/.dbic.yaml will only be looked at if it was not found in ./dbic.yaml. If there are duplicates in one file (such that \s-1DATABASE\s0 is listed twice in ~/.dbic.yaml,) the first configuration will be used. .SH "CHANGE CONFIG PATH" .IX Header "CHANGE CONFIG PATH" Use \f(CW\*(C`_\|_PACKAGE_\|_\->config_paths([( \*(Aq/file/stub\*(Aq, \*(Aq/var/www/etc/dbic\*(Aq)]);\*(C'\fR to change the paths that are searched. For example: .PP .Vb 3 \& package My::Schema \& use warnings; \& use strict; \& \& use base \*(AqDBIx::Class::Schema::Config\*(Aq; \& _\|_PACKAGE_\|_\->config_paths([( \*(Aq/var/www/secret/dbic\*(Aq, \*(Aq/opt/database\*(Aq )]); .Ve .PP The above code would have \fI/var/www/secret/dbic.*\fR and \fI/opt/database.*\fR searched, in that order. As above, the first credentials found would be used. This will replace the files originally searched for, not add to them. .SH "USE SPECIFIC CONFIG FILES" .IX Header "USE SPECIFIC CONFIG FILES" If you would rather explicitly state the configuration files you want loaded, you can use the class accessor \f(CW\*(C`config_files\*(C'\fR instead. .PP .Vb 3 \& package My::Schema \& use warnings; \& use strict; \& \& use base \*(AqDBIx::Class::Schema::Config\*(Aq; \& _\|_PACKAGE_\|_\->config_files([( \*(Aq/var/www/secret/dbic.yaml\*(Aq, \*(Aq/opt/database.yaml\*(Aq )]); .Ve .PP This will check the files, \f(CW\*(C`/var/www/secret/dbic.yaml\*(C'\fR, and \f(CW\*(C`/opt/database.yaml\*(C'\fR in the same way as \f(CW\*(C`config_paths\*(C'\fR, however it will only check the specific files, instead of checking for each extension that Config::Any supports. You \s-1MUST\s0 use the extension that corresponds to the file type you are loading. See Config::Any for information on supported file types and extension mapping. .SH "ACCESSING THE CONFIG FILE" .IX Header "ACCESSING THE CONFIG FILE" The config file is stored via the \f(CW\*(C`_\|_PACKAGE_\|_\->config\*(C'\fR accessor, which can be called as both a class and instance method. .SH "OVERRIDING" .IX Header "OVERRIDING" The \s-1API\s0 has been designed to be simple to override if you have additional needs in loading \s-1DBIC\s0 configurations. .SS "Overriding Connection Configuration" .IX Subsection "Overriding Connection Configuration" Simple cases where one wants to replace specific configuration tokens can be given as extra parameters in the \->connect call. .PP For example, suppose we have the database \s-1MY_DATABASE\s0 from above: .PP .Vb 5 \& MY_DATABASE: \& dsn: "dbi:Pg:host=localhost;database=blog" \& user: "TheDoctor" \& password: "dnoPydoleM" \& TraceLevel: 1 .Ve .PP If you’d like to replace the username with “Eccleston” and we’d like to turn PrintError off. .PP The following connect line would achieve this: .PP .Vb 1 \& $Schema\->connect(“MY_DATABASE”, “Eccleston”, undef, { PrintError => 0 } ); .Ve .PP The name of the connection to load from the configuration file is still given as the first argument, while other arguments may be given exactly as you would for any other call to \f(CW\*(C`connect\*(C'\fR. .PP Historical Note: This class accepts numerous ways to connect to \s-1DBIC\s0 that would otherwise not be valid. These connection methods are discouraged but tested for and kept for compatibility with earlier versions. For valid ways of connecting to \s-1DBIC\s0 please see .SS "filter_loaded_credentials" .IX Subsection "filter_loaded_credentials" Override this function if you want to change the loaded credentials before they are passed to \s-1DBIC.\s0 This is useful for use-cases that include decrypting encrypted passwords or making programmatic changes to the configuration before using it. .PP .Vb 5 \& sub filter_loaded_credentials { \& my ( $class, $loaded_credentials, $connect_args ) = @_; \& ... \& return $loaded_credentials; \& } .Ve .PP \&\f(CW$loaded_credentials\fR is the structure after it has been loaded from the configuration file. In this case, \f(CW\*(C`$loaded_credentials\->{user}\*(C'\fR eq \&\fBWalterWhite\fR and \f(CW\*(C`$loaded_credentials\->{dsn}\*(C'\fR eq \&\fBDBI:mysql:database=students;host=%s;port=3306\fR. .PP \&\f(CW$connect_args\fR is the structure originally passed on \f(CW\*(C`\->connect()\*(C'\fR after it has been turned into a hash. For instance, \&\f(CW\*(C`\->connect(\*(AqDATABASE\*(Aq, \*(AqUSERNAME\*(Aq)\*(C'\fR will result in \&\f(CW\*(C`$connect_args\->{dsn}\*(C'\fR eq \fB\s-1DATABASE\s0\fR and \f(CW\*(C`$connect_args\->{user}\*(C'\fR eq \fB\s-1USERNAME\s0\fR. .PP Additional parameters can be added by appending a hashref, to the connection call, as an example, \f(CW\*(C`\->connect( \*(AqCONFIG\*(Aq, { hostname => "db.foo.com" } );\*(C'\fR will give \f(CW$connect_args\fR a structure like \f(CW\*(C`{ dsn => \*(AqCONFIG\*(Aq, hostname => "db.foo.com" }\*(C'\fR. .PP For instance, if you want to use hostnames when you make the initial connection to \s-1DBIC\s0 and are using the configuration primarily for usernames, passwords and other configuration data, you can create a config like the following: .PP .Vb 4 \& DATABASE: \& dsn: "DBI:mysql:database=students;host=%s;port=3306" \& user: "WalterWhite" \& password: "relykS" .Ve .PP In your Schema class, you could include the following: .PP .Vb 4 \& package My::Schema \& use warnings; \& use strict; \& use base \*(AqDBIx::Class::Schema::Config\*(Aq; \& \& sub filter_loaded_credentials { \& my ( $class, $loaded_credentials, $connect_args ) = @_; \& if ( $loaded_credentials\->{dsn} =~ /\e%s/ ) { \& $loaded_credentials\->{dsn} = sprintf( $loaded_credentials\->{dsn}, \& $connect_args\->{hostname}); \& } \& } \& \& _\|_PACKAGE_\|_\->load_classes; \& 1; .Ve .PP Then the connection could be done with \&\f(CW\*(C`$Schema\->connect(\*(AqDATABASE\*(Aq, { hostname =\*(C'\fR 'my.hostname.com' });> .PP See \*(L"load_credentials\*(R" for more complex changes that require changing how the configuration itself is loaded. .SS "load_credentials" .IX Subsection "load_credentials" Override this function to change the way that DBIx::Class::Schema::Config loads credentials. The function takes the class name, as well as a hashref. .PP If you take the route of having \f(CW\*(C`\->connect(\*(AqDATABASE\*(Aq)\*(C'\fR used as a key for whatever configuration you are loading, \fI\s-1DATABASE\s0\fR would be \&\f(CW\*(C`$config\->{dsn}\*(C'\fR .PP .Vb 8 \& Some::Schema\->connect( \& "SomeTarget", \& "Yuri", \& "Yawny", \& { \& TraceLevel => 1 \& } \& ); .Ve .PP Would result in the following data structure as \f(CW$config\fR in \&\f(CW\*(C`load_credentials($class, $config)\*(C'\fR: .PP .Vb 6 \& { \& dsn => "SomeTarget", \& user => "Yuri", \& password => "Yawny", \& TraceLevel => 1, \& } .Ve .PP Currently, load_credentials will \s-1NOT\s0 be called if the first argument to \&\f(CW\*(C`\->connect()\*(C'\fR looks like a valid \s-1DSN.\s0 This is determined by match the \s-1DSN\s0 with \f(CW\*(C`/^dbi:/i\*(C'\fR. .PP The function should return the same structure. For instance: .PP .Vb 6 \& package My::Schema \& use warnings; \& use strict; \& use base \*(AqDBIx::Class::Schema::Config\*(Aq; \& use LWP::Simple; \& use JSON \& \& # Load credentials from internal web server. \& sub load_credentials { \& my ( $class, $config ) = @_; \& \& return decode_json( \& get( "http://someserver.com/v1.0/database?key=somesecret&db=" . \& $config\->{dsn} )); \& } \& \& _\|_PACKAGE_\|_\->load_classes; .Ve .SH "AUTHOR" .IX Header "AUTHOR" Kaitlyn Parkhurst (SymKat) \fI\fR ( Blog: ) .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Matt S. Trout (mst) \fI\fR .IP "\(bu" 4 Peter Rabbitson (ribasushi) \fI\fR .IP "\(bu" 4 Christian Walde (Mihtaldu) \fI\fR .IP "\(bu" 4 Dagfinn Ilmari Mannsåker (ilmari) \fI\fR .IP "\(bu" 4 Matthew Phillips (mattp) \fI\fR .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This library is free software and may be distributed under the same terms as perl itself. .SH "AVAILABILITY" .IX Header "AVAILABILITY" The latest version of this software is available at