PostgreSQL database session save handler module
[What is it]
session_pgsql is an additional session save handler module. It
provides session storage using PostgreSQL database server(s).
- C implantation of session save handler with PostgreSQL. It could
twice as fast or more compare to script version of save handler.
- Automatic session table creation.
- Better garbage collection.
- Multiple PostgreSQL servers support.
- Automatic db server failover(switching) when there is trouble.
- Automatic db server load balancing where there are multiple
PostgreSQL servers.
- Automatic session table vacuum.
- Short circuit UPDATE
It is design to scale any size of web sites.
[Requirements]
PHP 4.3.0 or later
PostgreSQL 7.2.0 or later as server
libpq that comes with PostgreSQL 7.2.0 or later (and header to build)
libmm (and header. I use mm-1.2.1)
[How to compile]
To compile PHP with mod_pgsql, you need "--with-session-pgsql[=DIR]"
when you configure PHP. [=DIR] is installation path for
PostgreSQL. You don't have to compile PHP with PostgreSQL module, but
your system must have libpq and headers installed. It also uses libmm
your system must have libmm and headers installed to compile.
1. Change directory to <php source root>/ext and move tar ball to
there.
2. Unpack session_pgsql source
% tar zxvf session_pgsql-<version>.tar.bz2
You may need to bunzip first if your tar don't recognize bz2
compression
3. Change directory to <php source root> then
% ./buildconf
% ./configure --with-session-pgsql <other configure options>
% make
% make install
4. If you choose to build stand alone module with "--with-session-pgsql=shared"
Do not forget to edit php.ini to load session_pgsql.so.
5. Reboot your web server.
You may also want to compile session pgsql as stand alone PHP module.
To compile session_pgsql as stand alone module without PHP source, you
need PHP header and build tools installed. These files are install when
"make install" is done with PHP source. If you are using RPM, these files
are likely included in php-devel package.
1. Unpack session_pgsql source.
% tar zxvf session_pgsql-<version>.tar.bz2
2. Change directory to session_pgsql
% cd session_pgsql
3. Run phpize. This will creates configure script and files needed.
% phpize
4. Run configure script, build and install module
% ./configure --with-session-pgsql
% make
% make install
This will build and install session_pgsql.so module and install
the module file to php module directory.
5. Edit your php.ini to load session_pgsql. Add following line to
php.ini
extension=session_pgsql.so
6. Verify with phpinfo() if session_pgsql is loaded or not. If it's
not loaded, try to use full path to load module.
7. Reboot your web server.
Finally, do no forget to edit session_pgsql.db php.ini directive.
See following sections for the ini directive usage.
[How to use]
Once you have successfully installed session_pgsql (and PHP of course)
and PostgreSQL to localhost. All you have to do is (as postgres super user)
% createuser nobody
% createdb php_session
In your php.ini
session.save_handler = pgsql
or
In your script (make sure you call it *before* staring session)
session_module_name('pgsql');
session_pgsql connects to local PostgreSQL backend and create session
table automatically if needed. If you would like to use remote PostgreSQL
server or even multiple PostgreSQL servers, edit session_pgsql.db php.ini
configuration directive.
NOTE: It cannot be used with CGI/CLI binary or dl() or loading from .htaccess.
NOTE: It's good idea to have more secure setting. Change security options
according your security needs.
[php.ini settings]
Following php.ini directives are recognized by session and session_pgsql
module.
session.save_handler
"pgsql" for session_pgsql session.
session.*
save_path is ignored. Other session.* settings are also used for
session_pgsql.
session_pgsql.db
Valid PostgreSQL database connection string.
For example, "host=localhost dbname=php_session user=nobody" can
be set. This example is the default.
You can specify multiple PostgreSQL by separating ";". e.g.
"host=server1 dbname=php_session user=nobody;host=server2 dbname=php_session user=nobody"
If multiple servers are set, session_pgsql automatically balance
db server loads. If one of session db server fails, it will try to
use available db server automatically.
NOTE: database name must be "php_session". Other connection options
may be changed.
NOTE: If you have multiple web/db servers, make sure session_pgsql.db
is the same value for all web servers.
Default is "host=localhost dbname=php_session user=nobody"
session_pgsql.keep_expired
Keep expired data except session values. Counter, created time, created
IP address, etc is kept when this is set to on. If this option is off
session record is deleted and insert record is created.
Default is off.
session_pgsql.use_app_vars
Use application level variable ($_APP) or not.
Use different session name to change application.
i.e. use session_name('AppName')
Use of application variable has severe performance penalty.
Default is off.
session_pgsql.create_table
Automatically create session and application variable table
if set to on. session_pgsql creates tables, php_session and php_app_vers,
in the database. Default is on.
session_pgsql.short_circuit
If short_circuit is set to on, it will skip UPDATE statement when
skipping is possible. Setting error or custom field value or SESSION
array will make session_pgsql save changes to table, otherwise
it will not update table. Access counter and expire field will not
be updated when update is skipped.
Default is off.
session_pgsql.failover_mode
If failover_mode is set to on, it will always use 1st db server
and if 1st server fails, it will use next available db server.
create session and application variable table
if set to on. If this option is enabled, load balancing session
db server will not be enabled. Default is off.
NOTE: session_pgsql do not mirror session data. It just switch
to other database server to continue web services.
Default is off.
session_pgsql.gc_interval
How often perform GC in seconds.
If you set multiple db servers to session_pgsql.db, set only
one of your web server to prevent unneeded garbage collections.
It is good idea set to 0 (disable) and perform garbage collection
by using cron or like in db server if you have multiple web servers
accessed to the session db server(s).
NOTE: It's good idea performing garbage collection using cron or like.
Default is 3600 seconds (1 hour).
session_pgsql.vacuum_interval
How often perform GC in seconds.
If you set multiple db servers to session_pgsql.db, set only
one of your web server to prevent unneeded vacuum operations.
It is good idea set to 0 (disable) and perform vacuum
by using cron or like in db server if you have multiple web servers
accessed to the session db server(s).
NOTE: It's good idea performing vaccum and reindex using cron or like.
Default is 21600 seconds (6 hours).
[Module Functions]
/* {{{ proto array session_pgsql_status(void)
Returns current pgsql save handler status */
/* {{{ proto bool session_pgsql_reset(void)
Reset connection to session database servers */
/* {{{ proto array session_pgsql_info(void)
Returns current session info */
/* {{{ proto bool session_pgsql_set_field(string value)
Set custom field value */
/* {{{ proto string session_pgsql_get_field(void)
Get custom field value */
/* {{{ proto bool session_pgsql_add_error(int error_level [, string error_message])
Increments error counts and sets last error message */
/* {{{ proto array session_pgsql_get_error([bool with_error_message])
Returns number of errors and last error message */
[Known Problem]
Please report problem to the author.
[Session Table Definition]
CREATE TABLE php_session (
sess_id text,
sess_name text,
sess_data text,
sess_created integer,
sess_modified integer,
sess_expire integer,
sess_addr_created text,
sess_addr_modified text,
sess_counter integer,
sess_error integer,
sess_warning integer,
sess_notice integer,
sess_err_message text,
sess_custom text
);
CREATE INDEX php_session_idx ON php_session USING BTREE (sess_id);
[Application Variable Table Definition]
CREATE TABLE php_app_vars (
app_modified integer,
app_name text,
app_vars text
);
NOTE: If you use HASH for index, you'll have deadlock problem when
server load *very* high. Even if it's unlikely to have deadlock under
normal operation, but it can. DO NOT USE HASH INDEX.
User may change session table as long as all fields are defined.
[ToDo]
- More efficient application variable handling
[History]
1.0.0 - 2003/?/??
- Stable release.
0.6.1 - 2003/1/19
- Stable release candidate.
0.6.0 - 2003/1/18
- Stable release candidate.
0.5.2 - 2003/1/17
- Fixed shared module build.
0.5.1 - 2003/1/17
- Fixed short_circuit option.
0.5.0 - 2003/1/17
- Added short_circuit option.
0.4.1 - 2003/1/16
- Added all features planned. Alpha release.
0.4.0 - 2003/1/15
- Implemented most features that are planned.
0.2.0 - 2002/2/20
- Added application variable support.
0.1.0 - 2002/1/12
- Initial test release.