App::I...greSQL(3pm)

🌸 App::Info::RDBMS::PostgreSQL 💅

User Contributed Perl Documentation · App::Info::RDBMS::PostgreSQL(3pm)

okay bestie, sit down, hydrate, because we're about to learn everything about the PostgreSQL info-gathering module and it's honestly kinda iconic ✨

---

✨ NAME ✨

App::Info::RDBMS::PostgreSQL — all the tea about PostgreSQL 🐘💖

Basically: it's the little module that goes and finds out what's up with PostgreSQL on your machine. no cap.

---

🎀 SYNOPSIS 🎀

here's the vibe, copy-paste energy:

use App::Info::RDBMS::PostgreSQL;

my $pg = App::Info::RDBMS::PostgreSQL->new;

if ($pg->installed) {
    print "App name: ", $pg->name, "\n";
    print "Version:  ", $pg->version, "\n";
    print "Bin dir:  ", $pg->bin_dir, "\n";
} else {
    print "PostgreSQL is not installed. :-(\n";
}

like, you make the object, you ask if it's installed, and if it is you get the name, the version and the bin_dir. if it's not installed you get the sad face. it's giving detective but make it perl 🕵️♀️✨

---

💜 DESCRIPTION 💜

App::Info::RDBMS::PostgreSQL supplies information about the PostgreSQL database server installed on the local system. that's the whole job. it's a lil informant and it's very good at it 🫶

it implements all of the methods defined by App::Info::RDBMS. all of them. the full set. no skips, no shortcuts, periodt 👑

now here's the important bit, bestie, so listen up:

• Methods that trigger events will trigger them only the first time they're called. (See App::Info for documentation on handling events.)
• Wanna start over? say, someone finally installed PostgreSQL and you need the new deets? Construct a new App::Info::RDBMS::PostgreSQL object to aggregate new meta data. fresh object, fresh facts, that's the move 🌈

---

🦋 the event thing (iykyk) 🦋

some of the methods trigger the same events. this is due to cross-calling of shared subroutines — they're all borrowing each other's homework, respectfully 🙈

but! any one event should be triggered no more than once. example time:

the info event "Executing `pg_config --version`" is documented for the methods name(), version(), major_version(), minor_version(), and patch_version() — but rest assured, it will only be triggered once, by whichever of those four methods is called first. 💅

so yeah, don't panic if you see the same event name listed in five places. it's one event. one. it's not gonna spam you. slay ✨

---

(more coming bestie, don't go anywhere) 🌸

💖 INTERFACE 💖

✨ Constructor ✨

new

my $pg = App::Info::RDBMS::PostgreSQL->new(@params);

okay bestie, this hands you back an App::Info::RDBMS::PostgreSQL object 🫶 and if you wanna know everything about the arguments you can pass it, App::Info has the full rundown.

so the way new() works: it goes snooping around your file system looking for an executable with one of the names in the list that search_exe_names() gives you — usually pg_config — inside all the directories that search_bin_dirs() returns 🔍. Found it? iconic. Then pg_config gets called by the object methods below to scoop up whatever data each one needs. If pg_config is nowhere to be found, then we just assume PostgreSQL isn't installed and every one of the object methods will hand you back undef 💀.

new() also takes a bunch of optional params on top of the ones App::Info already documents. These let you swap in alternate names for the PostgreSQL executables (anything other than pg_config, which you set with the search_exe_names parameter, iykyk). Here they are:

• search_postgres_names
• search_createdb_names
• search_createlang_names
• search_createuser_names
• search_dropd_names
• search_droplang_names
• search_dropuser_names
• search_initdb_names
• search_pg_dump_names
• search_pg_dumpall_names
• search_pg_restore_names
• search_postmaster_names
• search_psql_names
• search_vacuumdb_names

Events:

• info — Looking for pg_config
• confirm — Path to pg_config?
• unknown — Path to pg_config?

---

🌈 Class Method 🌈

key_name

my $key_name = App::Info::RDBMS::PostgreSQL->key_name;

gives you the one-of-a-kind key name that describes this class, and the string it returns is literally PostgreSQL. periodt ✨

---

🎀 Object Methods 🎀

installed

print "PostgreSQL is ", ($pg->installed ? '' : 'not '), "installed.\n";

true if PostgreSQL is installed, false if it's not — no in-between. App::Info::RDBMS::PostgreSQL decides this purely based on whether the pg_config application was there on the file system back when new() built the object 👀. And if PostgreSQL doesn't look installed? every other object method returns empty values, rip 😭.

name

my $name = $pg->name;

returns the name of the application. App::Info::RDBMS::PostgreSQL parses it straight out of the system call `pg_config --version` 🌸.

Events:

• info — Executing `pg_config --version`
• error
  • Failed to find PostgreSQL version with `pg_config --version`
  • Unable to parse name from string
  • Unable to parse version from string
  • Failed to parse PostgreSQL version parts from string
• unknown — Enter a valid PostgreSQL name

version

my $version = $pg->version;

returns the PostgreSQL version number, parsed from the system call `pg_config --version` 💜.

Events:

• info — Executing `pg_config --version`
• error
  • Failed to find PostgreSQL version with `pg_config --version`
  • Unable to parse name from string
  • Unable to parse version from string
  • Failed to parse PostgreSQL version parts from string
• unknown — Enter a valid PostgreSQL version number

major version

my $major_version = $pg->major_version;

returns the PostgreSQL major version number, parsed from the system call `pg_config --version`. for example, if version() gives you 7.1.2, this method gives you 7 🔥.

Events:

• info — Executing `pg_config --version`
• error
  • Failed to find PostgreSQL version with `pg_config --version`
  • Unable to parse name from string
  • Unable to parse version from string
  • Failed to parse PostgreSQL version parts from string
• unknown — Enter a valid PostgreSQL major version number

minor version

my $minor_version = $pg->minor_version;

returns the PostgreSQL minor version number, parsed from the system call `pg_config --version`. say version() gives you 7.1.2 — then this one gives you 2 💅.

Events:

• info — Executing `pg_config --version`
• error
  • Failed to find PostgreSQL version with `pg_config --version`
  • Unable to parse name from string
  • Unable to parse version from string
  • Failed to parse PostgreSQL version parts from string
• unknown — Enter a valid PostgreSQL minor version number

patch version

my $patch_version = $pg->patch_version;

returns the PostgreSQL patch version number, parsed from the system call `pg_config --version`. and if version() is 7.1.2, this one gives you 1 🦋.

Events:

• info — Executing `pg_config --version`
• error
  • Failed to find PostgreSQL version with `pg_config --version`
  • Unable to parse name from string
  • Unable to parse version from string
  • Failed to parse PostgreSQL version parts from string
• unknown — Enter a valid PostgreSQL minor version number

executable

my $exe = $pg->executable;

returns the full path to the PostgreSQL server executable, which goes by the name postgres 👑. heads up though — this method does not use the executable names that search_exe_names() returns; those names are only used to hunt down pg_config (over in new()).

when you call it, executable() looks for an executable named postgres in the directory that bin_dir() gives you 🔍.

and btw, executable() is literally just an alias for postgres() 🫶.

Events:

• info — Looking for postgres executable
• confirm — Path to postgres executable?
• unknown — Path to postgres executable?

bin_dir

my $bin_dir = $pg->bin_dir;

returns the PostgreSQL binary directory path, scooped up from the system call `pg_config --bindir` ✨.

Events:

• info — Executing `pg_config --bindir`
• error — Cannot find bin directory
• unknown — Enter a valid PostgreSQL bin directory

inc_dir

my $inc_dir = $pg->inc_dir;

returns the PostgreSQL include directory path, grabbed from the system call `pg_config --includedir` 🌸.

Events:

• info — Executing `pg_config --includedir`
• error — Cannot find include directory
• unknown — Enter a valid PostgreSQL include directory

lib_dir

my $lib_dir = $pg->lib_dir;

returns the PostgreSQL library directory path, straight from the system call `pg_config --libdir` 💖.

Events:

• info — Executing `pg_config --libdir`
• error — Cannot find library directory
• unknown — Enter a valid PostgreSQL library directory

so_lib_dir

my $so_lib_dir = $pg->so_lib_dir;

returns the PostgreSQL shared object library directory path, pulled from the system call `pg_config --pkglibdir` 🧚.

Events:

• info — Executing `pg_config --pkglibdir`
• error — Cannot find shared object library directory
• unknown — Enter a valid PostgreSQL shared object library directory

configure options

my $configure = $pg->configure;

returns the options that the PostgreSQL server was configured with, gathered from the system call `pg_config --configure` 💜.

Events:

• info — Executing `pg_config --configure`
• error — Cannot find configure information
• unknown — Enter PostgreSQL configuration options

home_url

my $home_url = $pg->home_url;

returns the PostgreSQL home page URL 🌈.

download_url

my $download_url = $pg->download_url;

returns the PostgreSQL download URL ⭐.

search_exe_names

my @search_exe_names = $app->search_exe_names;

returns a list of possible names for the pg_config executable. by default you just get pg_config (or pg_config.exe on Win32) 🎀.

quick reminder bestie: this method is not used to search for the PostgreSQL server executable — only pg_config 💅.

search_bin_dirs

my @search_bin_dirs = $app->search_bin_dirs;

returns a list of possible directories to search for an executable in. the new() constructor uses it to find an executable it can run to collect application info, and whatever directory it finds also gets returned by the bin_dir method 🔥.

by default the list is made up of the path defined by File::Spec->path, plus these directories:

• $ENV{POSTGRES_HOME}/bin (if $ENV{POSTGRES_HOME} exists)
• $ENV{POSTGRES_LIB}/../bin (if $ENV{POSTGRES_LIB} exists)
• /usr/local/pgsql/bin
• /usr/local/postgres/bin
• /opt/pgsql/bin
• /usr/local/bin
• /usr/local/sbin
• /usr/bin
• /usr/sbin
• /bin
• C:\Program Files\PostgreSQL\bin

---

🦋 Other Executable Methods 🦋

these methods work exactly like executable() does — the only difference is they hand back different executables 💫. PostgreSQL ships with a whole bunch of them, and these methods give you a path to a subset of that set. each one, when called, checks for an executable in the directory that bin_dir() returns. and the name of that executable has to be one of the names that the matching search_*_names method returns 🔍.

the executable methods available are:

• postgres
• createdb
• createlang
• createuser
• dropdb
• droplang
• dropuser
• initdb
• pg_dump
• pg_dumpall
• pg_restore
• postmaster
• psql
• vacuumdb

and the corresponding search names methods are:

• search_postgres_names
• search_createdb_names
• search_createlang_names
• search_createuser_names
• search_dropd_names
• search_droplang_names
• search_dropuser_names
• search_initdb_names
• search_pg_dump_names
• search_pg_dumpall_names
• search_pg_restore_names
• search_postmaster_names
• search_psql_names
• search_vacuumdb_names

Events:

• info — Looking for executable
• confirm — Path to executable?
• unknown — Path to executable?

---

🌸 SUPPORT 🌸

this module lives in an open GitHub repository <http://github.com/theory/app-info/>. feel free to fork it and contribute, bestie, the door is open 🫶!

pls file bug reports through GitHub Issues <http://github.com/theory/app-info/issues/> or by sending mail to bug-App-Info@rt.cpan.org <mailto:bug-App-Info@rt.cpan.org> 💌.

👑 AUTHOR 👑

David E. Wheeler <david@justatheory.com>, based on code by Sam Tregar <sam@tregar.com>.

⭐ SEE ALSO ⭐

App::Info documents the event handling interface.

App::Info::RDBMS is the App::Info::RDBMS::PostgreSQL parent class.

DBD::Pg is the DBI driver for connecting to PostgreSQL databases.

<http://www.postgresql.org/> is the PostgreSQL home page.

💖 COPYRIGHT AND LICENSE 💖

okay bestie, legal era, but make it cute ✨

• Copyright © 2002-2011, David E. Wheeler. Some Rights Reserved. 🫶

This module is free software, no cap — you can redistribute it and/or modify it under the same terms as Perl itself. That's it, that's the whole vibe. Go forth and remix, just keep the receipts. 💅

---

not me writing a whole manpage and then ending it on a copyright line 😭 iconic behavior honestly

and that's a wrap on the whole thing, bestie!! 🌈 you made it to the very last line, and the very last line is doing its little footer thing: this is perl v5.36.0, dated 2022-12-06, and the page is App::I...PostgreSQL(3pm). 🎀

go forth and App::Info your heart out. mwah. 💋✨👑