HTTPS clone URL
Subversion checkout URL
Postgres session handler extension for PHP
Latest commit 165b9e6 Michael Graziano Update README - Mostly Grammar, Spelling and flow changes.
PostgreSQL database session save handler module session_pgsql is an additional session save handler module. It provides session storage using PostgreSQL database server(s). - C implementation of session save handler with PostgreSQL. - Automatic session table creation. - Automatic garbage collection/Session Expiration. - Multiple PostgreSQL servers support. - Automatic db server failover(switching) when there is trouble. - Automatic db server load balancing where there are multiple PostgreSQL servers. - Short circuit UPDATE It is designed to scale to any deployment size, though it has only received medium-scale testing. This release of the session_pgsql extension was based on work by Yasuo Ohgaki, who graciously allowed its re-release under the PHP license. It was modernized by Michael Graziano in 2009 to allow it to work on PHP 5.3. [Requirements] PHP 5.3.0 or later PostgreSQL 8.3.0 or later libpq that comes with PostgreSQL 8.3.0 or later (and header to build) libmm (and header. I use mm-1.4.2) [How to compile] If you are using PECL you should just be able to "pecl install" this extension (and you probably aren't reading this file if that's the case). To compile it manually, you need to do one of the following: Static component of PHP: To build session_pgsql into PHP itself you need to add the "--with-session-pgsql[=DIR]" option to the configure line. [=DIR] is installation path for PostgreSQL. 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. Restart your web server. As a PHP Module: 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 the PHP headers and build tools installed. These files are installed when you "make install" from the PHP sources. If you are using a vendor-packaged PHP these files are likely in a "php-devel" or "php-dev" 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 % make % make install This will build the session_pgsql.so module and should install the module file to php module directory (Verify the output of make install against php-config's idea of where modules should live). 5. Edit your php.ini to load session_pgsql. Add following line to php.ini extension=session_pgsql.so 6. Restart your web server. 7. Verify with phpinfo() if session_pgsql is loaded or not. If it's not loaded, try using the full path to the module. [How to use] Once you have successfully installed session_pgsql (and PHP of course) and have a PostgreSQL server to point it at you need to create a datbase and user for session_pgsql to use. All you have to do is (as postgres super user) % createuser php_session % createdb php_session Then in your php.ini file session.save_handler = pgsql or in your script (*before* staring any sessions) 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: session_pgsql cannot be used with CGI/CLI binary, dl() or loading from .htaccess NOTE: It's good idea to have fairly secure settings on the session DB/Table. the session_pgsql user needs: The CONNECT privilege on the database The USAGE privilege on the schema the table resides in The SELECT, INSERT, UPDATE and DELETE privileges on the session table. The session_pgsql user SHOULD NOT be a superuser. [php.ini settings] The 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 - I suggest setting it to "session_pgsql" or similar since it gets passed up the PHP error chain in warning/error messages and can help make debugging easier. 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=somedb user=user1;host=server2 dbname=otherdb user=user2" If multiple servers are set, session_pgsql will try to automatically balance db server load. If one of session db server fails, it will try to use other available db servers automatically. NOTE: It is recommended that you use database-level load balancing and redundancy rather than specifying multiple DB servers. 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.create_table Automatically create session variable table. If set to on session_pgsql will try to create the php_session table. 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 values will make session_pgsql save changes to table, otherwise it will not update table. NOTE: Access counter and expire field are not updated if this is enabled -- This has garbage collection implications. Default is off (always update). 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. if set to on. If this option is enabled, load balancing session db server will not be enabled. Default is off. NOTE: This will not mirror your data, it just switches to the other database server if it can't reach the first one. It is recommended that you use database-level load balancing and redundancy rather than using failover_mode Default is off, since you should be pointing at a redundant DB. session_pgsql.gc_interval How often perform GC (in seconds). It is good idea set to 0 (disable) and perform garbage collection using cron, especially if you have multiple web servers. Negative values are allowed, and will cause GC to run on EVERY session access. Default is 3600 seconds (1 hour). [Known Problems] This extension does not work with SquirrelMail -- this appears to be due to problems with how SquirrelMail handles Sessions. Patches to fix this are welcomed. Please report any problems you find to the maintainer - firstname.lastname@example.org. [Session Table Definition] CREATE TABLE php_session ( sess_id text PRIMARY KEY, 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 ); You may change the session table as long as all fields above are defined. [ToDo] [History] 1.0.1 - 2010/01/19 - Minor fixes and tweaks in error handling - Updated CREATE TABLE statement to define a PKEY 1.0.0 - 2009/12/01 - Stable release for PHP-5.3.0 (mg). - Removed application variable support (Narrowing scope to what I use/can test) 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.