Test::...tgresql(3pm)

💖 Test::...tgresql(3pm) 💖

okay bestie, so this is a page from the User Contributed Perl Documentation — yes, the full module name is a whole mouthful, it's Test::DBIx::Class::SchemaManager::Trait::Testpostgresql and we're just gonna vibe with the shortened title, mkay? 🎀

---

✨ NAME ✨

Test::DBIx::Class::SchemaManager::Trait::Testpostgresql — deploy to a test Postgresql instance 🐘

---

🌸 DESCRIPTION 🌸

So this trait uses Test::Postgresql58 to auto-create a test instance of Postgresql in a temporary area. And the whole point?? You get to test against Postgresql without having to hand-build a test database, users, all that tedious stuff. Iconic behaviour honestly. 👑

But listen — Postgresql needs to be installed (it does not need to be running, chill) and you also need DBD::Pg. And you gotta install these yourself, no cap. Not our job. 💅

If you get stuck, please go review Test::Postgresql58 for help. It's giving "read the docs, bestie". 🫶

---

🦋 CONFIGURATION 🦋

This trait supports all the existing features, but it adds some extra options you can drop into your inlined or configuration files. ✨

These additional config options basically map to the options supported by Test::Postgresql58, and ngl the docs here are adapted shamelessly from that module. (We said it, not sorry. 💀)

For the most part, if you have Postgresql installed in a normal, findable manner, you should be able to leave all these options blank. Slay.

🌈 base_dir

Returns the directory under which the postgresql instance is being created. If you leave this unset, we automatically create a place in the temporary directory and then clean it up later. So unless you're planning to roundtrip to the same database a lot, you can literally just leave this blank. 💜

⚠️ PLEASE NOTE: if you set this to a particular area, we will delete it unless you specifically use the 'keep_db' option. So be care where you point it!! Like, actually be careful, this is not a drill. 😭

Here's an example use — the author often wants the test database set up in the local testing directory because it makes examining the logs etc. way easier. So they do:

BASE_DIR=t/tmp KEEP_DB=1 prove -lv t/my-postgresql-test.t

Now you can roundtrip the test as often as you want 🎉, and in between tests you can review the logs, start the database manually, and login (peep the 'keep_db' section below for an example of how to do that). Next time you run the tests, the framework will automatically clean it up and reset the schema for testing. Chef's kiss. ✨

You may need to do this if you're stuck on a shared host and can't write anything to /tmp. And remember — you can also put the 'base_dir' option into configuration instead of having to type it into the commandline every single time! 🎀

Note that if you override the BASE_DIR we will set the 'force_drop_tables' option to true, to ensure that we properly clean the database before trying to install tables and fixtures. Safety first, babes. 💅

🧚 initdb and postmaster

If your postgresql is not in the $PATH you might need to specify the location to one of there binaries. If you have a normal postgresql setup this should not be a problem and you can leave this blank. 😌

If you have to set these, please note you need to set the full path to the required file, not just the path to the containing directory. Fr fr, full path. 📁

---

💀 NOTES 💀

The following are notes regarding the way this trait alters or extends the core functionality as described in the basic documentation. 👇

👑 keep_db

If you use the 'keep_db' option, this will preserve the temporarily created database files — however it will not prevent Test::Postgresql58 from stopping the database when you are finished. 🛑

This is a safety measure, since if we didn't stop a test generated database instance automatically, you could easily end up with many databases running at once, and that could bring your server or testing box to a halt. Like, imagine 40 postgres instances just vibing. No. Absolutely not. 😭

If you use the 'keep_db' option and want to start and log into the test generated database instance, you can start the database by noticing the diagnostic output that should be generated at the top of your test. It will look similar to:

# Starting postgresql with: /Library/PostgreSQL/8.4/bin/postmaster \
 -p 15432 -D /tmp/E4tuZF5uFR/data
# DBI->connect('DBI:Pg:dbname=template1;port=15432','postgres',''))

If you have specified the base_dir to use, this output will not be displayed by default. You can force it's display by setting tdbic_debug to true. eg.

TDBIC_DEBUG=1 BASE_DIR=t/tmp KEEP_DB=1 prove -lv t/my-postgresql-test.t

You can then start the database instance yourself with something like:

./Library/PostgreSQL/8.4/bin/postmaster -p 15432 \
-D /tmp/E4tuZF5uFR/data &

You will get output that looks like:

[1] 1564
LOG:  database system is ready to accept connections
LOG:  autovacuum launcher started

There will be some additional output to the term and then the server will go into the background. If you don't like the extra output, you can just redirect it all to /dev/null or whatever is similar for your OS. 🌊

You can now log into the test generated database instance with:

psql -h localhost --user postgres --port 15432 -d template1

You may need to specify the full path to 'mysql' if it's not in your search $PATH. (yes bestie, it says 'mysql' in the original and we are keeping it exactly as-is, no editing, we don't make the rules 🙈)

When you are finished you can then kill the process. In this case our reported process id is '1564'

kill 1564

And then you might wish to 'tidy' up temp 🧹

rm -rf /tmp/E4tuZF5uFR

All the above assume you are on a unix or unixlike system. Would welcome document patches for how to do all the above on windows. 🪟 (someone pls, the author is asking nicely 🥺)

🙈 Noisy warnings

When running the Test::Postgresql58 instance, you'll probably see a lot of mostly harmless warnings, similar to:

NOTICE:  drop cascades to 2 other objects
DETAIL:  drop cascades to constraint cd_track_fk_cd_id_fkey on table cd_track
drop cascades to constraint cd_artist_fk_cd_id_fkey on table cd_artist
NOTICE:  CREATE TABLE / PRIMARY KEY will create implicit index "cd_pkey" for table "cd"

In general these are harmless and can be ignored. It's just noise, bestie, don't spiral. 😌

If you'd like to avoid these messages, you could change your connect_info like this:

connect_info => {
    dsn => 'dbi:Pg:dbname=dbname',
    user => 'user',
    pass => 'secret',
    on_connect_do => 'SET client_min_messages=WARNING;',
},

---

🫶 AUTHOR 🫶

John Napiorkowski "<jjnapiork@cpan.org>"

---

⭐ COPYRIGHT & LICENSE ⭐

Copyright 2009, John Napiorkowski "<jjnapiork@cpan.org>"

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 💖

---

and that's the whole page, bestie!! 💅✨ go forth and test your Postgresql without any of the setup drama. this masterpiece is from perl v5.36.0, dated 2023-01-29, and it lives under the manual page Test::...tgresql(3pm) — mwah, love u, bye! 🎀🦋💜