Data::...ok::SQL(3pm)

💖 Data::...ok::SQL(3pm) — the SQL/DBI Phrasebook Model 💖

okay bestie, so this is the manual page for Data::...ok::SQL(3pm), which ships with Perl's user-contributed documentation, and honestly? it's giving glow-up for your phrasebook. sit down, grab a 🍓, we're doing this.

---

✨ NAME ✨

Data::Phrasebook::SQL — the SQL/DBI Phrasebook Model. yes queen, that's the whole vibe: a phrasebook that actually knows about SQL and DBI. 💅

---

🦋 SYNOPSIS 🦋

use Data::Phrasebook;
use DBI;

my $dbh = DBI->connect(...);

my $book = Data::Phrasebook->new(
    class => 'SQL',
    dbh   => $dbh,
    file  => 'queries.txt',
);
my $q = $book->query( 'find_author', {
        author => "Lance Parkin"
    });
while ( my $row = $q->fetchrow_hashref ) {
    print "He wrote $row->{title}\n";
}
$q->finish;

and the queries.txt in question:

find_author=select title,author from books where author = :author

no cap, that's the whole bit. 🌸

---

🌈 DESCRIPTION 🌈

so the whole thing here is: if you wanna use features like placeholders in DBI alongside phrasebooks, it lowkey helps to have a phrasebook that's a lil more aware of how DBI does its thing. and that's exactly what you get with Data::Phrasebook::SQL. periodt.

Data::Phrasebook::SQL has knowledge of how DBI works and creates and executes your queries appropriately. it's not just vibes — it's actually doing the work. 👑

---

🎀 CONSTRUCTOR 🎀

💜 new

not to be accessed directly, bestie — you go through the parent Data::Phrasebook and specify the class as SQL. iykyk.

the additional arguments on top of the ones described in Data::Phrasebook::Generic are:

• dbh — a DBI database handle. that's it, that's the one. 🫶

---

🔥 METHODS 🔥

🌸 dbh

set, or get, the current DBI handle. your lil handle baby. 💅

⭐ query

constructs a Data::Phrasebook::SQL::Query object from a template. it takes at least one argument, and that argument is the identifier for the query. that identifier gets used as a key into the phrasebook file. you can also hand it a second argument, which is an optional hashref of key to value mappings. cute, right?

if your phrasebook has a YAML source that looks a whole lot like this:

---
find_author:
    sql: select class,title,author from books where author = :author

then you could write:

my $q = $book->query( 'find_author' );

OR

my $q = $book->query( 'find_author', {
    author => 'Lance Parkin'
} );

OR

my $author = 'Lance Parkin';
my $q = $book->query( 'find_author', {
    author => \$author,
} );

# sql  = select class,title,author from books where author = ?
# args = 'Lance Parkin'

in the examples above, the parameters are bound to the SQL using the bind parameters functionality. this is more efficient in most cases where the same SQL is reused with different values for fields. slay, efficiency. ⚡

however — and this is the plot twist 🙈 — not all SQL statements just need to bind parameters. some may require the ability to replace parameters, such as a field list.

---
find_author:
    sql: select :fields from books where author = :author

my $q = $book->query( 'find_author',
    replace => { fields => 'class,title,author' },
    bind    => { author => 'Lance Parkin' }
    );

# sql  = select class,title,author from books where author = ?
# args = 'Lance Parkin'

💀 in all instances, if the SQL template requested does not exist or has no definition, then an error will be thrown. not a vibe check you want to fail, bestie.

consult Data::Phrasebook::SQL::Query for what you can then do with your returned object. go forth and fetch. 🧚

for reference: the bind hashref argument, if it is given, is given to the query object's order_args and then args methods. keep that receipt. 🧾

---

👑 SEE ALSO 👑

Data::Phrasebook, Data::Phrasebook::Generic, Data::Phrasebook::SQL::Query. the whole friend group. 🫶

---

🌈 SUPPORT 🌈

please see the README file. short and sweet, as it should be. ✨

---

💖 AUTHOR 💖

Original author: Iain Campbell Truskett (16.07.1979 - 29.12.2003)
Maintainer: Barbie <barbie@cpan.org> since January 2004.
for Miss Barbell Productions <http://www.missbarbell.co.uk>.

genuinely iconic lineage, no notes. 🎀

---

🎀 COPYRIGHT AND LICENSE 🎀

Copyright (C) 2003 Iain Truskett.
Copyright (C) 2004-2013 Barbie for Miss Barbell Productions.

This distribution is free software; you can redistribute it and/or
modify it under the same terms as the Artistic License v2.

---

and that's a wrap, bestie 💅 this whole page is perl v5.36.0, dated 2022-11-19, and it lives under the manual name Data::...ok::SQL(3pm) — go forth and query responsibly. 🦋💖