The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
PGObject-Util-PGConfig-0.02
River stage one • 2 direct dependents • 3 total dependents
++
/ PGObject::Util::PGConfig

NAME

PGObject::Util::PGConfig - Postgres Configuration Management

VERSION

Version 0.20

SYNOPSIS

    use PGObject::Util::PGConfig;

    my $config = PGObject::Util::PGConfig->new();
    # setting values in the internal store
    $config->set('statement_timeout', 3600); # set the desired state
    $config->set('datestyle', 'ISO');

    # session configuration management
    $config->list($dbh);
    $config->fetch($dbh, 'statement_timeout'); # get the session statement timeout
    # We can now sync with Pg for the dbh session
    $config->sync_session($dbh, qw(statement_timeout datestyle));

    # or we can get from a file
    $config->fromfile('path/to/file');
    # or from file contents
    $config->fromcontents($string);
    # and can return current state as file contents
    $config->filecontents();
    # or write to a file
    $config->tofile('path/to/new.conf');

DESCRIPTION

The current config module provides an abstraction around the PostgreSQL GUC (configuration system). This includes parsing config files (postgresql.conf, recovery.conf) and retrieve current settings from a database configuration.

The module does not depend on a database configuration so it can be used to aggregate configuration data from different sources.

Session update guarantees that only appropriate session variables are updated.

Methods

Constructor

new

The constructor takes no arguments and initializes an empty store. The store is implemented as a hashref similar to what you would expect from a Moo/Moose object but it is recommended that you do not inspect directly because this behavior is not guaranteed for subclasses.

If a subclass overwrites the storage approach, it MUST override this method as well.

Internal store

There are several things which are not the responsibility of the internal store. These include checking validity of variable names as these could vary between major versions of PostgreSQL. Subclasses MAY override these methods safely and provide a different storage mechanism.

set($key, $value)

Sets a current GUC variable to a particular value.

forget($key)

Deletes a key from the store

known_keys()

Returns a list of keys from the store.

get_value($key)

Returns a value from the key in the store.

DB Session

The methods in this session integrate with a database session and pull data from these. The module itself does not depend on the database session for general use.

fetch($dbh, $key)

Retrieves a setting from the session and saves it to the store.

Returns the stored value.

list($dbh)

Returns a list of all GUC variables set for the database session at $dbh

Does not affect store.

sync_session($dbh)

Synchronizes all stored variables into the current session if applicable.

apply_system($dbh)

Requires superuser access. Runs ALTER SYSTEM commands for all appropriate keys.

Returns a list of keys applied. This can then be used to check against expected behavior.

File and Contents

This module is also capable of reading to and writing to files and generating file content in the format expected. This means that the general whitespace rules and escaping approach PostgreSQL expects are met.

fromfile($path)

Reads the contents from a file. Loads the whole file into memory.

fromcontents($contents)

Parses file content and sets the internal store accordingly.

filecontents()

Returns file contents. Variables are set in alphabetical order

tofile($path)

Writes the contents, per filecontents above, to $path

Future Versions

sync_system($dbh)

This command will use ALTER SYSTEM statements to set defaults to be used on next PostgreSQL restart or reload. Not yet supported.

AUTHOR

Chris Travers, <chris.travers at adjust.com>

BUGS

Please report any bugs or feature requests to bug-pgobject-util-pgconfig at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=PGObject-Util-PGConfig. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc PGObject::Util::PGConfig

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2017 Adjust.com

This program is distributed under the (Revised) BSD License: http://www.opensource.org/licenses/BSD-3-Clause

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

* Neither the name of Adjust.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.