File Coverage

blib/lib/Prancer/Session/Store/Database.pm

Criterion	Covered	Total	%
statement	9	9	100.0
branch			n/a
condition			n/a
subroutine	3	3	100.0
pod			n/a
total	12	12	100.0

line	stmt	sub	time	code
1				package Prancer::Session::Store::Database;
2
3	1	1	15616	use strict;
	1		2
	1		39
4	1	1	3	use warnings FATAL => 'all';
	1		2
	1		35
5
6	1	1	421	use version;
	1		1538
	1		6
7				our $VERSION = '1.00';
8
9				1;
10
11				=head1 NAME
12
13				Prancer::Session::Store::Database
14
15				=head1 SYNOPSIS
16
17				This module implements a session handler that stores sessions in a database. It
18				creates its own database connection, separate from any existing database
19				connection, to avoid any issues with transactions. It wraps all changes to the
20				database in transactions to ensure consistency.
21
22				This configuration expects a database table that looks like this:
23
24				CREATE TABLE session (
25				id CHAR(72) NOT NULL,
26				application VARCHAR DEFALUT '' NOT NULL,
27				timeout integer DEFAULT date_part('epoch'::text, now()) NOT NULL,
28				data TEXT
29				);
30
31				CREATE UNIQUE INDEX session_uq ON sessions (id, application);
32				CREATE INDEX session_timeout_ix ON sessions (timeout);
33
34				Additional columns may be added as desired but they will not be used by this
35				session handler.
36
37				To use this session handler, add this to your configuration file:
38
39				session:
40				store:
41				driver: Prancer::Session::Store::Database::Driver::DriverName
42				options:
43				table: sessions
44				database: test
45				username: test
46				password: test
47				hostname: localhost
48				port: 5432
49				charset: utf8
50				connection_check_threshold: 10
51				expiration_timeout: 3600
52				autopurge: 0
53				autopurge_probability: 0.1
54				application: foobar
55
56				=head1 OPTIONS
57
58				=over
59
60				=item table
61
62				The name of the table in your database to use to store sessions. This name may
63				include a schema name, like C. Otherwise the default schema of
64				the database user will be used. If this option is not provided then the default
65				table name is C.
66
67				=item database
68
69				B The name of the database to connect to. If using SQLite, this
70				should be the path to the database file.
71
72				=item username
73
74				The username to use when connecting. If this option is not set the default is
75				the user running the application server. If using SQLite then this will be
76				ignored.
77
78				=item password
79
80				The password to use when connecting. If this option is not set the default is
81				to connect with no password. If using SQLite then this will be ignored.
82
83				=item hostname
84
85				The host name of the database server. If this option is not set the default is
86				to connect to localhost. If using SQLite then this will be ignored.
87
88				=item port
89
90				The port number on which the database server is listening. If this option is
91				not set the default is to connect on the database's default port. If using
92				SQLite then this will be ignored.
93
94				=item charset
95
96				The character set to connect to the database with. If this is set to "utf8"
97				then the database connection will attempt to make UTF8 data Just Work if
98				available.
99
100				=item connection_check_threshold
101
102				This sets the number of seconds that must elapse between calls to get a
103				database handle before performing a check to ensure that a live database
104				connection still exists. If the check for a live database connection fails then
105				the session handler will attempt to reconnect. This handles cases where the
106				database handle hasn't been used in a while and the underlying connection has
107				gone away. If this is not set it will default to 30 seconds.
108
109				=item timeout
110
111				Tthis is the number of seconds a session should last in the database before it
112				will be automatically purged. The default is to purge sessions after 1800
113				seconds (30 minutes).
114
115				=item autopurge
116
117				This flag controls whether sessions will be automatically purged by Prancer.
118				If set to 1, the default, then on 10% of requests to your application, Prancer
119				will delete from the database any session that has timed out. If set to 0 then
120				sessions will never be removed from the database. Note that this doesn't
121				control whether sessions time out, only whether they get removed from the
122				database.
123
124				=item autopurge_probability
125
126				This is the probability that autopurge will run on any given request. By
127				default, this value is 0.1, or 10%, meaning that 1 in every 10 requests will
128				attempt to purge expired sessions. This can be set to "1" to purge on every
129				session action or to something extremely small like 0.001 to purge very, very
130				infrequently. Or you can export purging duties to another program entirely.
131
132				=item application
133
134				If multiple applications will be using the same session table then this option
135				may be used to distinguish between them. This key will be used in the
136				C column of the sessions table.
137
138				=back
139
140				=head1 COPYRIGHT
141
142				Copyright 2014 Paul Lockaby. All rights reserved.
143
144				This library is free software; you can redistribute it and/or modify it under
145				the same terms as Perl itself.
146
147				=head1 SEE ALSO
148
149				=over
150
151				=item L
152				=item L
153
154				=back
155
156				=cut