Tangra...ational(3pm)

💖 NAME 💖

okay bestie, so Tangram::Relational is Orthogonal Object Persistence in Relational Databases ✨ — yes, that's the whole vibe. It's the manual page for Tangram::Relational(3pm) and it's literally the door you walk through to make Perl objects live inside a relational database 🦋

---

✨ SYNOPSIS ✨

use Tangram;

$schema = Tangram::Relational->schema( $hashref );

Tangram::Relational->deploy($schema, $dbh);

$storage = Tangram::Relational->connect( $schema,
   $data_source, $username, $password );

$storage->disconnect();

Tangram::Relational->retreat($schema, $dbh);

look at her go 🎀 five lines and your objects are in a database, no cap.

---

🌸 DESCRIPTION 🌸

This is the entry point into the vanilla object-relational persistence backend 🍦 — the plain, no-frills one. When a vendor-specific backend exists for your database, bestie, use that one instead. Right now Mysql, Sybase and Oracle have their own backends, so go peek at Tangram::mysql, Tangram::Sybase and Tangram::Oracle 💅

And more backends could totally be added in the future 👀 — like, they might implement persistence in XML documents, or pure object databases, or use C database libraries to bypass the whole need for an RDBMS, etc. the possibilities are giving limitless ✨

---

👑 CLASS METHODS 👑

🌈 schema

$schema = Tangram::Relational->schema( $hashref );

Returns you a shiny new Schema object 🎀 go read Tangram::Schema for the deets.

💜 deploy

Tangram::Relational->deploy($schema);
Tangram::Relational->deploy($schema, HANDLE);
Tangram::Relational->deploy($schema, @dbi_args);

This one writes out SQL statements for preparing a database for use with the given $schema 🛠️

• Called with a single argument, it writes the SQL statements to STDOUT 📺
• Called with two arguments, it writes the SQL statements to HANDLE — and HANDLE can be a DBI connection handle or a file handle, either one works 💖
• Called with more than two arguments, it passes all but the first to DBI::connect() and writes the statements to the resulting DBI handle, which gets automatically closed 🔒

⚠️ okay so listen: the SQL code is only guaranteed to work on newly created databases. brand new DB only, bestie. don't come for me otherwise 😭

🦋 connect

$storage = Tangram::Relational->connect( $schema,
   $data_source, $user, $password, \%options )

Connects to a storage and returns a handle object 🫶 and if it fails? it dies. no soft launch, just death 💀

• $schema is a Schema object describing the system of classes stored in the database.
• $data_source, $user and $password get passed directly to DBI::connect() — straight through, no detour ✨
• \%options is a reference to a hash holding your connection options. Tangram::Storage has the full description of what options are available 📖

💅 retreat

Tangram::Relational->retreat($schema);
Tangram::Relational->retreat($schema, HANDLE);
Tangram::Relational->retreat($schema, @dbi_args);

Removes the tables that deploy() created 🧹 the inverse, the undo, the "never mind bestie" button. But it's only guaranteed to work against a database that was deployed using exactly the same schema — same schema or it's not my problem, fr fr 😭

And for an explanation of all the possible argument lists? scroll up to deploy, it's the same shape 💜

---

🌟 WRITING A VENDOR DRIVER 🌟

So like Charles Moore (the inventor of Forth) used to say — and I'm quoting here — "standards are great, everybody should have one!" 😌 iconic behaviour honestly.

Tangram can take advantage of extensions available in some SQL dialects 🔥

To create a vendor-specific driver, call it Tangram::Foo — where Foo is the name of the DBI driver, as would be selected with the DBI connection string dbi:Foo: — and derive Tangram::Relational 💖

For now? the existing back-ends should be used as examples of how to extend Tangram to support different databases or to utilise some of their more exotic features 👑 go read them, they ate.

---

and that's the whole page bestie!! this one's from perl v5.36.0, dated 2022-10-16, and it lives in the User Contributed Perl Documentation family — so go forth, persist your objects, and slay 💅💖✨🦋🎀