pyams/pyams_user_guide: comparison src/source/zodb.rst

equal deleted inserted replaced

-:eeef4052fcd1
+:f234f01d54f9
 .. _zodb:
-Creating ZODB
-=============
+ZODB server
+============
-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.
+Installation
-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`_.
+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).
-.. _ZEO:
+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:
-Installing a ZEO server
-+++++++++++++++++++++++
+* `ZEO Server`_
+* `RelStorage`_
-ZEO (Zope Enterprise Objects) is the first available implementation available for concurrent access to a
+* `Newt.DB`_
+.. note::
+When you start your application in "*single process*" mode, PyAMS packages start several processes
+and the "*synchronization*" is done via **ØMQ**.
+.. _`ZEO Server`:
+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::
-Creating initial buildout
+ZEO package documentation and complete configuration settings are available on PyPI_ (cf: `ZOE 5.2.0`_).
--------------------------
+.. _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.
 A simple option to create a ZEO server is to create a buildout environment including *ZEO* and *ZODB* packages:
 .. code-block:: bash
-# mkdir /var/local/
+$ mkdir /var/local/
-# pip3 install virtualenv
+$ pip3 install virtualenv
-# virtualenv --python=python3.5 env
+$ virtualenv --python=python3.5 env
-# cd env
+$ cd env
-# . bin/activate
+$ . bin/activate
-(env) # pip3.5 install cookiecutter
+(env) $ pip3.5 install cookiecutter
-(env) # cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/zeo_server
+(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:
 - **pyams_release**: version of PyAMS configuration file to use. "latest" (default value) will point to last release;
 you can also choose to point to a given release ("0.1.4" for example)
 - ./bin/buildout
 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:
 - **etc/zeo_server-zdaemon.conf**: ZDaemon configuration file
 after buildout.
 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:
 - **etc/init.d/zeo-zeo_server**: ZEO server start/stop script in Init-D format. Create a link to this file in
 */etc/init.d* and update Init.d scripts (*update-rc.d zeo-zeo_server defaults*) to include ZEO in server start/stop
 to be changed on other distributions.
 .. _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
 supported.
 benefit from many extensions (clustering, fail-over, hot-standby...) provided by these databases.
 .. _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).
 NewtDB adds conversion of data from the native serialization used by ZODB to JSON, stored in a PostgreSQL JSONB
 Database creation is done as with RelStorage, but NewtDB add several schema objects. Migration scripts are available
 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.
 This Python script is using a configuration file containing directives of both source and target databases, which can
 be any storage described in the previous sections (or can even use the same storage).
 Here is a sample configuration file to convert a ZODB from a ZEO to RelStorage:
-.. code-block::
+.. code-block:: html
 %import relstorage
 <zeoclient source>
 server zeo-server.mydomain:8100
 shared-blob-dir false
 <postgresql>
 dsn host='postgresql-server.mydomain' dbname='pyams_rs' user='pyams' password='xxxxxxxx'
 </postgresql>
 </relstorage>

branch	dev-dc
changeset 34	f234f01d54f9
parent 21	e1cb9c606859
child 104	942151432421