PyPI 官网下载 | RelStorage-1.6.3.tar.gz

RelStorage is a storage implementation for ZODB that stores pickles in a relational database. PostgreSQL 8.1 and above (via psycopg2), MySQL 5.0.32+ / 5.1.34+ (via MySQLdb 1.2.2 and above), and Oracle 10g and 11g (via cx_Oracle) are currently supported. RelStorage replaced the PGStorage project. .. contents:: Features ======== * It is a drop-in replacement for FileStorage and ZEO. * There is a simple way to convert FileStorage to RelStorage and back again. You can also convert a RelStorage instance to a different relational database. * Designed for high volume sites: multiple ZODB instances can share the same database. This is similar to ZEO, but RelStorage does not require ZEO. * According to some tests, RelStorage handles high concurrency better than the standard combination of ZEO and FileStorage. * Whereas FileStorage takes longer to start as the database grows due to an in-memory index of all objects, RelStorage starts quickly regardless of database size. * Supports undo, packing, and filesystem-based ZODB blobs. * Both history-preserving and history-free storage are available. * Capable of failover to replicated SQL databases. * Free, open source (ZPL 2.1) Installation ============ You can install RelStorage using easy_install:: easy_install RelStorage RelStorage requires a version of ZODB that is aware of MVCC storages. ZODB 3.9 supports RelStorage without any patches. ZODB 3.7 and 3.8 can support RelStorage if you first apply a patch to ZODB. You can get versions of ZODB with the patch already applied here: http://packages.willowrise.org The patches are also included in the source distribution of RelStorage. You need the Python database adapter that corresponds with your database. Install psycopg2, MySQLdb 1.2.2+, or cx_Oracle 4.3+. **CAUTION**: RelStorage 1.6 will *not* work with ZODB 5 or ZEO 5. You will need a 4.x or older version of those two dependencies. The setup.py distributed with RelStorage cannot enforce this due to the legacy nature of its ZODB3 dependency. Configuring Your Database ------------------------- You need to configure a database and user account for RelStorage. RelStorage will populate the database with its schema the first time it connects. PostgreSQL ~~~~~~~~~~ If you installed PostgreSQL from a binary package, you probably have a user account named ``postgres``. Since PostgreSQL respects the name of the logged-in user by default, switch to the ``postgres`` account to create the RelStorage user and database. Even ``root`` does not have the PostgreSQL privileges that the ``postgres`` account has. For example:: $ sudo su - postgres $ createuser --pwprompt zodbuser $ createdb -O zodbuser zodb New PostgreSQL accounts often require modifications to ``pg_hba.conf``, which contains host-based access control rules. The location of ``pg_hba.conf`` varies, but ``/etc/postgresql/8.4/main/pg_hba.conf`` is common. PostgreSQL processes the rules in order, so add new rules before the default rules rather than after. Here is a sample rule that allows only local connections by ``zodbuser`` to the ``zodb`` database:: local zodb zodbuser md5 PostgreSQL re-reads ``pg_hba.conf`` when you ask it to reload its configuration file:: /etc/init.d/postgresql reload MySQL ~~~~~ Use the ``mysql`` utility to create the database and user account. Note that the ``-p`` option is usually required. You must use the ``-p`` option if the account you are accessing requires a password, but you should not use the ``-p`` option if the account you are accessing does not require a password. If you do not provide the ``-p`` option, yet the account requires a password, the ``mysql`` utility will not prompt for a password and will fail to authenticate. Most users can start the ``mysql`` utility with the following shell command, using any login account:: $ mysql -u root -p Here are some sample SQL statements for creating the user and database:: CREATE USER 'zodbuser'@'localhost' IDENTIFIED BY 'mypassword'; CREATE DATABASE zodb; GRANT ALL ON zodb.* TO 'zodbuser'@'localhost'; FLUSH PRIVILEGES; Oracle ~~~~~~ Initial setup will require ``SYS`` privileges. Using Oracle 10g XE, you can start a ``SYS`` session with the following shell commands:: $ su - oracle $ sqlplus / as sysdba You need to create a database user and grant execute privileges on the DBMS_LOCK package to that user. Here are some sample SQL statements for creating the database user and granting the required permissions:: CREATE USER zodb IDENTIFIED BY mypassword; GRANT CONNECT, RESOURCE, CREATE TABLE, CREATE SEQUENCE TO zodb; GRANT EXECUTE ON DBMS_LOCK TO zodb; Configuring Plone ----------------- To install RelStorage in Plone, see the instructions in the following article: http://shane.willowrise.com/archives/how-to-install-plone-with-relstorage-and-mysql/ Plone uses the ``plone.recipe.zope2instance`` Buildout recipe to generate zope.conf, so the easiest way to configure RelStorage in a Plone site is to set the ``rel-storage`` parameter in ``buildout.cfg``. The ``rel-storage`` parameter contains options separated by newlines, with these values: * ``type``: any database type supported (``postgresql``, ``mysql``, or ``oracle``) * RelStorage options like ``cache-servers`` and ``poll-interval`` * Adapter-specific options An example:: rel-storage = type mysql db plone user plone passwd PASSWORD Configuring Zope 2 ------------------ To integrate RelStorage in Zope 2, specify a RelStorage backend in ``etc/zope.conf``. Remove the main mount point and add one of the following blocks. For PostgreSQL:: %import relstorage <zodb_db main> mount-point / <relstorage> <postgresql> # The dsn is optional, as are each of the parameters in the dsn. dsn dbname='zodb' user='username' host='localhost' password='pass' </postgresql> </relstorage> </zodb_db> For MySQL:: %import relstorage <zodb_db main> mount-point / <relstorage> <mysql> # Most of the options provided by MySQLdb are available. # See component.xml. db zodb </mysql> </relstorage> </zodb_db> For Oracle (10g XE in this example):: %import relstorage <zodb_db main> mount-point / <relstorage> <oracle> user username password pass dsn XE </oracle> </relstorage> </zodb_db> To add ZODB blob support, provide a blob-dir option that specifies where to store the blobs. For example:: %import relstorage <zodb_db main> mount-point / <relstorage> blob-dir ./blobs <postgresql> dsn dbname='zodb' user='username' host='localhost' password='pass' </postgresql> </relstorage> </zodb_db> Configuring ``repoze.zodbconn`` ------------------------------- To use RelStorage with ``repoze.zodbconn``, a package that makes ZODB available to WSGI applications, create a configuration file with contents similar to the following:: %import relstorage <zodb main> <relstorage> <mysql> db zodb </mysql> </relstorage> cache-size 100000 </zodb> ``repoze.zodbconn`` expects a ZODB URI. Use a URI of the form ``zconfig://path/to/configuration#main``. Included Utilities ================== ``zodbconvert`` --------------- RelStorage comes with a script named ``zodbconvert`` that converts databases between formats. Use it to convert a FileStorage instance to RelStorage and back, or to convert between different kinds of RelStorage instances, or to convert other kinds of storages that support the storage iterator protocol. When converting between two history-preserving databases (note that FileStorage uses a history-preserving format), ``zodbconvert`` preserves all objects and transacti