pyramid_zodbconn
================
Overview
--------
A package which provides integration between the Pyramid web application
server and the :term:`ZODB` object database.
It will run under CPython 2.5, 2.6, and 2.7. It will not run under PyPy or
Jython. It requires ZODB >= 3.10.0.
Installation
------------
Install using setuptools, e.g. (within a virtual environment)::
$ easy_install pyramid_zodbconn
Setup
-----
Once ``pyramid_zodbconn`` is installed, you must use the ``config.include``
mechanism to include it into your Pyramid project's configuration. In your
Pyramid project's ``__init__.py``:
.. code-block:: python
:linenos:
config = Configurator(.....)
config.include('pyramid_zodbconn')
Alternately you can use the ``pyramid.includes`` configuration value in your
``.ini`` file:
.. code-block:: ini
:linenos:
[app:myapp]
pyramid.includes = pyramid_zodbconn
Using
-----
For :mod:`pyramid_zodbconn` to work properly, you must add at least one
setting to your of your Pyramid's ``.ini`` file configuration (or to the
``settings`` dictionary if you're not using ini configuration):
``zodbconn.uri``. For example:
.. code-block:: ini
[app:myapp]
...
zodbconn.uri = zeo://localhost:9991?cache_size=25MB
...
The ``zodbconn.uri`` parameter is a URL which describes a ZODB database.
Once you've both included the ``pyramid_zodbconn`` into your configuration
via ``config.include('pyramid_zodbconn')`` and you've added a
``zodbconn.uri`` setting to your configuration, you can then use the
:func:`pyramid_zodbconn.get_connection` API in your Pyramid application, most
commonly in a Pyramid *root factory*:
.. code-block:: python
:linenos:
from pyramid_zodbconn import get_connection
from persistent.mapping import PersistentMapping
class MyModel(PersistentMapping):
__parent__ = __name__ = None
def root_factory(request):
conn = get_connection(request)
zodb_root = conn.root()
if not 'app_root' in zodb_root:
app_root = MyModel()
zodb_root['app_root'] = app_root
import transaction
transaction.commit()
return zodb_root['app_root']
The :func:`pyramid_zodbconn.get_connection` API returns a ZODB connection to
the main database you've specified via ``zodbconn.uri`` in your
configuration.
When the request is finalized, the connection you've opened via
``get_connection`` will be closed.
Named Databases
---------------
If you need to use more than one ZODB database in your Pyramid application,
you can use *named* databases via configuration. Named databases are
specified by ``zodbconn.uri.thename`` in settings configuration. For
example:
.. code-block:: ini
[app:myapp]
...
zodbconn.uri = zeo://localhost:9991?cache_size=25MB
zodbconn.uri.sessions = zeo://localhost:9992?cache_size=100MB
...
Once this is done, you can use :func:`pyramid_zodbconn.get_connection` to
obtain a reference to each of the named databases:
.. code-block:: python
main_conn = get_connection(request) # main database
sessions_conn = get_connection(request, 'sessions')
The ``zodbconn.uri.sessions`` parameter example above is a URI which
describes a ZODB database, in the same format as ``zodbconn.uri``. You can
combine named and unnamed database configuration in the same application.
You *must* have at least one primary database to use named databases.
.. note::
Named database support is new as of ``pyramid_zodbconn`` 0.3.
URI Schemes
-----------
The URI schemes currently recognized in the ``zodbconn.uri`` setting are
``file://``, ``zeo://``, ``zconfig://`` and ``memory://``. Documentation for
these URI scheme syntaxes are below.
``file://`` URI scheme
~~~~~~~~~~~~~~~~~~~~~~
The ``file://`` URI scheme can be passed as ``zodbconn.uri`` to create a ZODB
FileStorage database factory. The path info section of this scheme should
point at a filesystem file path that should contain the filestorage data.
For example::
file:///my/absolute/path/to/Data.fs
The URI scheme also accepts query string arguments. The query string
arguments honored by this scheme are as follows.
FileStorage constructor related
+++++++++++++++++++++++++++++++
These arguments generally inform the FileStorage constructor about
values of the same names.
create
boolean
read_only
boolean
quota
bytesize
Database-related
++++++++++++++++
These arguments relate to the database (as opposed to storage)
settings.
database_name
string
Connection-related
++++++++++++++++++
These arguments relate to connections created from the database.
connection_cache_size
integer (default 10000)
connection_pool_size
integer (default 7)
Blob-related
++++++++++++
If these arguments exist, they control the blob settings for this
storage.
blobstorage_dir
string
blobstorage_layout
string
Misc
++++
demostorage
boolean (if true, wrap FileStorage in a DemoStorage)
Example
+++++++
An example that combines a path with a query string::
file:///my/Data.fs?connection_cache_size=100&blobstorage_dir=/foo/bar
``zeo://`` URI scheme
~~~~~~~~~~~~~~~~~~~~~
The ``zeo://`` URI scheme can be passed as ``zodbconn.uri`` to create a ZODB
ClientStorage database factory. Either the host and port parts of this scheme
should point at a hostname/portnumber combination e.g.::
zeo://localhost:7899
Or the path part should point at a UNIX socket name::
zeo:///path/to/zeo.sock
The URI scheme also accepts query string arguments. The query string
arguments honored by this scheme are as follows.
ClientStorage-constructor related
+++++++++++++++++++++++++++++++++
These arguments generally inform the ClientStorage constructor about
values of the same names.
storage
string
cache_size
bytesize
name
string
client
string
debug
boolean
var
string
min_disconnect_poll
integer
max_disconnect_poll
integer
wait
boolean
wait_timeout
integer
read_only
boolean
read_only_fallback
boolean
username
string
password
string
realm
string
blob_dir
string
shared_blob_dir
boolean
Misc
++++
demostorage
boolean (if true, wrap ClientStorage in a DemoStorage)
Connection-related
++++++++++++++++++
These arguments relate to connections created from the database.
connection_cache_size
integer (default 10000)
connection_pool_size
integer (default 7)
Database-related
++++++++++++++++
These arguments relate to the database (as opposed to storage)
settings.
database_name
string
Example
+++++++
An example that combines a path with a query string::
zeo://localhost:9001?connection_cache_size=20000
``zconfig://`` URI scheme
~~~~~~~~~~~~~~~~~~~~~~~~~
The ``zconfig://`` URI scheme can be passed as ``zodbconn.uri`` to create any
kind of storage that ZODB can load via ZConfig. The path info section of this
scheme should point at a ZConfig file on the filesystem. Use an optional
fragment identifier to specify which database to open. This URI scheme does
not use query string parameters.
Examples
++++++++
An example ZConfig file::
If that configuration file is located at /etc/myapp/zodb.conf, use the
following URI to open the database::
zconfig:///etc/myapp/zodb.conf
A ZConfig file can specify more than one database. For example::
In that case, use a URI with a fragment identifier::
zconfig:///etc/myapp/zodb.conf#temp1
``memory://`` URI scheme
~~~~~~~~~~~~~~~~~~~~~~~~
The ``memory://`` URI scheme can be passed as ``zodbconn.uri`` to create a
ZODB MappingStorage (memory-based) database factory. The path info section
of this scheme should be a storage name. For example::
memory://storagename
However, the storage name is usually omitted, and the most common form is::
memory://
The URI scheme also accepts query string arguments. The query string
arguments honored by this scheme are as follows.
Database-related
++++++++++++++++
These arguments relate to the database (as opposed to storage)
settings.
database_name
string
Connection-related
++++++++++++++++++
These arguments relate to connections created from the database.
connection_cache_size
integer (default 10000)
connection_pool_size
integer (default 7)
Example
+++++++
An example that combines a dbname with a query string::
memory://storagename?connection_cache_size=100&database_name=fleeb
Events
------
All events are sent via the standard Pyramid ``registry.notify`` interface and
can be subscribed to using the ``config.add_subscriber`` API in Pyramid.
When a connection is opened, the
:class:`pyramid_zodbconn.ZODBConnectionOpened` event is sent.
Just before a connection is closed, the
:class:`pyramid_zodbconn.ZODBConnectionWillClose` event is sent.
When a connection is closed, the
:class:`pyramid_zodbconn.ZODBConnectionClosed` event is sent.
Transfer Log
------------
Add the key ``zodbconn.transferlog`` to your deployment settings to have
``pyramid_zodbconn`` send information about the ZODB storage loads and stores
caused by each request sent to the system. The ``zodbconn.transferlog`` key
can either be a filename or it can be empty, which indicates that the transfer
log should be sent to stdout.
For example::
zodbconn.transferlog = /some/file/transfer.log
The transfer log is written in CSV format. Each line is in the format::
timestamp, request_method, url, elapsed_secs, loads, stores
For example::
"2014-07-02 13:44:18", "GET", "/manage/@@contents", 28.47, 23580, 0
"2014-07-02 13:44:18", "GET", "/manage/auditstream-sse", 0.02, 0, 0
"2014-07-02 13:44:18", "GET", "/sdistatic/css/sdi_bootstrap.css", 0.00, 0, 0
"2014-07-02 13:44:18", "GET", "/sdistatic/js/jquery-2.0.3.js", 0.00, 0, 0
"2014-07-02 13:44:18", "GET", "/sdistatic/js/bootstrap.js", 0.00, 0, 0
"2014-07-02 13:44:18", "GET", "/sdistatic/js/sdi.js", 0.00, 0, 0
If you only want to write transfer log entries for requests that take over a
certain amount of time, you can use the ``zodbconn.transferlog_threshhold``
setting. It should be an integer representing a number of seconds. If the
request consumes more than this number of seconds, a transfer log line will be
written, otherwise no transfer log line will be written.
For example::
zodbconn.transferlog_threshhold = 2
More Information
----------------
.. toctree::
:maxdepth: 1
api.rst
glossary.rst
Change History
--------------
.. toctree::
:maxdepth: 1
changes
Reporting Bugs / Development Versions
-------------------------------------
Visit http://github.com/Pylons/pyramid_zodbconn to download development or
tagged versions.
Visit http://github.com/Pylons/pyramid_zodbconn/issues to report bugs.
Indices and tables
------------------
* :ref:`glossary`
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`