Cataly...re::DBI(3pm)

💖 Catalyst::Plugin::Session::Store::DBI 💖

hiii bestie 🫶 welcome to the manual page for Catalyst::Plugin::Session::Store::DBI, straight out of the User Contributed Perl Documentation, manual section 3pm. it's a Catalyst plugin that keeps your session data in a database and honestly? it ate. let's get into it 💅

---

✨ NAME ✨

Catalyst::Plugin::Session::Store::DBI — store your sessions in a database. no cap, that's the whole job and it does it flawlessly 👑

---

🌸 SYNOPSIS 🌸

okay so first you gotta make a table for your sessions:

# Create a table in your database for sessions
CREATE TABLE sessions (
    id           char(72) primary key,
    session_data text,
    expires      int(10)
);

then in your app, you load up the plugins:

# In your app
use Catalyst qw/Session Session::Store::DBI Session::State::Cookie/;

you can connect directly to the database, like so:

# Connect directly to the database
MyApp->config('Plugin::Session' => {
    expires   => 3600,
    dbi_dsn   => 'dbi:mysql:database',
    dbi_user  => 'foo',
    dbi_pass  => 'bar',
    dbi_table => 'sessions',
    dbi_id_field => 'id',
    dbi_data_field => 'session_data',
    dbi_expires_field => 'expires',
});

or, and this is the move honestly, reuse an existing database handle from a DBIC/CDBI class:

# Or use an existing database handle from a DBIC/CDBI class
MyApp->config('Plugin::Session' => {
    expires   => 3600,
    dbi_dbh   => 'DBIC', # which means MyApp::Model::DBIC
    dbi_table => 'sessions',
    dbi_id_field => 'id',
    dbi_data_field => 'session_data',
    dbi_expires_field => 'expires',
});

and then just, like, use it? in an action:

# ... in an action:
$c->session->{foo} = 'bar'; # will be saved

look at her go 😭✨

---

🦋 DESCRIPTION 🦋

this storage module stores your session data in a database using DBI. that's it, that's the vibe. iconic behavior fr fr 💜

---

🎀 CONFIGURATION 🎀

all of these parameters go inside the configuration hash, under the "Plugin::Session" key. yes, that key. you got this 💪

⭐ expires

the expires column in your table gets set to the expiration value. and listen — no automatic cleanup is done on your session data 🙈 but bestie, you're not stuck, because you can call the delete_expired_sessions method to do the clean-up yourself. you can also use the Catalyst::Plugin::Scheduler plugin to schedule automated session cleanup, which is the "girl who has her life together" move 💅

⭐ dbi_dbh

set this to an existing $dbh, or to the class name of a DBIx::Class, Class::DBI, Rose::DB::Object, or Catalyst::Model::DBI model. and yes, DBIx::Class schema is also supported — just set dbi_dbh to the name of your schema model ✨

this one is recommended if you've got other database code in your application, because it avoids opening additional connections. less connections, less drama, we love to see it 🫶

⭐ dbi_dsn

⭐ dbi_user

⭐ dbi_pass

⭐ dbi_options

want to connect directly to a database? then specify the necessary dbi_dsn, dbi_user, and dbi_pass options. and if you need to supply your own options to DBI, you can do that by passing a hashref to dbi_options. the default options are AutoCommit => 1 and RaiseError => 1. defaults are cute like that 🌸

⭐ dbi_table

put in the table name from your database where sessions will live. this table must have at least 3 columns: id, session_data, and expires. peep the Schema section below for more deets. the table name defaults to 'sessions'.

⭐ dbi_id_field

the name of the field on your sessions table that stores the session ID. defaults to "id". 💖

⭐ dbi_data_field

the name of the field on your sessions table that stores session data. defaults to "session_data". 💖

⭐ 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 must contain at minimum these 3 columns:

id           char(72) primary key
session_data text
expires      int(10)

the 'id' column should probably be 72 characters. it needs to handle the longest string that can be returned by "generate_session_id" in Catalyst::Plugin::Authentication, plus another 8 characters for internal use. that's less than 72 characters in practice when SHA-1 or MD5 are used, but SHA-256 will need all those characters. so like, plan ahead bestie 📏✨

the 'session_data' column should be a long text field. session data is encoded using Base64 before being stored in the database. sneaky but correct 💅

⚠️ heads up! MySQL TEXT fields only store 64KB. so if your session data is gonna exceed that size, you'll want to move on up to MEDIUMTEXT, MEDIUMBLOB, or larger. glow-up for your column 🔥

the 'expires' column stores the future expiration time of the session. this may be null for per-user and flash sessions. flexible king 👑

NOTE: your column names do not need to match this schema! use config to set custom column names. your table, your rules 🎀

---

💜 METHODS 💜

🍓 get_session_data

🍓 store_session_data

🍓 delete_session_data

🍓 delete_expired_sessions

🍓 setup_session

these are implementations of the required methods for a store. go see Catalyst::Plugin::Session::Store if you want the full lore 📚

🍓 session_store_dbi_table

returns the configured table name. ✨

🍓 session_store_dbi_id_field

returns the configured ID field name. ✨

🍓 session_store_dbi_data_field

returns the configured data field name. ✨

🍓 session_store_dbi_expires_field

returns the configured expires field name. ✨

---

🧚 INTERNAL METHODS 🧚

🔥 prepare

🔥 setup_actions

(these are internal, so like… don't touch, okay? 🙈)

---

👑 SEE ALSO 👑

• Catalyst
• Catalyst::Plugin::Session
• Catalyst::Plugin::Scheduler

---

🌟 AUTHOR 🌟

Andy Grundman, <andy@hybridized.org>. thank you for your service, legend 🫡💖

---

💌 COPYRIGHT 💌

Copyright (c) 2005 - 2009 the Catalyst::Plugin::Session::Store::DBI "AUTHOR" as listed above.

this program is free software, you can redistribute it and/or modify it under the same terms as Perl itself. slay, open source icon 🌈

---

and that's the whole page bestie, no notes 💅 this was perl v5.26.2, dated 2018-06-08 — yeah she's a lil vintage but she still serves 🎀✨ bye pookie, go store some sessions 🦋💖