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 - mikeg@bsd-box.net.

[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.