Alzabo...e::Row(3pm)

✨ Alzabo::Runtime::Row — the whole vibe ✨

Row objects, bestie. That's the name of the game, and this page is from the User Contributed Perl Documentation corner of the world. Sit down, grab a strawberry 🍓, and let's get into it.

---

🦋 SYNOPSIS 🦋

use Alzabo::Runtime::Row;

my $row = $table->row_by_pk( pk => 1 );

$row->select('foo');

$row->update( bar => 5 );

$row->delete;

That's the whole lil tour, no cap. 💅

---

💖 DESCRIPTION 💖

Okay so these objects represent actual rows from the database containing actual data. Like, the real deal, not a concept.

In general though, you're gonna want to use the Alzabo::Runtime::Table object to go get your rows — it's giving main character energy for retrieval. And the Alzabo::Runtime::Table object can hand you back either single rows or row cursors, whichever you need. 🫶

---

🌈 ROW STATES 🌈

Row objects can be in a whole variety of states, and honestly the vibe check changes depending on which one you're in.

Most row objects are "live", which means they represent an actual row object. Iconic. ✨

A row can be changed to the "deleted" state by calling its delete() method. That's a row that no longer exists in the database. And heads up: most method calls on rows in this state cause an exception. 💀

There's also a "potential" state, for objects which do not represent actual database rows. You can call make_live() on these rows to change their state to "live". Glow up, honestly. 🧚

Finally, there's an "in cache" state, which is identical to the "live" state, except that it's used for object's that are cached via the Alzabo::Runtime::UniqueRowCache class. Same energy, different closet.

---

👑 METHODS 👑

Row objects offer the following methods, and yes, we're doing all of them:

select (@list_of_column_names)

Returns a list of values matching the specified columns in a list context. In scalar context it returns only a single value (the first column specified). Pick your fighter.

If no columns are specified, it will return the values for all of the columns in the table, in the order that are returned by Alzabo::Runtime::Table->columns. Surprise, it's everything.

This method throws an Alzabo::Runtime::NoSuchRowException if called on a deleted row. 🚫

select_hash (@list_of_column_names)

Returns a hash of column names to values matching the specified columns. Key-value slay.

If no columns are specified, it will return the values for all of the columns in the table.

This method throws an Alzabo::Runtime::NoSuchRowException if called on a deleted row.

update (%hash_of_columns_and_values)

Given a hash of columns and values, attempts to update the database to and the object to represent these new values.

It returns a boolean value indicating whether or not any data was actually modified. So like, true = something moved, false = nothing changed, we stay unbothered. 💅

This method throws an Alzabo::Runtime::NoSuchRowException if called on a deleted row.

refresh

Refreshes the object against the database. This can be used when you want to ensure that a row object is up to date in regards to the database state. It's the "bestie what did I miss" of methods.

This method throws an Alzabo::Runtime::NoSuchRowException if called on a deleted row.

delete

Deletes the row from the RDBMS and changes the object's state to deleted. Gone, bye. 👋

For potential rows, this method simply changes the object's state.

This method throws an Alzabo::Runtime::NoSuchRowException if called on a deleted row.

id_as_string

Returns the row's id value as a string. This can be passed to the Alzabo::Runtime::Table->row_by_id method to recreate the row later. Save it for later, bestie, it's your little receipt. 🎀

For potential rows, this method always return an empty string.

This method throws an Alzabo::Runtime::NoSuchRowException if called on a deleted row.

is_live

Indicates whether or not the given row represents an actual row in the database.

is_potential

Indicates whether or not the given row represents an actual row in the database.

is_deleted

Indicates whether or not the given row has been deleted

table

Returns the Alzabo::Runtime::Table object that this row belongs to.

schema

Returns the Alzabo::Runtime::Schema object that this row's table belongs to. This is a shortcut for $row->table->schema. Lowkey convenient, highkey correct.

rows_by_foreign_key

This method is used to retrieve row objects from other tables by "following" a relationship between two tables. We're stalking the graph, respectfully. 🦋

It takes the following parameters:

• foreign_key => Alzabo::Runtime::ForeignKey object

Given a foreign key object, this method returns either a row object or a row cursor object the row(s) in the table to which the relationship exist.

The type of object returned is based on the cardinality of the relationship. If the relationship says that there could only be one matching row, then a row object is returned, otherwise it returns a cursor. One = row, many = cursor. Simple math, periodt.

---

🧚 POTENTIAL ROWS 🧚

The "potential" row state is used for rows which do not yet exist in the database. These are created via the Alzabo::Runtime::Table->potential_row method. Manifesting, basically. ✨

They are useful when you need a placeholder object which you can update and select from, but you don't actually want to commit the data to the database.

These objects are not cached.

Once make_live() is called, the object's state becomes "live".

Potential rows have looser constraints for column values than regular rows. When creating a new potential row, it is ok if none of the columns are defined. If a column has a default, and a value for that column is not given, then the default will be used. However, you cannot update a column in a potential row to undef (NULL) if the column is not nullable. That one will bite you. 🙈

No attempt is made to enforce referential integrity constraints on these objects.

You cannot set a column's value to a database function like NOW(), because this requires interaction with the database. No touching, it's not time yet.

make_live

This method inserts the row into the database and changes the object's state to "live". The glow up is real. 👑

This means that all references to the potential row object will now be references to the real object (which is a good thing).

This method can take any parameters that can be passed to the Alzabo::Runtime::Table->insert method.

Any columns already set will be passed to the insert method, including primary key values. However, these will be overridden, on a column by column basis, by a pk or values parameters given to the make_live() method.

⚠️ Calling this method on a row object that is not in the "potential" state will cause an Alzabo::Runtime::LogicException. Do not test this for fun. I know you want to.

---

💜 AUTHOR 💜

Dave Rolsky, <autarch@urth.org>

---

And that's the whole page, bestie. This one's perl v5.34.0, dated 2022-06-14 — so when you cite your sources, cite those. Stay iconic, go read your rows, and don't call delete() on something you still need. 🫶💖✨