diff -r a7332a53e6dc -r 5fe8d5ffccde src/source/zodb.rst --- a/src/source/zodb.rst Mon Mar 26 10:38:06 2018 +0200 +++ b/src/source/zodb.rst Thu Apr 12 11:18:48 2018 +0200 @@ -1,28 +1,49 @@ .. _zodb: -Creating ZODB -============= + +ZODB server +============ + + +Installation +'''''''''''' -PyAMS primarily relies on a ZODB (Zope Objects DataBase) to store it's configuration. Other packages may -rely on other database(s), but *PyAMS_content* package also stores it's contents in a ZODB. +PyAMS relies mainly on a ZODB (**\Z**\ope **\O**\bjects **\D**\ata\ **\B**\ase) to store it's configuration and for exemple *PyAMS_content*, but other packages may +rely on other database(s). -As some PyAMS packages start several processes ("synchronization" is done via **ØMQ**), concurrent accesses are -required on the ZODB (even when you start your application in "single process" mode); several ZODB storages -implementations providing a shared access are available: `ZEO`_, `RelStorage`_ and `Newt.DB`_. +Concurrent accesses are **required** on the ZODB, to fully enjoy PyAMS. +Several ZODB storages implementations providing a shared access are available and the installation are describe below: + + * `ZEO Server`_ + * `RelStorage`_ + * `Newt.DB`_ -.. _ZEO: +.. note:: + + When you start your application in "*single process*" mode, PyAMS packages start several processes + and the "*synchronization*" is done via **ØMQ**. + + -Installing a ZEO server -+++++++++++++++++++++++ +.. _`ZEO Server`: -ZEO (Zope Enterprise Objects) is the first available implementation available for concurrent access to a +1. ZEO server ++++++++++++++ + +ZEO (**\Z**\ope **\E**\nterprise **\O**\bjects) is the first available implementation available for concurrent access to a FileStorage, provided through the ZEO package. -ZEO package documentation and complete configuration settings are available on PyPI. +.. seealso:: + + ZEO package documentation and complete configuration settings are available on PyPI_ (cf: `ZOE 5.2.0`_). -Creating initial buildout -------------------------- +.. _PyPI: https://pypi.python.org/pypi/ZEO +.. _`ZOE 5.2.0`: https://pypi.python.org/pypi/ZEO/5.2.0 + + +a) Installation with initial buildout +------------------------------------- PyAMS provides a ZEO server scaffold, called *zeo_server*, generated via a *cookiecutter* template. @@ -30,13 +51,13 @@ .. code-block:: bash - # mkdir /var/local/ - # pip3 install virtualenv - # virtualenv --python=python3.5 env - # cd env - # . bin/activate - (env) # pip3.5 install cookiecutter - (env) # cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/zeo_server + $ mkdir /var/local/ + $ pip3 install virtualenv + $ virtualenv --python=python3.5 env + $ cd env + $ . bin/activate + (env) $ pip3.5 install cookiecutter + (env) $ cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/zeo_server *CookieCutter* will ask you for a small set of input variables that you can change or not: @@ -75,8 +96,8 @@ To initialize authentication database, please run following command after buildout: ./bin/zeopasswd -f etc/auth.db -p digest -r "ZEO_server" zeouser xxxx -ZEO server configuration ------------------------- +b) ZEO server configuration +--------------------------- All ZEO configuration files are generated in "etc" subdirectory. These includes: @@ -90,8 +111,9 @@ In these file names, always replace "zeo_server" with the value which was given to "project_slug" variable during *CookieCutter* template creation. -ZEO server tools ----------------- + +c) ZEO server tools +------------------- A set of system configuration files are produced to handle your ZEO environment. These includes: @@ -116,8 +138,8 @@ .. _RelStorage: -Installing a RelStorage server -++++++++++++++++++++++++++++++ +2. RelStorage server +++++++++++++++++++++ RelStorage (http://relstorage.readthedocs.io/en/latest) is an alternate ZODB storage implementation, that stores Python pickles in a relational database; PostgreSQL (>= 9.0), MySQL (>= 5.0.32) and Oracle (> 10g) databases are @@ -132,8 +154,8 @@ .. _Newt.DB: -Installing a NewtDB server -++++++++++++++++++++++++++ +3. NewtDB server +++++++++++++++++ NewtDB (http://www.newtdb.org/en/latest) is another ZODB storage implementation. It's using RelStorage but is dedicated to PostgreSQL (>= 9.5). @@ -150,21 +172,10 @@ if you need to switch from a classic RelStorage database to a Newt database. -.. _ZODB.init: - -Initializing ZODB -+++++++++++++++++ - -When your ZODB is created, you have to initialize it! - -After installing PyAMS application (see :ref:`appinstall`), a database upgrade script is available which allows you -to initialize the database. See :ref:`config` and :ref:`scripts` to know more. - - .. _ZODB.migration: -ZODB migration -++++++++++++++ +Migration +''''''''' After installation, you can switch from a given storage to another one with the help of the *zodbconvert* command line script provided by RelStorage. @@ -174,7 +185,8 @@ Here is a sample configuration file to convert a ZODB from a ZEO to RelStorage: -.. code-block:: + +.. code-block:: html %import relstorage @@ -193,3 +205,5 @@ dsn host='postgresql-server.mydomain' dbname='pyams_rs' user='pyams' password='xxxxxxxx' + +