PGObje...DBAdmin(3pm)

📦

version 1.6.2 · 3 versions

1.6.2 · ubuntu resolute, ubuntu stonking (latest)
1.6.1 · debian bookworm, ubuntu jammy, ubuntu noble
1.6.2 · debian trixie

PGObject::Util::DBAdmin 💅

PostgreSQL Database Management Facilities for PGObject — that's the 3pm manual page, bestie, and we're about to make friends with it 💖

✨ NAME ✨

PGObject::Util::DBAdmin — PostgreSQL Database Management Facilities for PGObject 🐘👑

🌸 VERSION 🌸

version 1.6.2

🦋 SYNOPSIS 🦋

Okay so real talk: this module is the friend that handles all the basic Postgres db manipulation utilities for you. She's got you. ✨

 my $db = PGObject::Util::DBAdmin->new(
    connect_data => {
       user     => 'postgres',
       password => 'mypassword',
       host     => 'localhost',
       port     => '5432',
       dbname   => 'mydb'
    }
 );

 my @dbnames = $db->list_dbs(); # like psql -l

 $db->create(); # createdb
 $db->run_file(file => 'sql/initial_schema.sql'); # psql -f

 my $filename = $db->backup(format => 'c'); # pg_dump -Fc

 my $db2 = PGObject::Util::DBAdmin->new($db->export, (dbname => 'otherdb'));

 my $db3 = PGObject::Util::DBAdmin->new(
    connect_data => {
       service     => 'zephyr',
       sslmode     => 'require',
       sslkey      => "$HOME/.postgresql/postgresql.key",
       sslcert     => "$HOME/.postgresql/postgresql.crt",
       sslpassword => 'your-sslpassword',
    }
 );

See how $db->export just slides straight into ->new to spin up a whole second object? That's the main character move right there. 👑

🎀 PROPERTIES 🎀

connect_data

Contains a hash with connection parameters — and listen, the full list of what's supported lives in the PostgreSQL documentation at:

https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS

The usual suspects (the ones you'll actually be typing 99% of the time) are:

user
password
dbname
host
port

⚠️ Heads up bestie: the key requiressl is deprecated in favor of sslmode and isn't supported. Not a vibe. Use sslmode. 💀

username (deprecated)

The username used to authenticate with the PostgreSQL server.

password (deprecated)

The password used to authenticate with the PostgreSQL server.

host (deprecated)

In PostgreSQL, this can refer to the hostname or the absolute path to the directory where the UNIX sockets are set up.

port (deprecated)

Default '5432'

dbname (deprecated)

The database name to create or connect to.

🫶 Yes these are all deprecated, no that doesn't mean they vanished. They still work (see BUILDARGS below), they're just giving "legacy era". You're meant to use connect_data now. Periodt.

stderr

When applicable, the stderr output captured from any external commands (for example createdb or pg_restore) run during the previous method call. See the notes down in CAPTURING. 🧚

stdout

When applicable, the stdout output captured from any external commands (for example createdb or pg_restore) run during the previous method call. See the notes down in CAPTURING. 🧚

logger

Provides a reference to the logger associated with the current instance. The logger uses ref $self as its category, which means you do not have to go build brand new loggers every time you derive from this class. Slay. ✨

If you want to override the logger-instantiation behaviour, please implement the _build_logger builder method in your derived class. That's the door, bestie. 🚪💅

🌈 GLOBAL VARIABLES 🌈

%helper_paths

This hash variable contains as its keys the names of the PostgreSQL helper executables — psql, dropdb, pg_dump, etc. The values contain the paths at which the executables to be run are located. The default values are the names of the executables only, which is what lets them get looked up in $PATH. 👑

Modification of the values in this variable is the strict realm of applications. Libraries that use this library should defer any potential required modifications to the applications based upon them. (Translation: don't touch it from a library, that's not your lane, fr fr.) 🙈

💜 SUBROUTINES/METHODS 💜

new

Creates a new db admin object for manipulating databases. That's it, that's the whole job, and she does it beautifully. 🎀

BUILDARGS

Compensates for the legacy invocation with the username, password, host, port and dbname parameters. (This is the thing quietly translating your old-style calls into the new world so nothing breaks. 🫶)

verify_helpers( [ helpers => [...]], [operations => [...]])

Verifies ability to execute (external) helper applications by method name (through the operations argument) or by external helper name (through the helpers argument). Returns a hash ref with each key being the name of a helper application (see helpers below) with the values being a boolean indicating whether or not the helper can be successfully executed. ✅❌

Valid values in the array referenced by the operations parameter are:

create
run_file
backup
backup_globals
restore
drop

…which are the methods this module implements with the help of external helper programs. (Other values may be passed, but unsupported values aren't included in the return value. No sneaky extras. 🙅)

Valid values in the array referenced by the helpers parameter are the names of the PostgreSQL helper programs:

createdb
dropdb
pg_dump
pg_dumpall
pg_restore
psql

(Other values may be passed, but unsupported values will not be included in the return value. Same deal.)

When no arguments are passed, all helpers will be tested. All of them. Every single one. 🌈

💡 Note: verify_helpers is a class method, meaning it wants to be called as PGObject::Util::DBAdmin->verify_helpers(). Don't call it on an instance and then act surprised, okay? 😭

export

Exports the database parameters as a list so it can be used to create another object. (This is the bit in the SYNOPSIS doing the handoff into a fresh ->new. Iconic.) 👑

connect($options)

Connects to the database using DBI and returns a database connection. 🔌

Connection options may be specified in the $options hashref.

server_version([$dbname])

Returns a version string (like 9.1.4) for PostgreSQL. Croaks on error. 🐸

When a database name is specified, uses that database to connect to, using the credentials specified in the instance.

If no database name is specified, 'template1' is used.

list_dbs([$dbname])

Returns a list of db names. 📋

When a database name is specified, uses that database to connect to, using the credentials specified in the instance.

If no database name is specified, 'template1' is used.

create

Creates a new database. 🎉

Croaks on error, returns true on success.

Supported arguments:

copy_of — Creates the new database as a copy of the specified one (using it as a template). Optional parameter. Default is to create a database without a template.

run_file

Run the specified file on the db. 📄✨

After calling this method, STDOUT and STDERR output from the external utility which runs the file on the database are available as properties $db->stdout and $db->stderr respectively.

Croaks on error. Returns true on success.

Recognized arguments are:

file — Path to file to be run. This is a mandatory argument. (Mandatory mandatory. Don't skip it. 🙈)
vars — A hash reference containing psql-variables to be passed to the script being executed. Running:

   $dbadmin->run_file(file => '/tmp/pg.sql', vars => { schema => 'xyz' });

Is equivalent to starting the file /tmp/pg.sql with the command

   \set schema xyz

To undefine a variable, associate the variable name (hash key) with the value undef.

stdout_log — Provided for legacy compatibility. Optional argument. The full path of a file to which STDOUT from the external psql utility will be appended.
errlog — Provided for legacy compatibility. Optional argument. The full path of a file to which STDERR from the external psql utility will be appended.

backup

Creates a database backup file. 💾

After calling this method, STDOUT and STDERR output from the external utility which runs the file on the database are available as properties $db->stdout and $db->stderr respectively.

Unlinks the output file and croaks on error. 🐸🗑️

Returns the full path of the file containining the backup.

Accepted parameters:

format — The specified format, for example c for custom. Defaults to plain text.
file — Full path of the file to which the backup will be written. If the file does not exist, one will be created with umask 0600. If the file exists, it will be overwritten, but its permissions will not be changed. 🔐

If undefined, a file will be created using File::Temp having umask 0600.

tempdir — The directory in which to write the backup file. Optional parameter. Uses File::Temp default if not defined. Ignored if the file parameter is given.
compress — Optional parameter. Specifies the compression level to use and is passed to the underlying pg_dump command. Default is no compression.

backup_globals

This creates a file containing a plain text dump of global (inter-db) objects, such as users and tablespaces. It uses pg_dumpall to do this. 🌍

Being a plain text file, it can be restored using the run_file method. (Cute little full-circle moment. 🎀)

Unlinks the output file and croaks on error. 🐸🗑️

Returns the full path of the file containining the backup.

Accepted parameters:

file — Full path of the file to which the backup will be written. If the file does not exist, one will be created with umask 0600. If the file exists, it will be overwritten, but its permissions will not be changed. 🔐

If undefined, a file will be created using File::Temp having umask 0600.

tempdir — The directory in which to write the backup file. Optional parameter. Uses File::Temp default if not defined. Ignored if the file parameter is given.

restore

Restores from a saved file. Must pass in the file name as a named argument. ♻️

After calling this method, STDOUT and STDERR output from the external restore utility are available as properties $db->stdout and $db->stderr respectively.

Croaks on error. Returns true on success.

Recognized arguments are:

file — Path to file which will be restored to the database. Required.
format — The file format, for example c for custom. Defaults to plain text.

drop

Drops the database. This is not recoverable. Croaks on error, returns true on success.

💀 BESTIE. Not recoverable. There is no undo, there is no "wait let me just—", there is no coming back. Say it with me: not recoverable. Make sure you meant it. 🫶

is_ready

Drops the database. This is not recoverable. Croaks on error, returns true on success.

😭 Not me pointing out that the docs for is_ready are literally word-for-word the same as the docs for drop. That's what the page says, bestie, I'm just the messenger. No cap, that's the whole entry.

🧚 CAPTURING 🧚

This module uses Capture::Tiny to run extenal commands and capture their output, which is made available through the stderr and stdout properties.

This capturing does not work if Perl's standard STDOUT or STDERR filehandles have been localized. In this situation, the localized filehandles are captured, but external system calls are not affected by the localization, so their output is sent to the original filehandles and is not captured. 🙈

See the Capture::Tiny documentation for more details. 📚

🌸 AUTHOR 🌸

Chris Travers, "<chris at efficito.com>"

⭐ BUGS ⭐

Please report any bugs or feature requests to "bug-pgobject-util-dbadmin at rt.cpan.org", or through the web interface at:

http://rt.cpan.org/NoAuth/ReportBug.html?Queue=PGObject-Util-DBAdmin

I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. 🫶✨

🫶 SUPPORT 🫶

Okay bestie, if you ever get stuck (and you won't, but like, if), you can pull up the docs for this module right from your terminal with the perldoc command:

perldoc PGObject::Util::DBAdmin

So easy, so iconic.

You can also go snooping for info in these very good, very legit places:

📮 RT: CPAN's request tracker (report bugs here) — this is where you go when something's acting up and you need to tell the maintainers about it:

http://rt.cpan.org/NoAuth/Bugs.html?Dist=PGObject-Util-DBAdmin

📝 AnnoCPAN: Annotated CPAN documentation — community annotations, lil notes in the margins, love that for us:

http://annocpan.org/dist/PGObject-Util-DBAdmin

⭐ CPAN Ratings — where people rate it, and like, it deserves a five, periodt:

http://cpanratings.perl.org/d/PGObject-Util-DBAdmin

🔍 Search CPAN — the search bar of destiny:

http://search.cpan.org/dist/PGObject-Util-DBAdmin/

🎀 ACKNOWLEDGEMENTS 🎀

Nothing here, bestie. Not a single line. An empty acknowledgements section is its own kind of main character energy — humble, quiet, mysterious. 💅

👑 LICENSE AND COPYRIGHT 👑

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 Chris Travers's Organization nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.

And here comes the ALL-CAPS part, which is not a vibe check you want to fail — legal text is dramatic on purpose, so here it is, exactly as written:

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.

🫧 Quick translation, bestie: it's free to use, you just gotta keep the copyright notice and the disclaimer around, don't slap Chris Travers's Organization's name on your fork like it's an endorsement, and if it breaks? That's on the universe, not on them.

And that's the whole page, bestie!! 💖✨🎀🦋🌸💅

This lil masterpiece was cooked up as part of perl v5.40.0, dated 2024-09-16, filed under PGObje...DBAdmin(3pm) in the User Contributed Perl Documentation — so when you're telling your friends about it (and you will), you know exactly where it lives. 🫶 Go forth and manage those databases, you absolute legend. 👑

📦 where this page comes from

ubuntu resolute: libpgobject-util-dbadmin-perl 1.6.2-1 · BSD-3-Clause
ubuntu stonking: libpgobject-util-dbadmin-perl 1.6.2-1 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms