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.