Tangram::Storage(3pm)

📦
version 2.12 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

Tangram::Storage — persistent object database 🫶

welcome to the Tangram::Storage(3pm) page bestie, this is User Contributed Perl Documentation and it's that girl. okay so lowkey this is the object that talks to your database, let's go 💅

✨ SYNOPSIS ✨

use Tangram;

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

$oid = $storage->insert( $obj );
@oids = $storage->insert( @objs );

$storage->update( $obj );
$storage->update( @objs );

$obj = $storage->load( $oid );
@objs = $storage->load( @oids );

@objs = $storage->select( $class );
@objs = $storage->select( $remote, $filter );

$cursor = $storage->cursor( $remote, $filter );

if ($storage->oid_isa($oid, "ClassName")) {
    # oid $oid is a ClassName
}

$storage->disconnect();

🌸 DESCRIPTION 🌸

A Tangram::Storage object is, simply, a connection to a database that's been set up to work with Tangram. that's it. that's the whole thing. it's giving "bridge between your Perl objects and your RDBMS" and honestly? iconic.

🧠 MEMORY MANAGEMENT 🧠

okay so starting with version 1.18, Tangram tries to use the weak reference support that landed in Perl 5.6. whether that support is there or not majorly changes how Storage messes with object lifetime, so listen up 🎀

  • If weakref support is available, Storage uses weak references to keep track of objects that have already been loaded. This does not stop Perl from reclaiming those objects. IOW: your client code is the one deciding how long an object stays in memory. main character energy, truly.
  • If weakref support is not available, Storage falls back to normal, 'strong' references. Storage will pin in memory every object that has been loaded and inserted through it, until you call disconnect or unload.

either way, Tangram will not break circular structures for you. no cap.

⚠️ note that caching objects between transactions is a great way to ruin the transactional guarantees that your database (hopefully) provides. like. don't.

that being said, be sure to check out the unload_all() method ✨

🔌 INTERNAL CONNECTION 🔌

Except in the implementation of cursor(), Tangram uses a single DBI connection for its operations. That connection is called the 'internal' connection. Since, in general, database managers do not allow multiple result sets on the same connection, the internal connection can only be used to carry a single task at a time. one at a time bestie, no line-cutting 💀

Tangram::Cursors returned by cursor() do not suffer from this limitation, because they use a separate DBI connection. slay for them honestly.

👑 CLASS METHODS 👑

🌈 connect

$storage = connect( $schema,
   $data_source, $username, $auth, \%options )

Connects to a storage and returns a handle object. Dies in case of failure. no soft launches here, it's pass/fail 😭

$schema is an Tangram::Schema object consistent with the database.

$data_source, $username and $auth are passed directly to DBI::connect().

\%options is a reference to a hash that may contain the following fields:

  • dbh — Pass in an already connected DBI handle
  • no_tx — Specify explicitly whether or not transactions are possible. If they are not, then Tangram can guarantee consistency by serialising transaction updates — which guarantees poor performance and means that you can never use $storage->rollback. (If you are using MySQL, you should consider using the InnoDB table type to avoid this problem. Also note that you will explicitly have to set this option if you have InnoDB tables configured, as there is no real way of telling if transactions are available for any given query without either trying to do a rollback, or querying the table types for every table. Which I don't think it's Tangram's duty to do! 💅)
  • no_subselects — Functions that need to perform sub-selects will die immediately or attempt to emulate the functionality required, rather than relying on the RDBMS to return a failure. This is currently ignored, but that's not functionally relevant :-). It can be read as $storage->{no_subselects} however, as the correct value is automatically detected on connection.

All fields are optional. every single one. no pressure 🦋

dbh can be used to connect a Storage via an existing DBI handle. $data_source, $username and $auth are still needed though, because Tangram may need to open extra connections (see below). sneaky but valid.

💅 INSTANCE METHODS 💅

🍓 insert

$storage->insert( @objs );

Inserts objects in storage. Returns the ID(s) assigned to the object(s). This method is valid in both "scalar and list contexts".

The inserted objects must be of a class described in the schema associated to the storage. no rogue classes allowed.

Attempting to insert an object that is already persistent in the storage is an error. periodt.

Tangram will automatically insert any object that is refered by $obj if it is not already present in storage. In the following example:

my $homer = NaturalPerson->new(
   firstName => 'Homer', name => 'Simpson',
   children => Set::Object->new(
      NaturalPerson->new(
         firstName => 'Bart', name => 'Simpson' ),
      NaturalPerson->new(
         firstName => 'Lisa', name => 'Simpson' ),
      NaturalPerson->new(
         firstName => 'Maggie', name => 'Simpson'
   ) ) );

$storage->insert( $homer );

...Tangram automatically inserts the kids along with Homer. family package deal, adorable 🫶

🦋 update

$storage->update( @objs );

Save objects to storage. This method is valid in both "scalar and list contexts".

The objects must be of a class described in the schema associated to the storage.

Attempting to update an object that is not already present in the storage is an error.

Tangram will automatically insert any object that is refered by an inserted object if it is not already present in storage. It will not automatically update the refered objects that are already stored. In the following example:

my $homer = NaturalPerson->new(
   firstName => 'Homer', name => 'Simpson' );
$storage->insert( $homer );

my $marge = NaturalPerson->new(
   firstName => 'Marge', name => 'Simpson',
   age => 34 );
$storage->insert( $marge );

$marge->{age} = 35;

$homer->{partner} = $marge;

$homer->{children} = Set::Object->new(
   NaturalPerson->new(
      firstName => 'Bart', name => 'Simpson' ),
   NaturalPerson->new(
      firstName => 'Lisa', name => 'Simpson' ),
   NaturalPerson->new(
      firstName => 'Maggie', name => 'Simpson' ) );

$storage->update( $homer );

...Tangram automatically inserts the kids when their father is updated. OTOH, $marge will not be automatically inserted nor updated; her age will remain '34' in persistent storage. she stays 34 forever, iconic behaviour honestly 💀

Tangram does not perform any deadlock detection on updates. You have to rely on your database back-end for that. not Tangram's job bestie, take it up with your RDBMS.

💜 id

$id = $storage->id( $obj );
@id = $storage->id( @obj );

Returns the IDs of the given objects. If an object is not persistent in storage yet, its corresponding ID is undef().

This method is valid in both "scalar and list contexts".

🧚 oid_isa

if ($storage->oid_isa($id, "ClassName")) {
   ...
}

Checks that the passed Object ID, $id, is a "ClassName" according to the schema. This check relies solely on the information in the schema, not Perl's idea of ->isa relationships. so don't @ me with your inheritance feelings, this is schema business only.

⭐ load

$obj = $storage->load( $id );
@obj = $storage->load( @id );

Returns a list of objects given their IDs. Dies if any ID has no corresponding persistent object in storage. rip.

This method is valid in both "scalar and list contexts".

🪈 remote

@remote = $storage->remote( @classes );

Returns a list of "Tangram::Remote" objects of given classes. See Tangram::Remote for a more detailed description. These objects are called remote objects in the documentation. that's the official name, we don't make the rules 🎀

🌈 select

@objs = $storage->select( $remote );

@objs = $storage->select( $remote, $filter );

@objs = $storage->select( $remote,
   opt1 => val1, opt2 => val2, ...);

Valid only in list context. Returns a list containing all the objects that satisfy $filter. (if you try to call this in scalar context, that's not giving what you think it's giving.)

$remote can be either a remote object of an array of remote objects. If it is a single remote object, a list of objects is returned. If it is an array, a list of arrays of objects is returned.

  • If one argument is passed, return all the objects of the given type.
  • If two arguments are passed, the second argument must be a Filter. select() returns the objects that satisfy $filter and are type-compatible with the corresponding remote object.
  • If more than two arguments are passed, the arguments after $remote are treated as key/value pairs.

Currently Tangram recognizes the following directives:

  • filter
  • distinct
  • order
  • desc
  • distinct
  • limit
  • outer_filter
  • force_outer

filter specifies a Filter that can be used to restrict the result set.

Filters are based on simple Perl expressions involving remote objects. The expression is eventually compiled into its SQL equivalent, becoming part of a WHERE-CLAUSE. glow-up from Perl to SQL, we love to see it ✨

For example:

my $remote_person = $storage->remote('Foo::Person');
my @martians = $storage->select(
    $remote_person,
    filter => ($remote_person->{location} eq 'Mars')
);

Would retrieve all martians from the database. okay aliens 🛸

Note that the fields are accessed as hash reference keys instead of the (expected) method calls. yes bestie it's ->{location} not ->location, we cope.

In the previous example, ->{location} is seen as a scalar from Perl and as some derivative of a VARCHAR/TEXT field on the database side. But filters can operate on many other types, including references to other persistent objects. For instance:

# instantiate the obj and add it to the DB
my $mars = Foo::Location->new( name => 'Mars');
$storage->insert($mars);

my $remote_person = $storage->remote('Foo::Person');
my @martians = $storage->select(
    $remote_person,
    filter => ($remote_person->{location} == $mars)
);

In this case, having a reference to the persistent object $mars handy allows us to look for all objects that reference it. Keep in mind that these are introductory examples — the relationship between two classes of objects and how they behave depends on defined relationships between them — whether it's a "ref", an "array", etc -- see Tangram::Schema and Tangram::Type for more information on relationship types.

Filters can also be joined together with boolean expressions:

my $r_user = $storage->remote('My::Users');
my @active_premium_users = $storage->select( $r_user,
    filter => (# "&" is not a typo - see below
               ($r_user->{is_logged_in} eq 'Y') &
               ($r_user->{is_premium} eq 'Y' )
              )
);

...

(part 1 of 3 — hold on bestie, there's more 💖)

This select is the one that pulls back every user who's logged in and rocking a premium account. Real talk though — peep the & in there instead of && (or and). That's not a typo, bestie, that's a whole Perl problem: && may not be overloaded. So for your basic boolean operators you go & for AND, | for OR, and ! for NOT. Periodt.

The other overloaded bits that do exactly what you'd expect:

+ - * / == eq != ne < lt <= le > gt >= ge cos sin acos

...and every single one of those gets translated to its SQL counterpart as closely as possible. 💅

💡 Tip: you can also cook up filters ahead of time with this simple syntax: my $new_filter = ($r_user->{is_logged_in} eq 'Y'); Then you sprinkle more expressions onto it, like: $new_filter &= (r_user->{is_premium} eq 'Y'); and drop it into the expression like this: my @active_premium_users = $storage->select ( $r_user, filter => $new_filter );

As of Tangram 2.08_02, the scalar value 1 can be used as an "identity" filter. Slay.

Also go peek at "Tangram::Expr". 🦋

distinct says every object in the result set has to be unique — Tangram generates a SELECT DISTINCT for you.

order specifies attributes in terms of one or more of the remote objects — literally any that are being selected, or any that show up in the filter.

As of Tangram 2.09, you can also use SQL expressions directly in order expressions, though ngl you should think about how portable that is or isn't. 🫠

desc says the order should be descending. Like:

$storage->select( $object, filter => (...),
                  order => [ $remote_foo->{field1} ],
                  desc => 1  );

That one would order DESC (descending, high to low) all the fields listed in the order clause.

Passing:

desc => 0

would order all the fields ASC (ascending, low to high).

And to specify which fields go DESC and which ones go ASC, you pass an array ref to desc, like this:

$storage->select( $object, filter => (...),
                  order => [
                            $remote_foo->{field1},
                            $remote_foo->{field2},
                            $remote_foo->{field3},
                           ],
                  desc => [ 1, 0, 1 ]  );

That orders field1 and field3 descending, and field2 ascending. Chef's kiss. 👑

distinct is a boolean; a true value specifies that the same object should occur only once in the result set. In general, this is a good idea.

limit is a maximum number of rows to retrieve; in fact, with some databases you can hand it two numbers to get the rows between N and M of a select. Check your RDBMS manual for more on that. If you wanna specify more than one number, you can use this syntax:

$storage->select( $object, filter => (...),
                  limit => [ 5, 10 ] );

The example above would return rows 6 through 15 on a MySQL database. ✨

The select method is valid only in list context.

outer_filter and force_outer are EXPERIMENTAL API features.

If you pass any filter conditions into outer_filter instead of filter, then any mentioned tables get connected by an outer join. What that means: the object doesn't necessarily have to be present for the select to return a row; it may also be undef.

The force_outer option expects an array ref of Tangram::Remote objects. Those tables get joined with an outer join clause.

⚠️ The outer join related code is extremely hairy, and you are advised to make sure you test each outer join query you're going to use against new versions of Tangram.
Do not try to combine inheritance and outer joins if you want your app to run on toy databases — currently that means SQLite and MySQL. SQLite does not parse SQL nested join syntax and MySQL just gets the join all wrong. At least, on my testbed system. YMMV. 💀

🧮 sum( $expr, [$filter] ) 🧮

Returns the total of the remote expression ($expr) for all rows that match $filter, as summed by the RDBMS. $filter is optional, and if you don't pass it, the implication is to sum the value for ALL objects of that type. 🌈

my $r_thing = $storage->remote("Thing");
$sum = $storage->sum( $r_thing->{field},
                      ($r_thing->{foo} eq "bar") );

You can also pass a whole list of fields to sum, as an array ref:

($sum_expr1, $sum_expr2)
    = $storage->sum( [ $expr1, $expr2 ], $filter );

🔢 count( $expr, [$filter] ) 🔢

Works exactly like sum(), but returns the count of the given objects or columns instead of the sum. ✨

This function does not support counting multiple columns by passing an array ref. However, you can still achieve that with the ->count() remote expression function (see Tangram::Expr).

If your filter is simple enough, then you can just pass the filter in without an $expr. Iconic behaviour, honestly.

🎀 cursor 🎀

$cursor = $storage->cursor( $remote );
$cursor = $storage->cursor( $remote, $filter );
$cursor = cursor( $remote,
   opt1 => val1, op2 => val2, ...);

Valid only in scalar context.

Returns a Cursor on the objects that are type-compatible with $remote.

  • If one argument is passed, the cursor returns all the objects of the given type.
  • If two arguments are passed, the second argument must be a Filter. The cursor returns the objects that satisfy $filter and are type-compatible with the corresponding Remote.
  • If more than two arguments are passed, the arguments after $remote are treated as key/value pairs. Currently Tangram recognizes the following directives:
    • filter
    • order
    • desc
    • distinct
    • retrieve

For the options filter, order, desc and distinct, go see "select".

The retrieve option is an array of Expr, to be retrieved in addition to the object itself. 💖

🦋 prefetch 🦋

$storage->prefetch("Class", "collection", $filter);

This method fetches all the "collection" collections from "Class", where $filter.

⚠️ You need to be VERY careful with your filter — it is quite easy to end up with a filter that will include a single table twice with no join.

You should not include an expression in the filter that matches the type of object that you are prefetching, unless that is a different object to the one you want to load.

You should replace the text "Class" with a Tangram::Remote object from your $filter if it appears in the expression.

This code is OK:

my $r_parent = $storage->remote( "NaturalPerson" );
my $filter = ($r_parent->{age} > 40);

my @parent = $storage->select($r_parent, $filter);
$storage->prefetch($r_parent, "children" $filter);

But this code has the problem:

my $r_parent = $storage->remote( "NaturalPerson" );
my $r_child  = $storage->remote( "NaturalPerson" );

my $filter = (
              ($r_parent->{age} > 40) &;
               $r_parent->{children}->includes($r_child)
             );

my @parent = $storage->select($r_parent, $filter);
my @children = $storage->select($r_child, $filter);

$storage->prefetch($r_parent, "children", $filter);

Because $filter contains an extra unnecessary' relationship with <italic>$r_child`</italic>, the filter that Tangram builds internally ends up looking like:

(
 ($r_parent->{age} > 40) &
 $r_parent->{children}->includes($r_child) &
 $r_parent->{children}->includes($r_child2) &
);

So you end up including extra tables without joining them. 😭 This situation does not make any sense, but unfortunately because of the definition of how RDBMS' work, it is required behaviour for it to give you a permutation of all of the unjoined tables. <sigh> 💀

💅 erase 💅

$storage->erase( @obj );

Removes objects from persistent storage. The objects remain present in transient storage. Poof, but not really poof. 🫶

🌸 tx_start 🌸

$storage->tx_start();

Starts a new Tangram transaction. Tangram transactions can be nested, but currently this does not actually make SQL "SAVEPOINT"s (for partial transaction rollback).

Instead, Tangram maintains a transaction nesting count for each storage object and commits the operations only when that count reaches zero. This scheme makes it easy for a function to collaborate with its caller in the management of the "internal connection". ✨

Example:

sub f
{
   $storage->tx_start();
   $storage->update( $homer );
   $storage->tx_commit(); # or perhaps rollback()
}

sub g
{
   $storage->tx_start();
   f();
   $storage->update( $marge );
   $storage->tx_commit(); # or perhaps rollback()
}

f(); # 1
g(); # 2

In (1), f() commits the changes to $homer directly to the database.

In (2), f() transparently reuses the transaction opened by g(). Changes to both $homer and $marge are committed to the database when g() calls tx_commit(). The way that just… works? Obsessed. 💖

By default with ACID compliant database back-ends (such as Pg, MySQL/InnoDB, Oracle and pretty much any commercial RDBMS), the first time you open a database connection, you are beginning a transaction. However, this is not the case with the Tangram::SQLite or Tangram::mysql back-ends, both of which do not implement transaction isolation; therefore it is not good to assume that the database can handle concurrent writing efficiently.

To be run safely on these non-compliant back-ends, you should explicitly tx_start() at the beginning of transaction blocks rather than relying on the default behaviour. Don't skip this one, bestie. 🙈

🌈 tx_commit 🌈

$storage->tx_commit();

Commits the current Tangram transaction for this storage. If the transaction being committed is the outermost transaction for this storage, the DBI transaction is also committed.

When using the SQLite back-end, when the DBI transaction is committed, the connection is also marked read-only (ie, AutoCommit is enabled). 👑

🧚 tx_rollback 🧚

$storage->tx_rollback();

Rolls back the current Tangram transaction for this storage. If the transaction being rolled back is the outermost transaction for this storage, the DBI transaction is also rolled back. Undo-undo, babe. ✨

⭐ tx_do ⭐

$storage->tx_do( sub { ... } );

Executes CODEREF under the protection of a Tangram transaction and passes it @args in the argument list.

Rolls back the transaction if CODEREF dies; in which case the exception is re-thrown.

Returns the results of CODEREF, either as a scalar or as a list depending on the context in which tx_do was called.

Example:

$storage->tx_do(
   sub
   {
      $storage->update( $homer );
      # do things, die perhaps
      $storage->update( $marge );
   } );

Lowkey the safest way to do your writes. Protect your peace (and your rows). 🫶🌸

Both $homer and $marge will be updated, or none will, depending on whether the anonymous subroutine passed to tx_do() dies. 👑

🧹 unload

$storage->unload( @obj );

Okay so this one drops references to persistent objects present in memory. @objs may contain both objects and object ids. If @objs is empty, unloads all the objects loaded by this storage. ✨

Storage keeps track of all the persistent objects that are present in memory, in order to make sure that loading the same object twice results in a single copy of the object. No cap.

As a consequence, these objects will not be reclaimed by Perl's automatic memory management mechanism until either disconnect() or unload() is called.

Bestie listen 💀 unload() should be called only when no other references exist to persistent objects, otherwise the same object (in the database) may end up having two copies in transient storage, or vice versa!

In most cases, you never want to use this function - letting objects pass out of scope and be cleaned up is a much more natural way to let the object cache take care of itself. It's giving self-care tbh 🫶

🫧 unload_all( [ $notify_method ])

Drops references to all objects in the object cache. If you pass a notify method, then this will be passed to all objects as they are dumped (so long as they "->can()" handle it). This can be used, for instance, with Class::Tangram objects to make sure all circular references in cached objects are cleared, if you pass "clear_refs" as the $notify_method. 🌈

Similar warnings apply to this function as "$storage->unload()".

This function is particularly useful in OLTP (online transaction processing) servers. In those, it should be called before the first "$storage->tx_start()", so that all objects are known to be "fresh" in the current transaction. Due to ACID guarantees of consistent reads etc (not on MySQL/MyISAM!), you should then not have the classic "dirty read" problem - so long as you wrap the entire transaction in a function that catches a failure on "-e<gt"tx_commit()> and attempts a retry (make sure to clear the cache again before a retry!). 🔥

You might also want to see your RDBMS manual under the topic of "transaction isolation", in particular the SQL command "SET TRANSACTION ISOLATION LEVEL".

🔌 disconnect

$storage->disconnect();

Disconnects from the database. Drops references to persistent objects present in memory (see "unload"). Bye felicia 👋

And that's the whole page, bestie! This was Tangram::Storage(3pm), Perl v5.36.0, dated 2022-10-16. Go forth and persist your objects like a main character 💅👑

📦 where this page comes from