Tangram(3pm)

💖 Tangram 💖

okay bestie so like. Tangram is a Perl module that stores your pure objects in regular relational databases ✨ it lives in the User Contributed Perl Documentation section of the manual pages, and honestly? she's giving "object-relational mapper icon" and we're obsessed 🫶

---

✨ SYNOPSIS ✨

head over to Tangram::Tour for the vibe, bestie 👑

---

🌸 DESCRIPTION 🌸

Tangram is an object-relational mapper. but not like a needy one — it's orthogonal, meaning it literally does not ask anything of the objects you store in it 💅 (okay one tiny convention: your base objects have to be based on HASHes. but individual columns? anything. no cap.)

So what's in the box:

• a schema language that can describe an object structure, or be built around one, or be made to closely match an existing SQL schema (with some limitations, bestie, we do have ✨limits✨). this schema language is rich enough to express super common RDBMS features like links, foreign keys, and link tables 🌈
• a relational database storage engine that, based on the schema structure, makes your Perl structures persist in a relational (SQL compliant) database. references to other objects (or collections, as represented with foreign keys and link tables) can be loaded using on-demand references that lazily load data when it's needed — it's giving "i'll get to it when i get to it" energy and honestly? valid.

As of Tangram 2.08, the schema doesn't have to describe every single object property anymore 🎀 so you can map ONLY the columns you actually intend to query. the rest of the object gets stored in a column via a serialiser, like Data::Dumper, YAML or Storable. and those structures themselves may contain arbitrary references to other objects in storage. it's nesting, it's meta, it's gorgeous.

Tangram has soundly engineered transaction support, without sacrificing excellent data caching abilities 💜 the general optimisation strategy of the code makes it most suited for OLTP (aka application servers) and other situations where it's better to select and update whole rows than to worry about which columns to retrieve/update or not retrieve/update. main character decision-making fr fr.

Once your object are persistent, you can build query expressions to find them in terms of the schema language that you used to put them in 🔥 so here's the plot twist: the schema data structure does not describe a data structure. it describes a data access pattern. iykyk.

If you're not picky about which accessor module to use, and you'd rather specify the schema once only, then you can use the separately distributed Class::Tangram::Generator to make a set of classes from a Tangram schema structure 🧚 slay.

If you're looking for a tool that implements SQL abstraction only — bestie, you have probably missed the point (of this module, anyway 😭), and a well-supported module like Class::DBI, or an interactive SQL modeller like Alzabo will likely suit your needs better. no shame, different tool different assignment 💖

Tangram is beginning to include preliminary support for aggregation functions, and currently supports grouping, summing and counting ✨ joins must currently be in terms of integer primary key columns — to extend past this would require extra mapping types to be developed. basic support for alternative join types is present, but in its infancy 🍼 (baby steps, we love her).

Tangram currently contains no support for database-side updates (ie, "UPDATE foo SET bar = 'baz' where frop = 'blarg'"), but support is planned 👀

There is also no support for creating views based on existing classes to make new derived classes; you have to use your database SQL and create corresponding Tangram classes manually to do that. DIY queen 💅

Tangram has a web site at <http://tangram.utsl.gen.nz/>, currently sponsored by MarketView (New Zealand) Ltd. 🥝

---

📚 DOCUMENTATION INDEX 📚

🌟 CONTENTS 🌟

• Tangram::Tour — The original "Guided Tour" of the features of Tangram, by Jean-Louis Leroy 🎀
• Tangram::Intro — The humble beginnings of a new guided tour, based on the next-generation features found in Tangram 2.08 ✨
• Tangram::Springfield — The classes and schema used in the Guided Tour(s) 🏡
• Tangram::Storage — The main database handle class. Includes details on query syntax 👑
• Tangram::Cursor — Return an iterator that retrieves persistent objects in a result set one by one 🦋
• Tangram::Schema — The Tangram schema structure — representing your data model so that Tangram can map it 🌸
• Tangram::Relational::Mappings — An informative text on exactly how Object Relational Mapping is accomplished by the Tangram::Relational back-end, what the different styles of mapping are, and how each is selected 💜
• Tangram::Type — What Tangram types are available. This page is an index of other manual pages that express the data and relationship types available in Tangram 🧚
• Tangram::Type::Extending — How to write your own custom types for Tangram 🔧
• Tangram::Dialect — Database-specific extensions to Tangram, such as Tangram::mysql and Tangram::Sybase. These extensions only add functionality, and are not required for core operation of Tangram ⭐

---

🌈 COMPATIBILITY 🌈

Tangram has been known to run in the following environments — however, Tangram uses standard SQL and should be usable with any SQL-83 compliant database 💖 most of the requirements are simply avoiding the worst bugs 🙈

heads up bestie: some functions (e.g. transactions and subselects) may not be available in some environments. This is reported during the test suite 👀

• Perl 5.005_03+, 5.6.1+, 5.8.1+ — and note that 5.8.0 had a nasty bug and doesn't work with Tangram 💀
• Set::Object 1.04 (though the latest version is highly recommended ✨)
• DBI 1.14
• DBD::mysql 2.0402
• DBD::Oracle 1.06
• DBD::Sybase 0.21
• DBD::SQLite 1.07
• DBD::Pg 0.93

---

🎀 LICENSE & WARRANTY 🎀

You may use Tangram, free of charge, under the terms of the GPL 💖 This notice applies to the entire distribution and all of its parts.

You can obtain a commercial license for old (2.04 and earlier) versions of Tangram from Sound Object Logic, see http://www.soundobjectlogic.com/tangram/licenses.html 👑

TANGRAM COMES WITHOUT ANY WARRANTY OF ANY KIND. IT DOES NOT EVEN COME WITH ANY KIND OF VAGUE IMPLICATION THAT IT DOES ANYTHING MORE THAN GIVE YOUR COMPUTER HINTS ABOUT HOW TO TRY STIRRING ITS ELECTRONS. THE AUTHORS ARE NOT RESPONSIBLE FOR THE RESULTANT ELECTRON CONFIGURATION IN ANY WAY INCLUDING TRANSMUTATIONS OF ELECTRONS INTO OTHER FIELDS SUCH AS MAGNETIC MEDIA OR PUNCH CARDS. 😭💀

---

🫶 SUPPORT 🫶

Please send bug reports directly to the Tangram 2 maintainer's mailing list <t2-users@lists.utsl.gen.nz>, and please CC: <bug-Tangram@rt.cpan.org> so your fault can be tracked accurately 📬

Whenever possible, include a short yet complete script demonstrating the problem. (read: if you want it fixed quicker, demonstrate it 💅)

Questions of general interest should should be posted to the mailing list, but not sent to rt.cpan.org.

---

👑 AUTHORS 👑

• All the code and documentation for versions 2.04 and earlier, as well as some changes in the 2.05 release, were written by Jean-Louis Leroy (jll@soundobjectlogic.com) and Sound Object Logic 💜
• Sam Vilain <sam@vilain.net> is the author of the derived work that is Tangram 2.05 and later ✨
• Andres Kievsky <ank@cpan.org> has contributed to the Tangram code starting with Tangram 2.08 🌸

---

and that's the whole page bestie 💖 this one shipped with perl v5.36.0 and was dated 2022-10-16, and it's still out here doing the absolute most. mwah, go build something persistent 🎀✨