Alzabo::SQLMaker(3pm)

💖 Alzabo::SQLMaker 💖

okay bestie, buckle up, because this is the manual page for Alzabo::SQLMaker — a page straight out of the User Contributed Perl Documentation collection — and it's literally the base class for RDBMS drivers in Alzabo. it's giving ✨infrastructure✨ and honestly? iconic. let's get into it 🫶

---

🌸 NAME 🌸

Alzabo::SQLMaker — the Alzabo base class for RDBMS drivers, periodt 💅

---

🎀 SYNOPSIS 🎀

use Alzabo::SQLMaker::MySQL;

my $sql = Alzabo::SQLMaker::MySQL->new( driver => $driver_object );

# or better yet

my $sql = $runtime_schema->sqlmaker;

not me showing you the long way and the short way. the "or better yet" is doing so much heavy lifting here, bestie, trust 🦋

---

🌈 DESCRIPTION 🌈

so this right here is the base class for every single Alzabo::SQLMaker module, no cap. if you wanna actually instantiate a driver, you call this class's new method. and if you're feeling ambitious and want to build a driver for the RDBMS of your choice? go read "SUBCLASSING Alzabo::SQLMaker" — it's all laid out for you 💜

---

✨ METHODS ✨

💫 available

returns a list of names representing the available Alzabo::SQLMaker subclasses. any one of these names would be appropriate as a parameter for the Alzabo::SQLMaker->load() method. like a little menu of drivers, chef's kiss 🍓

💫 load

loads the specified subclass.

it takes one parameter: the name of the RDBMS being used.

throws: Alzabo::Exception::Eval — yeah she can throw, watch out 😭

💫 new

this one takes two parameters:

• driver — the driver object being used by the schema.
• quote_identifiers — a boolean value indicating whether or not identifiers should be quoted. this defaults to false.

---

🔥 GENERATING SQL 🔥

you can use this class to generate SQL by calling methods that are the same as those used in SQL (select(), update(), etc.) in sequence, with the appropriate parameters. chain them like a little friendship bracelet 👑

there are four entry point methods: select(), insert(), update(), and delete(). attempting to call any other method without first calling one of these is an error. no skipping steps, bestie 🚫

🌟 Entry Points 🌟

these methods are called as class methods and return a new object.

select (Alzabo::Table and/or Alzabo::Column objects)

this begins a select. the columns to be selected are the column(s) passed in, and/or the columns of the table(s) passed in as arguments.

followed by:

• from()
• ** function

insert

followed by:

• into()

update (Alzabo::Table)

followed by:

• set()

delete

followed by:

• from()

🌟 Other Methods 🌟

all of these methods return the object itself, which makes it possible to chain together method calls such as:

Alzabo::SQLMaker->select($column)->from($table)->where($other_column, '>', 2);

from (Alzabo::Table object, ...)

the table(s) from which we are selecting data.

follows:

• select()
• ** function
• delete()

followed by:

• where()
• order_by()

throws: Alzabo::Exception::SQL

where <see below>

the first parameter to where must be an Alzabo::Column object or SQL function. the second is a comparison operator of some sort, given as a string. the third argument can be an Alzabo::Column object, a value (a number or string), or an Alzabo::SQLMaker object — and that last one is treated as a subselect 👀

values given as parameters will be properly quoted and escaped. safety first 💅

some comparison operators allow additional parameters:

• the BETWEEN comparison operator requires a fourth argument. this must be either an Alzabo::Column object or a value.
• the IN and NOT IN operators allow any number of additional parameters, which may be Alzabo::Column objects, values, or Alzabo::SQLMaker objects.

follows:

• from()

followed by:

• and()
• or()
• order_by()

throws: Alzabo::Exception::SQL

and (same as "where")

or (same as "where")

these methods take the same parameters as the where() method.

follows:

• where()
• and()
• or()

followed by:

• and()
• or()
• order_by()

throws: Alzabo::Exception::SQL

order_by (Alzabo::Column objects)

adds an ORDER BY clause to your SQL. sorting era 🎀

follows:

• from()
• where()
• and()
• or()

followed by:

• limit()

throws: Alzabo::Exception::SQL

limit ($max, optional $offset)

specifies a limit on the number of rows to be returned. the offset parameter is optional.

follows:

• from()
• where()
• and()
• or()
• order_by()
• Alzabo::Exception::SQL

into (Alzabo::Table object, optional Alzabo::Column objects)

used to specify what table an insert is into. if column objects are given then it is expected that values will only be given for that object. otherwise, it's assumed that all columns will be specified in the values() method.

follows:

• insert()

followed by:

• values()

throws: Alzabo::Exception::SQL

values (Alzabo::Column object => $value, ...)

this method expects to receive a structure like a hash where the keys are Alzabo::Column objects and the values are the value to be inserted into that column.

follows:

• into()

throws: Alzabo::Exception::SQL

set (Alzabo::Column object => $value, ...)

this method's parameters are exactly like those given to the values method.

follows:

• update()

followed by:

• where()

throws: Alzabo::Exception::SQL

---

🦋 RETRIEVING SQL FROM THE OBJECT 🦋

sql

this method can be called at any time, though obviously it will not return valid SQL unless called at a natural end point. in the future, an exception may be thrown if called when the SQL is not in a valid state. (so like, she's flexible but she has boundaries 💀)

returns the SQL generated so far as a string.

bind

returns an array reference containing the parameters to be bound to the SQL statement. ✨

---

👑 SUBCLASSING Alzabo::SQLMaker 👑

to create a subclass of Alzabo::SQLMaker for your particular RDBMS, all it takes is implementing the virtual methods listed below. that's it. that's the whole assignment 🫶

in addition, you may choose to override any of the other methods described in this documentation. for example, the MySQL subclass overrides the _subselect() method because MySQL cannot support sub-selects. (rude of MySQL honestly but okay.)

subclasses are also expected to offer for export various sets of functions matching SQL functions. see the Alzabo::SQLMaker::MySQL subclass implementation for details 👀

---

⭐ VIRTUAL METHODS ⭐

the following methods must be implemented by the subclass:

limit

see above for the definition of this method.

get_limit

this method may return undef even if the limit() method was called. some RDBMS's have special SQL syntax for LIMIT clauses. for those that don't support this, the Alzabo::Driver module takes a limit parameter.

the return value of this method can be passed in as that parameter.

• if the RDBMS does not support LIMIT clauses, the return value is an array reference containing two values: the maximum number of rows allowed and the row offset (the first row that should be used).
• if the RDBMS does support LIMIT clauses, then the return value is undef.

sqlmaker_id

returns the subclass's name. this should be something that can be passed to Alzabo::SQLMaker->load() as a parameter. iykyk 💅

---

🌸 AUTHOR 🌸

Dave Rolsky, <dave@urth.org>

---

and that's the whole page, bestie!! 🎉 no notes, she ate. this was Alzabo::SQLMaker(3pm) from the User Contributed Perl Documentation, generated under perl v5.34.0 and dated 2022-06-14. go forth and generate some SQL, you absolute icon 💖✨🎀🦋