# man > Apache::Session

---
type: CommandReference
command: Apache::Session
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference
- `tie %session, 'Apache::Session::MySQL';` — create a new session
- `$id = $session{_session_id};` — retrieve the session ID
- `tie %session, 'Apache::Session::MySQL', $id;` — restore an existing session
- `$session{visa_number} = "1234 5678 9876 5432";` — store arbitrary data
- `tied(%session)->delete;` — permanently remove the session from storage
- `tie %s, 'Apache::Session::File', $id, { Transaction => 1 };` — enable transactional consistency
- `tie %global_data, 'Apache::Session::File', 1, { Directory => '/tmp/sessiondata' };` — share data across Apache processes

## Name
`Apache::Session` — A persistence framework for session data

## Synopsis
perl
use Apache::Session::MySQL;

my %session;
tie %session, 'Apache::Session::MySQL';

$session{visa_number} = "1234 5678 9876 5432";
my $id = $session{_session_id};

# later
my %session;
tie %session, 'Apache::Session::MySQL', $id;
validate($session{visa_number});

tied(%session)->delete;
## Options
Constructor options passed as a hashref to `tie`:
- `DataSource` — DBI data source name (e.g., `'dbi:mysql:sessions'`)
- `UserName` — database username
- `Password` — database password
- `LockDataSource` — separate DSN for locking, if required
- `LockUserName` — username for the lock database
- `LockPassword` — password for the lock database
- `Directory` — filesystem path for file-based stores
- `LockDirectory` — filesystem path for lockfiles
- `Transaction` — boolean; enable transactional semantics where supported

## Interface
- `tie %hash, $class, $id, $options` — tie a hash to a session. `$id` is undef for a new session, or a string for an existing one. `$options` is an optional hashref.
- `$session{_session_id}` — the magic key holding the session identifier. Other keys beginning with `_` are reserved.
- `tied(%hash)->delete()` — immediately remove the session from the backing store.
- Data is automatically saved when the hash goes out of scope (on `untie` or destruction), if a shallow change is detected.

## Behavior
- A newly created session is immediately written to the store (or `die` on failure) and an exclusive lock is acquired.
- An existing session is restored immediately (or `die`) and a non‑exclusive lock is acquired.
- When the hash is destroyed, if the hash has been modified (shallow check), an exclusive lock is acquired and the session is written to the store.
- Errors result in `die`; wrap session logic in `eval` blocks.

## Locking and Transactions
- Default locking only prevents data corruption, not providing full transactional consistency.
- Set `Transaction => 1` in the options hash to request transactional semantics (ignored by MySQL, used internally by Postgres).
- MySQL implementation uses exclusive locking only.

## Examples

### Sharing data between Apache processes
perl
use Apache::Session::File;
use DBI;

my %global_data;
eval {
    tie %global_data, 'Apache::Session::File', 1,
       { Directory => '/tmp/sessiondata' };
};
die "Global data inaccessible: $@" if $@;

my $dbh = DBI->connect(
    $global_data{datasource},
    $global_data{username},
    $global_data{password}
) || die $DBI::errstr;

undef %global_data;
### Tracking users with cookies (mod_perl)
perl
use Apache::Session::MySQL;
use Apache;

my $r = Apache->request;
my $cookie = $r->header_in('Cookie');
$cookie =~ s/SESSION_ID=(\w*)/$1/;

my %session;
tie %session, 'Apache::Session::MySQL', $cookie, {
    DataSource     => 'dbi:mysql:sessions',
    UserName       => 'mySQL_user',
    Password       => 'password',
    LockDataSource => 'dbi:mysql:sessions',
    LockUserName   => 'mySQL_user',
    LockPassword   => 'password'
};

my $session_cookie = "SESSION_ID=$session{_session_id};";
$r->header_out("Set-Cookie" => $session_cookie);
## See Also
- [Apache::Session::MySQL](http://localhost/phpMan.php/perldoc/Apache%3A%3ASession%3A%3AMySQL/markdown)
- [Apache::Session::Postgres](http://localhost/phpMan.php/perldoc/Apache%3A%3ASession%3A%3APostgres/markdown)
- [Apache::Session::File](http://localhost/phpMan.php/perldoc/Apache%3A%3ASession%3A%3AFile/markdown)
- [Apache::Session::DB_File](http://localhost/phpMan.php/perldoc/Apache%3A%3ASession%3A%3ADBFile/markdown)
- [Apache::Session::Oracle](http://localhost/phpMan.php/perldoc/Apache%3A%3ASession%3A%3AOracle/markdown)
- [Apache::Session::Sybase](http://localhost/phpMan.php/perldoc/Apache%3A%3ASession%3A%3ASybase/markdown)
- [CGI::Session](http://localhost/phpMan.php/perldoc/CGI%3A%3ASession/markdown)
- [Catalyst::Plugin::Session](http://localhost/phpMan.php/perldoc/Catalyst%3A%3APlugin%3A%3ASession/markdown)