Alzabo...Schema(3pm)

💖 Alzabo::Create::Schema — the manual page, but make it cute 💖

okay bestie, welcome to Alzabo...Schema(3pm), straight out of the User Contributed Perl Documentation section. grab a strawberry drink 🍓 and let's get into it, because this class is kind of a big deal.

---

✨ NAME ✨

Alzabo::Create::Schema — Schema objects for schema creation. yes, that's the whole vibe. it makes schemas. it creates them. iconic behavior. 👑

---

🎀 SYNOPSIS 🎀

use Alzabo::Create::Schema;

that's it. that's the whole flex. one line. 💅

---

🌸 DESCRIPTION 🌸

okay so picture this: this class represents the whole schema. like, the entire thing. it contains table objects, and those table objects contain columns, indexes, etc. etc. — it's giving nesting dolls but make it databases 🪆

and it's not just a container, bestie. it has methods that act globally on the schema — methods to save it to disk, to create itself in an RDBMS, to create relationships between tables, all of it. main character energy, no cap. ✨

🦋 Instantiation 🦋

every schema keeps track of whether it has been instantiated or not. and what does "instantiated" even mean? it means the schema exists in an RDBMS backend. fr fr.

you can do this explicitly by calling the schema's create() method. it also gets set implicitly when a schema is created as the result of reverse engineering.

now here's the part that lowkey changes everything: the most important effect of instantiation is that once a schema is instantiated, the way it generates SQL for itself changes.

• before it's instantiated: if you ask it to generate SQL via the make_sql() method, it will generate the set of SQL statements needed to create the schema from scratch.
• after it's instantiated: the schema will instead generate the SQL necessary to convert the version in the RDBMS backend to match the object's current state. think of it as a SQL 'diff'. 🫶

this feature is genuinely so useful, but ngl it can be confusing too. the most surprising aspect? if you create a schema via reverse engineering and then call the make_sql() method, you will not get any SQL. why? because the schema knows it's instantiated, and it also knows it's the same as the version in the RDBMS, so no SQL is necessary. it's giving "nothing to see here". 💀

you can use the set_instantiated() method method to change whether or not the schema thinks it is instantiated. (yes, the original says "method method". we keep the lore intact. 🫡)

---

👑 INHERITS FROM 👑

Alzabo::Schema

Note: all relevant documentation from the superclass has been merged into this document. so don't go looking for it elsewhere, bestie, it's all right here. 💖

---

💅 METHODS 💅

🌈 Constructors 🌈

new

this constructor takes the following parameters:

• name => $name — this is the name of the schema, and it will be the name of the database in the RDBMS.
• rdbms => $rdbms — this is a string identifying the RDBMS. the allowed values are returned from the Alzabo::RDBMSRules->available method. these are values such as 'MySQL', 'PostgreSQL', etc.

it returns a new Alzabo::Create::Schema object. 🎀

Throws: Alzabo::Exception::Params, Alzabo::Exception::System

load_from_file

this constructor takes the following parameters:

• name => $schema_name

returns a schema object previously saved to disk, as specified by the name parameters.

Throws: Alzabo::Exception::Params, Alzabo::Exception::System

reverse_engineer

attempts to connect to a database and instantiate a new schema object based on information in the specified database. the returned object will have its instantiated value set to true, so that subsequent changes will lead to SQL diffs, as opposed to SQL to create the database from scratch.

the schema object returned by this method will have its instantiated attribute set as true.

it takes the following parameters:

• name => $name — the name of the database with which to connect.
• rdbms => $rdbms — see the new method documentation for an explanation of this parameter.

in addition, this method takes any parameters that can be used when connecting to the RDBMS, including user, password, host, and port. 🦋

returns a new Alzabo::Create::Schema object.

---

🌟 Other Methods 🌟

name

returns a string containing the name of the schema. simple. elegant. slay. 💅

set_name ($name)

changes the schema name. and listen — since schemas are saved on disk with filenames based on the schema name, this deletes the files for the old name. 😭 so call save_to_file() immediately afterwards if you want to make sure you have a copy of the schema saved. don't say we didn't warn you.

Throws: Alzabo::Exception::Params, Alzabo::Exception::RDBMSRules, Alzabo::Exception::System

table ($name)

returns an Alzabo::Create::Table object representing the specified table.

an Alzabo::Exception::Params exception is throws if the schema does not contain the table. (yes, "is throws". the original said it, so we're keeping it. 🫶)

tables (@optional_list)

if no arguments are given, this method returns a list of all Alzabo::Create::Table objects in the schema, or in a scalar context the number of such tables. if one or more arguments are given, it returns a list of table objects with those names, in the same order given (or the number of such tables in a scalar context, but this isn't terribly useful — the manpage's words, not mine 💀).

an Alzabo::Exception::Params exception is throws if the schema does not contain one or more of the specified tables.

has_table ($name)

returns a boolean value indicating whether the table exists in the schema. vibe check: does it exist? true or false, that's the whole answer. ✨

make_table

this method makes a new table and adds it to the schema. the parameters given are passed directly to the Alzabo::Create::Table->new() method. the schema parameter is filled in automatically — we got you, bestie. 🫶

if a before or after parameter is given, then the move_table() method will be called to move the new table to the appropriate position.

returns a new Alzabo::Create::Table object.

Throws: Alzabo::Exception::Params, Alzabo::Exception::RDBMSRules

delete_table ("Alzabo::Create::Table" object)

removes the given table from the schema. this method will also delete all foreign keys in other tables that point at the given table. it's thorough like that. 💅

Throws: Alzabo::Exception::Params

add_table

add a table to the schema.

this methods takes the following parameters:

• table => "Alzabo::Create::Table" object
• after => "Alzabo::Create::Table" object (optional)

... or ...

• before => "Alzabo::Create::Table" object (optional)

returns a new Alzabo::Create::Table object.

Throws: Alzabo::Exception::Params

move_table

allows you to change the order of the tables as they are stored in the schema. reorganization, but make it intentional. 🎀

this method takes the following parameters:

• table => "Alzabo::Create::Table" object — the table to move.

and either ...

• before => "Alzabo::Create::Table" object — move the table before this table

... or ...

• after => "Alzabo::Create::Table" object — move the table after this table.

Throws: Alzabo::Exception::Params

add_relationship

creates a relationship between two tables. this involves creating Alzabo::Create::ForeignKey objects in both tables. if the columns_from and columns_to parameters are not specified, then the schema object attempts to calculate the proper values for these attributes.

to do this, Alzabo attempts to determine the dependencies of the tables. if you have specified a cardinality of 1..1, or n..1, in cases where both tables are independent, or where they are both dependent, then the table_from is treated as being the dependent table for the purposes of determining

(yes, the original sentence just ends there like that. we're not fixing it. it's canon. 💀)

if no columns with the same names exist in the other table, then columns with those names will be created. otherwise, add_relationship() changes the dependent columns so that their Alzabo::Create::ColumnDefinition objects are the same as the columns in the table upon which they are dependent — meaning that changes to the type of one column affects both at the same time. synced. locked in. 🔥

if you want to make a multi-column relationship, the assumption is that the order of the columns is significant. in other words, the first column in the columns_from parameter should correspond to the first column in hte columns_to parameter and so on. (that's "hte" — original typo, preserved with love. 🫶)

the number of columns given in columns_from and columns_to must be the same, except when creating a many to many relationship.

if the cardinality is many to many, then a new table will be created to link the two tables together. this table will contain the primary keys of both the tables passed into this function. it will contain foreign keys to both of these tables as well, and these tables will be linked to this new table. a whole little matchmaker situation. 💖

this method takes the following parameters:

• table_from => "Alzabo::Create::Table" object (optional if columns_from is provided)
• table_to => "Alzabo::Create::Table" object (optional if columns_to is provided)
• columns_from => "Alzabo::Create::Column" object (optional if table_from is provided)
• columns_to => "Alzabo::Create::Column" object (optional if table_to is provided)
• cardinality => [1, 1], [1, 'n'], ['n', 1], or ['n', 'n']
• name => $name — if provided, and if the specified cardinality requires the creation of a linking table, this string will be used to name that linking table. otherwise, the new table's name will be synthesized from the names of those it's linking.
• from_is_dependent => $boolean
• to_is_dependent => $boolean
• comment => $comment

Throws: Alzabo::Exception::Params

create

this method causes the schema to connect to the RDBMS, create a new database if necessary, and then execute whatever SQL is necessary to make that database match the current state of the schema object. if the schema has been instantiated previously, then it will generate the SQL necessary to change the database.

⚠️ this may be destructive (dropping tables, columns, etc) so be careful. like, genuinely careful, bestie. this is not a drill. 💀

this will cause the schema to be marked as instantiated.

wherever possible, existing data will be preserved. 🫶

this method takes any parameters that can be used when connecting to the RDBMS, including schema_name, user, password, host, and port.

if a schema_name parameter is given, then this will be the name given to the schema in the RDBMS.

Warning: every time you call create() or sync_backend(), the schema will consider itself to have been instantiated. this will affect how schema diffs are generated. after this, you will almost certainly need to use sync_backend() to sync the RDBMS schema, since the schema's internal notion of it's state may be incorrect. (its*. its state. but again — original wording, we preserve. 😌)

instantiated

returns a boolean value indicating whether the schema has been created in an RDBMS backend, otherwise it is false. 🌈

set_instantiated ($bool)

set the schema's instantiated attribute as true or false. flip the switch, babe. ✨

Throws: Alzabo::Exception::Params

make_sql

returns an array containing the SQL statements necessary to either create the database from scratch or update the database to match the schema object. see the create() method for more details. 🧚

drop

drops the database/schema from the RDBMS. this will cause the schema to be marked as not instantiated. this method does not delete the Alzabo files from disk. to do that, call the delete() method. two different things, don't get them twisted. 💅

---

and that's part one, bestie — more is coming, so don't go anywhere 🎀

okay so bestie, this method? it's the chill one. it takes literally any parameter you'd use when connecting to the RDBMS — like schema_name, user, password, host, and port are all fair game. 🫶

Throws: Alzabo::Exception::Driver 😭

---

sync_backend 🦋

bestie this one is the glow-up method. it peeks at the schema as it actually exists in the RDBMS backend and makes whatever changes are needed so that the backend schema matches your Alzabo schema object. and if there's, like, no corresponding schema in the RDBMS backend at all? then it's basically the same as calling create(). iconic behaviour honestly.

once you've called this, the schema is considered instantiated. 💅

ngl, this method will never be perfect, and that's not a bug it's just how it is — because some RDBMS backends alter table definitions the moment they're created. like, MySQL has default column lengths for all of its integer columns, and Alzabo tries to account for that. it's giving "doing my best."

so what that means in the end is that Alzabo may never think a schema in the RDBMS exactly matches the state of the Alzabo schema object. even immediately after running this method, running it again might still make it execute SQL commands. 😭 but lowkey it's fine — the SQL it generates will not cause anything to break. no cap.

and yep, this method takes any parameters that can be used when connecting to the RDBMS, including schema_name, user, password, host, and port.

Throws: Alzabo::Exception::Driver

---

sync_backend_sql ✨

if there is no corresponding schema in the RDBMS backend, then this method returns the SQL you need to create the schema from scratch. that's it. that's the whole vibe. 🎀

it also takes any parameters that can be used when connecting to the RDBMS, including schema_name, user, password, host, and port.

Throws: Alzabo::Exception::Driver

---

delete 💀

okay so this one removes the schema object from disk. it does NOT delete the database from the RDBMS — like, those are two completely different things bestie. if deleting the actual database is what you want, you have to call the drop method first. periodt.

Throws: Alzabo::Exception::System

---

clone 🧚

this creates a brand new object identical to the one you called the method on — with three tiny differences:

• this new schema has a different name
• it does not yet exist on disk
• its instantiation attribute is set to false

it takes the following parameter:

• name => $name — the new name you're giving this little guy 🌸

this method returns a new Alzabo::Create::Schema object. 🫶

Throws: Alzabo::Exception::Params, Alzabo::Exception::RDBMSRules

---

save_to_file 💾

saves the schema to a file on disk. that's it, that's the tweet.

Throws: Alzabo::Exception::System

---

runtime_clone 🦋

returns a new Alzabo::Runtime::Schema object based on the current schema. yes, you get a runtime bestie version of your schema. obsessed.

---

is_saved ⭐

returns true if the schema has been saved to disk. a vibe check, essentially.

---

begin_work 🌈

starts a transaction. and here's the cute part — calls to this function may be nested and it will be handled properly. she can multitask. 💅

---

rollback</rollback>

wait no, hold on 🙈 — it's:

rollback ↩️

rollback a transaction. the "never mind bestie, forget I said all that" of database operations.

---

commit ✅

finishes a transaction with a commit. and listen — if you made multiple calls to begin_work(), make sure to call this method the same number of times. stack them up, then pop them all off. iykyk. 👑

---

run_in_transaction ( sub { code... } ) 🔥

this method takes a subroutine reference and wraps it in a transaction. chef's kiss.

it will preserve the context of the caller and returns whatever the wrapped code would have returned. so it's giving transparent, seamless, main character energy. ✨

---

driver 🚗

returns the Alzabo::Driver object for the schema.

---

rules 📜

returns the Alzabo::RDBMSRules object for the schema.

---

sqlmaker 🛠️

returns the Alzabo::SQLMaker object for the schema.

---

👑 AUTHOR 👑

Dave Rolsky, <autarch@urth.org> 💖

---

and that's a wrap bestie!! 🎀 this page came to you courtesy of perl v5.34.0, dated 2022-06-14, and it lives at Alzabo...Schema(3pm). go forth and sync those backends, you absolute icon 💅✨🫶