[Zope] announce: SQLSession, 0.2.0

[Anthony Baxter]

At <URL:http://www.zope.org/Members/anthony/software/SQLSession/>,
you can find version 0.2.0 of my SQL Session product. Attached to 
this email is a list of changes since the previously publically
released version, as well as the readme.txt from the distribution.

Note that this version should behave in a much more pleasant fashion
with databases which dislike embedded newlines in literal strings
(e.g. Gadfly, and maybe PostgreSQL). 

Thanks to amk for pointing out the missing dictionary bits (and supplying
a patch!)

Let me know if this is useful for you, and if you have suggestions for
it's future development (patches more than welcome, of course :)

Anthony

---

Version 0.2.0

    Check that _force_new_session exists and has a true value, not just
    that it exists.

    Creating a new session updates the current REQUEST to refer to the new
    session. Otherwise, any old session will be seen for the rest of this
    transaction. This is a Principle of Least Suprise fix.

    Added additional dictionary methods (from amk). All except copy() are
    implemented.

    Added caching (disabled by default).

    Added support for multiple modes of storage in the database. Currently
    there is base64 and base64oneline. The latter replaces newlines in the
    encoded string with spaces. This is needed for gadfly, and _may_ be needed
    for PostgreSQL. If you need to enable this for your database, drop me a
    line and let me know which databases require it and which don't.


---
README for SQL Session, v 0.2

SQL Session

    This is a server-side session object that stores all state in 
    an SQL database.

    Usage:

	create an SQL Session object (it will be called 'Session'), and
	make sure the SQL is correct.

        in all documents that want to use Sessions, put, at the top

        <dtml-call Session>

        (I'd suggest putting it in your standard_html_header)

        This does a few things:
	  It looks for a session cookie (by default called _ZSession, but
	  that's something you can just set). If it finds one, it looks in
	  the database to check that this is an ok cookie to use.

	  If it doesn't find a cookie, or it finds that the Session is a 
	  dud, or if the request has the parameter '_force_new_session' set
	  to a true value, it will create a new Session in the DB, then send 
	  back a cookie with that session in it. 

          Next, it creates a SessionObj called 'SESSION', and puts it 
	  in the REQUEST object (so REQUEST['SESSION'] - just like 
	  REQUEST['RESPONSE']). This looks and acts like a dictionary, 
	  only it pulls its data out of the DB, and sets data in the 
	  DB. It supports the following:

	    __getitem__, __setitem__, set, keys, values, items, and most
	    other dictionary methods (except copy)


	From here on inside the document, you can do things like

	<dtml-call "SESSION.set('someitem', 'somevalue')">

	<dtml-var "SESSION['someitem']">

	and it will just be squirrelled away in the DB.


    The Gory Details, #1: SQL schema:

	The default SQL schema is pretty dumb, but it should
	work on everything (I test on gadfly).

	create table sessions 
	( session varchar  ) 

	create unique index sessions_idx on sessions(session)

	create table session_data
	( session varchar,
	  name varchar,
          value varchar  )

	A smarter one (like the one I use :) would use a sequence or
	similar to create a session_id, and use that in a key in session_data.

	Anyway, you don't have to use this schema - go edit the sql methods
	in the session (pull up it's management interface).

    The Gory Details, #2: Storing objects:

	Right now the SessionObj stores base64 encoded pickles. It can
	optionally do caching of results, but only for the lifetime of the
	REQUEST.

	(sessionObjs are created for each request, so they don't have to
	worry about getting out of sync with the db.)

	The nice thing about storing things this way is, of course,
	that you can stuff almost anything into it. The bad thing is,
	of course, that you can stuff almost anything into it. Make sure
	your definition of the session_data table makes the value column
	sufficiently large for your needs!

	Note that some databases gripe about inserting varchars as literal
	strings with newlines in them. For these, you should use the 
	'base64oneline' encoding format. (select it from the main edit window).


    To Do:

	See seperate file TODO.txt

Anthony Baxter <anthony@interlink.com.au>, Sun Nov 21 17:58:02 EST 1999