SQL::Library(3)

💖 SQL::Library 💖

okay bestie, so this is the manual page for SQL::Library, a Perl module for managing simple SQL libraries that live in INI-like files. It ships as a User Contributed Perl Documentation page, which is exactly the kind of thing you'd pull up with man SQL::Library — or perldoc SQL::Library if you're feeling fancy. ✨

---

🌸 NAME 🌸

SQL::Library — a module for managing simple SQL libraries stored in INI-like files. that's it, that's the whole vibe. no cap. 🎀

---

🦋 VERSION 🦋

this doc is talking about version 0.0.5 of SQL::Library. yes, the specific number matters, don't @ me. 💅

---

✨ SYNOPSIS ✨

here's the whole thing in action, look how cute it is:

use SQL::Library;

my $sql = new SQL::Library { lib => 'sql.lib' };
                      # or { lib => [ <FH> ] };
                      # or { lib => [ $string ] };

## Ask for a library entry by name...
my $query = $sql->retr( 'some_sql_query' );

## Add or update an entry...
$sql->set( 'yet_another_query', <<'END' );
SELECT foo
FROM   bar
WHERE  zoot = 1
END

## Remove an entry from the library...
$sql->drop( 'one_more_query' );

## List the entries in the library...
print join( ' : ', $sql->elements ), "\n";

## Dump the contents of the library to a string...
my $lib_str = $sql->dump;

## Write the library to disk...
$sql->write;

so you construct it, you retr stuff, you set stuff, you drop stuff, you list, you dump, you write. it's giving full lifecycle. 🔥

---

🌈 LIBRARY FILE FORMAT 🌈

okay so the format for these library files looks a lil bit like an INI file, but — and this is the plot twist — it is not an INI file. unlike an INI file, it does not handle key=value pairs that are divided up into sections. 🙅‍♀️

instead: library entry names sit on a line all by themselves, wrapped in square brackets. everything that comes after that until the next title tag is the value of the library entry. and the lil bits of noise — blank lines, pound signs (#) and C++ style comments (//) — all get discarded. gone. bye. 💀

a sample library file might look like this:

## A sample library file

[get_survey_questions]
select   question_no,
         question_text
from     question
where    survey_id = ?
order by question_no

[get_survey_info]
select title,
       date_format( open_date, '%Y%m%d' ) as open_date,
       date_format( close_date, '%Y%m%d' ) as close_date,
       template_file
from   survey
where  survey_id = ?

see how the SQL just vibes inside the brackets? iconic behavior honestly. 👑

---

💅 OBJECT METHODS 💅

PACKAGE->new( HASHREF )

creates a brand new library handle for you. right now the only argument supported in that hashref is lib, and lib points at the file containing the SQL library. that's it, that's the whole constructor menu. 🫶

$OBJ->retr( NAME )

hands you back the library entry that NAME points at. ask and you shall receive. ✨

$OBJ->set( NAME, VALUE )

sets the library entry NAME to VALUE. this is your multitasker — it's used both to create brand new library entries and to update the ones that already exist. glow-up for your library. 💖

$OBJ->drop( NAME )

drops entry NAME from the library. (yes the original says "form" and honestly, same, typos happen, we keep it real here — but the point is the entry is GONE.) 💀

$OBJ->elements

returns a list of all the entry names chillin' in the library. 📋

$OBJ->dump

returns a string holding the library contents in the very same INI format that the module reads from. round trip, babes. 🔁

$OBJ->write

writes the library out to the file named in lib. 💾

---

🐛 BUGS 🐛

• write() should write to a string, if it was so called. (it currently does not. noted. logged. we move.) 😭

---

📝 TO-DO 📝

• Complete test suite

yes bestie, the test suite is a work in progress. we're manifesting. 🧚

---

👑 AUTHOR 👑

Doug Gorley <douggorley@shaw.ca>

---

🌟 CO-MAINTAINER 🌟

Chris Vertonghen <chrisv@cpan.org> — and this is post-0.0.3, so anything before that was a different era. ⭐

---

📜 COPYRIGHT & LICENSE 📜

Copyright (C) 2004 by Doug Gorley.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.

tl;dr: it's Perl-licensed, so go forth and remix. but keep the copyright line, bestie, it's the law. 💜

---

and that's the whole page!! this doc was rendered by perl v5.42.0 on 2025-07-25 — so if you're reading this, that's the version-and-date era you're in. mwah. 💖✨🎀🦋