cson  Artifact Content

Artifact 98abac16e6cdd46460d1bed93327840f94268ffa:

Wiki page [cson_sessmgr_cpdo] by stephan 2011-05-09 17:58:44.
D 2011-05-09T17:58:44.870
L cson_sessmgr_cpdo
P bae8876f6952ba416151059bd6e2b2092d532df6
U stephan
W 3308
<strong>ACHTUNG: THIS PAGE IS NOW MAINTAINED IN THE NEW WIKI:</strong> [http://whiki.wanderinghorse.net/wikis/cson/?page=cson_sessmgr_cpdo]


See also: [cson_session], [cson_sessmgr_file], [cson_sessmgr_whio_ht], [cson_sessmgr_whio_epfs]

<h1>Database [cson_session] Storage</h1>

For this to be enabled, the library must be built with the <tt>CSON_ENABLE_CPDO</tt> macro set to a true value. Additionally, <tt>CPDO_ENABLE_SQLITE3</tt> and/or <tt>CPDO_ENABLE_MYSQL5</tt> will need to be set to true values if those back-ends are to be enabled. See [AmalgamationBuild] for more details.

The function <tt>cson_sessmgr_cpdo()</tt> is used to instantiate a session manager for database-based storage, using the [http://fossil.wanderinghorse.net/repos/cpdo/|cpdo] database access abstraction library (included in this source tree). Or one can use <tt>cson_sessmgr_load()</tt>>, passing it a key of "cpdo". The second argument to both functions is a <tt>cson_object</tt> which should have the following JSON structure:

<verbatim>
{
    "dsn": "drivername:driver_options... see cpdo docs",
    "user": "database user name",
    "password": "database password", 
    "table": "database table name containing the sessions",
    "fieldId": "db field which stores the session id (VARCHAR, length is app-dependent)",
    "fieldTimestamp": "db field which stores the last modification time (INTEGER-form timestamp)",
    "fieldSession": "db field which stores the raw JSON data (TEXT or BLOB, depending on the db)"
}
</verbatim>

The "dsn" option is required. All others use defaults if not specified (but logging in will likely fail if the user/password parts are not supplied). cpdo's DSN string format is described [http://fossil.wanderinghorse.net/repos/cpdo/index.cgi/wiki?name=DSN|on this page]. Note that the sqlite3-based back-end does not require user/password information.

The <tt>fieldTimestamp</tt> value must name a field which contains an integer value. The library assumes that times are stored in Unix Epoch (seconds since midnight 1970.1.1). The library currently uses local time, but should arguably be changed to use GMT (or make this a config option).

See the file <tt>cgi-test.json</tt>, in the source tree, for examples
of configuring both sqlite3- and mysql-based sessions.

Here is some sample SQL for setting up a session table:

sqlite3:
<verbatim>
CREATE TABLE cson_session (
    id VARCHAR(50) PRIMARY KEY NOT NULL, -- session ID string
    last_saved INTEGER NOT NULL DEFAULT 0, -- Unix Epoch timestamp
    json TEXT DEFAULT NULL -- the raw session JSON
);
</verbatim>

MySQL 5:
<verbatim>
CREATE TABLE `cson_session` (
  `id` varchar(50) PRIMARY KEY NOT NULL,
  `last_saved` int(11) NOT NULL DEFAULT 0,
  `json` text DEFAULT NULL
) ENGINE=MyISAM DEFAULT CHARSET=utf8;
</verbatim>

Note, however, that the manager configuration options can be used to define the names of the table and fields. Client-side session tables can also have additional fields, with the caveats that all must be able to default to some value and that this library might delete them (when it saves the session). This API only explicitly uses the fields described above, but may remove/replace rows, so clients cannot depend on any custom fields having stable values.

Z d08834d03168de7f76b09aa709877ba7