Cataly...::DBIC(3pm)

💖 NAME 💖

Catalyst::Plugin::Session::Store::DBIC — bestie, this is the one that stores your sessions via DBIx::Class. It's giving "your sessions, but make it a database row" ✨ (this page lives in the User Contributed Perl Documentation corner of the manual, iykyk)

---

🌸 SYNOPSIS 🌸

okay so first you gotta make a table. do it. no cap:

# Create a table in your database for sessions
CREATE TABLE sessions (
    id           CHAR(72) PRIMARY KEY,
    session_data TEXT,
    expires      INTEGER
);

# Create the corresponding table class
package MyApp::Schema::Session;

use base qw/DBIx::Class/;

__PACKAGE__->load_components(qw/Core/);
__PACKAGE__->table('sessions');
__PACKAGE__->add_columns(qw/id session_data expires/);
__PACKAGE__->set_primary_key('id');

1;

# In your application
use Catalyst qw/Session Session::Store::DBIC Session::State::Cookie/;

__PACKAGE__->config(
    # ... other items ...
    'Plugin::Session' => {
        dbic_class => 'DBIC::Session',  # Assuming MyApp::Model::DBIC
        expires    => 3600,
    },
);

# Later, in a controller action
$c->session->{foo} = 'bar';

like, that's it. that's the whole vibe check 💅

---

🦋 DESCRIPTION 🦋

So this little Catalyst::Plugin::Session storage module 👑 saves your session data straight into your database, going through DBIx::Class. Obsessed.

but ngl, it's actually just a wrapper around Catalyst::Plugin::Session::Store::Delegate. So if you want total, absolute, main-character control over how your sessions get stored, you probably want to use that one directly instead. fr fr.

---

✨ METHODS ✨

🎀 setup_finished

Hook into the configured session class. Cute, does its little thing.

🎀 session_store_dbic_class

Returns the DBIx::Class class name that gets passed to $c->model. Defaults to DBIC::Session.

🎀 session_store_dbic_id_field

Returns the configured ID field name. Defaults to id.

🎀 session_store_dbic_data_field

Returns the configured data field name. Defaults to session_data.

🎀 session_store_dbic_expires_field

Returns the configured expires field name. Defaults to expires.

🎀 session_store_model

Returns the model used to find a session.

🎀 get_session_store_delegate

Loads the row that corresponds to the session ID you specified. And if there isn't one? It just makes one for you automatically. generous queen 🫶

🎀 session_store_delegate_key_to_accessor

Matches the key and operation you gave it to the session ID and field name. slay.

🎀 delete_session_data

Deletes the specified session from the backend store. bye bestie 👋

🎀 delete_expired_sessions

Deletes all the expired sessions. spring cleaning energy 🧚

---

🌈 CONFIGURATION 🌈

These parameters should go in your application configuration, under the Plugin::Session key. yes, that exact key. don't be quirky about it.

🍓 dbic_class

(Required) — the name of the DBIx::Class that represents a session in the database. And the recommendation is you only give the part after MyApp::Model, like DBIC::Session.

If you're using Catalyst::Model::DBIC::Schema, this layout is the one:

• MyApp::Schema — your DBIx::Class::Schema class
• MyApp::Schema::Session — your session table class
• MyApp::Model::DBIC — your Catalyst::Model::DBIC::Schema class

This module will then use $c->model to reach the appropriate result source from the composed schema matching that dbic_class name. 💫

For more info, go peek at Catalyst::Model::DBIC::Schema.

🍓 expires

The number of seconds your sessions stay active.

Heads up bestie: there is no automatic cleanup of your session data. None. Zero. To delete expired sessions you can use the delete_expired_sessions method together with Catalyst::Plugin::Scheduler.

🍓 id_field

The name of the field on your sessions table that stores the session ID. Defaults to id.

🍓 data_field

The name of the field on your sessions table that stores session data. Defaults to session_data, for compatibility with Catalyst::Plugin::Session::Store::DBI.

🍓 expires_field

The name of the field on your sessions table that stores the expiration time of the session. Defaults to expires.

---

👑 SCHEMA 👑

Your sessions table should have these columns, periodt:

id           CHAR(72) PRIMARY KEY
session_data TEXT
expires      INTEGER

The id column should probably be 72 characters. Why? Because it needs to handle the longest string generate_session_id in Catalyst::Plugin::Session can return, plus another eight characters for internal use. With SHA-1 or MD5 that's less than 72 characters, but SHA-256 will need all 72 of them. every last one 😤

The session_data column should be a long text field. Your session data gets encoded with MIME::Base64 before it lands in the database.

⚠️ Not me warning you: MySQL TEXT fields only store 64 kB. So if your session data is gonna exceed that, you want MEDIUMTEXT, MEDIUMBLOB, or something bigger. And if you configure your DBIx::Class::ResultSource to include the column size, you'll get warnings about this problem:

This session requires 1180 bytes of storage, but your database
column 'session_data' can only store 200 bytes. Storing this
session may not be reliable; increase the size of your data field

See add_columns in DBIx::Class::ResultSource for more info.

The expires column stores the future expiration time of the session. It can be null for per-user and flash sessions. 💀

And note — yes, you can rename these columns using the id_field, data_field, and expires_field configuration parameters. But the column types still have to match the above. no negotiating.

---

💜 AUTHOR 💜

Daniel Westermann-Clark <danieltwc@cpan.org>

---

🎀 ACKNOWLEDGMENTS 🎀

• Andy Grundman, for Catalyst::Plugin::Session::Store::DBI
• David Kamholz, for most of the testing code (from Catalyst::Plugin::Authentication::Store::DBIC)
• Yuval Kogman, for assistance in converting to Catalyst::Plugin::Session::Store::Delegate
• Jay Hannah, for tests and warning when session size exceeds DBIx::Class storage size.

---

🌸 COPYRIGHT 🌸

Copyright (c) 2006 - 2009 the Catalyst::Plugin::Session::Store::DBIC AUTHOR as listed above.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

okay that's the whole page bestie, you're so ready 🫶 this was perl v5.34.0, dated 2022-06-09 — go forth and store those sessions 💅✨