More docs on setting up databases [skip ci]
This commit is contained in:
parent
2d9b282d7e
commit
436fbefec1
|
@ -5,6 +5,8 @@
|
|||
Once RelStorage is installed together with the appropriate database
|
||||
adapter, and you have created a user and database to use with
|
||||
RelStorage, it's time to configure the application to use RelStorage.
|
||||
This means telling RelStorage about the database to use, how to
|
||||
connect to it, and specifying any additional options.
|
||||
|
||||
.. note:: This is just a quick-start guide. There is a :doc:`full list
|
||||
of supported options <relstorage-options>` in a separate
|
||||
|
@ -40,29 +42,34 @@ An example::
|
|||
user plone
|
||||
passwd PASSWORD
|
||||
|
||||
Configuring Zope 2
|
||||
==================
|
||||
Configuring using ZConfig
|
||||
=========================
|
||||
|
||||
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::
|
||||
The most common way to configure RelStorage will involve writing a
|
||||
configuration file using the `ZConfig
|
||||
<https://github.com/zopefoundation/ZConfig/blob/master/doc/zconfig.pdf>`_
|
||||
syntax. You will write a ``<relstorage>`` element containing
|
||||
the general RelStorage options, and containing one database-specific
|
||||
element (``<postgresql>``, ``<mysql>`` or ``<oracle>``). (Where in the
|
||||
file the ``<relstorage>>`` element goes is specific to the framework
|
||||
or application you're using and will be covered next.)
|
||||
|
||||
In all cases, you'll need to add ``%import relstorage`` to the
|
||||
top-level of the file to let ZConfig know about the RelStorage
|
||||
specific elements.
|
||||
|
||||
|
||||
Examples 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::
|
||||
MySQL::
|
||||
|
||||
%import relstorage
|
||||
<zodb_db main>
|
||||
mount-point /
|
||||
<relstorage>
|
||||
<mysql>
|
||||
# Most of the options provided by MySQLdb are available.
|
||||
|
@ -70,13 +77,9 @@ For MySQL::
|
|||
db zodb
|
||||
</mysql>
|
||||
</relstorage>
|
||||
</zodb_db>
|
||||
|
||||
For Oracle (10g XE in this example)::
|
||||
And Oracle (10g XE in this example)::
|
||||
|
||||
%import relstorage
|
||||
<zodb_db main>
|
||||
mount-point /
|
||||
<relstorage>
|
||||
<oracle>
|
||||
user username
|
||||
|
@ -84,24 +87,38 @@ For Oracle (10g XE in this example)::
|
|||
dsn XE
|
||||
</oracle>
|
||||
</relstorage>
|
||||
</zodb_db>
|
||||
|
||||
To add ZODB blob support, provide a blob-dir option that specifies
|
||||
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>
|
||||
|
||||
|
||||
Configuring Zope 2
|
||||
------------------
|
||||
|
||||
To integrate RelStorage in Zope 2, specify a RelStorage backend in
|
||||
``etc/zope.conf``. Remove the main mount point replace it with the
|
||||
``<relstorage>`` element. For example (using PostgreSQL)::
|
||||
|
||||
%import relstorage
|
||||
<zodb_db main>
|
||||
mount-point /
|
||||
<relstorage>
|
||||
<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
|
||||
|
@ -118,4 +135,19 @@ contents similar to the following::
|
|||
</zodb>
|
||||
|
||||
``repoze.zodbconn`` expects a ZODB URI. Use a URI of the form
|
||||
``zconfig://path/to/configuration#main``.
|
||||
``zconfig://path/to/configuration#main`` where
|
||||
``path/to/configuration`` is the complete path to the configuration
|
||||
file, and ``main`` is the name given to the ``<zodb>`` element.
|
||||
|
||||
Manually Opening a Database
|
||||
---------------------------
|
||||
|
||||
You can also manually open a ZODB database in Python code. Once you
|
||||
have a configuration file as outlined above, you can use the
|
||||
``ZODB.config.databaseFromURL`` API to get a ZODB database::
|
||||
|
||||
path = "path/to/configuration"
|
||||
import ZODB.config
|
||||
db = ZODB.config.databaseFromURL(path)
|
||||
conn = db.open()
|
||||
...
|
||||
|
|
|
@ -2,11 +2,16 @@
|
|||
Configuring Your Database
|
||||
===========================
|
||||
|
||||
You need to configure a database and user account for RelStorage.
|
||||
You need to configure a database (schema) and user account for RelStorage.
|
||||
RelStorage will populate the database with its schema the first time it
|
||||
connects. Once you have the database configured, you can
|
||||
:doc:`configure your application <configure-application>` to use RelStorage.
|
||||
|
||||
.. note:: If you'll be developing on RelStorage itself, see :ref:`how
|
||||
to set up databases to run tests <test-databases>`.
|
||||
|
||||
.. highlight:: shell
|
||||
|
||||
PostgreSQL
|
||||
==========
|
||||
|
||||
|
@ -21,6 +26,12 @@ example::
|
|||
$ createuser --pwprompt zodbuser
|
||||
$ createdb -O zodbuser zodb
|
||||
|
||||
Alternately, you can use the ``psql`` PostgreSQL client and issue SQL
|
||||
statements to create users and databases. For example::
|
||||
|
||||
$ psql -U postgres -c "CREATE USER zodbuser WITH PASSWORD 'relstoragetest';"
|
||||
$ psql -U postgres -c "CREATE DATABASE zodb OWNER zodbuser;"
|
||||
|
||||
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
|
||||
|
@ -52,6 +63,8 @@ command, using any login account::
|
|||
|
||||
$ mysql -u root -p
|
||||
|
||||
.. highlight:: sql
|
||||
|
||||
Here are some sample SQL statements for creating the user and database::
|
||||
|
||||
CREATE USER 'zodbuser'@'localhost' IDENTIFIED BY 'mypassword';
|
||||
|
@ -66,12 +79,16 @@ performance.
|
|||
Oracle
|
||||
======
|
||||
|
||||
.. highlight:: shell
|
||||
|
||||
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
|
||||
|
||||
.. highlight:: sql
|
||||
|
||||
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
|
||||
|
|
|
@ -23,6 +23,8 @@ tests. Otherwise, tests for all installed drivers will be attempted;
|
|||
this can be bypassed with ``--no-db`` or limited to particular
|
||||
databases with ``--only-[mysql|pgsql|oracle]``.
|
||||
|
||||
.. _test-databases:
|
||||
|
||||
Databases
|
||||
=========
|
||||
|
||||
|
@ -51,13 +53,10 @@ used to set up the continuous integration test environment in the
|
|||
PostgreSQL
|
||||
----------
|
||||
|
||||
Execute the following using the ``psql`` command::
|
||||
Execute the following using the ``psql`` command:
|
||||
|
||||
CREATE USER relstoragetest WITH PASSWORD 'relstoragetest';
|
||||
CREATE DATABASE relstoragetest OWNER relstoragetest;
|
||||
CREATE DATABASE relstoragetest2 OWNER relstoragetest;
|
||||
CREATE DATABASE relstoragetest_hf OWNER relstoragetest;
|
||||
CREATE DATABASE relstoragetest2_hf OWNER relstoragetest;
|
||||
.. literalinclude:: ../../.travis/postgres.sh
|
||||
:language: shell
|
||||
|
||||
Also, add the following lines to the top of pg_hba.conf (if you put
|
||||
them at the bottom, they may be overridden by other parameters)::
|
||||
|
@ -81,19 +80,10 @@ test run much faster.
|
|||
MySQL
|
||||
-----
|
||||
|
||||
Execute the following using the ``mysql`` command::
|
||||
|
||||
CREATE USER 'relstoragetest'@'localhost' IDENTIFIED BY 'relstoragetest';
|
||||
CREATE DATABASE relstoragetest;
|
||||
GRANT ALL ON relstoragetest.* TO 'relstoragetest'@'localhost';
|
||||
CREATE DATABASE relstoragetest2;
|
||||
GRANT ALL ON relstoragetest2.* TO 'relstoragetest'@'localhost';
|
||||
CREATE DATABASE relstoragetest_hf;
|
||||
GRANT ALL ON relstoragetest_hf.* TO 'relstoragetest'@'localhost';
|
||||
CREATE DATABASE relstoragetest2_hf;
|
||||
GRANT ALL ON relstoragetest2_hf.* TO 'relstoragetest'@'localhost';
|
||||
FLUSH PRIVILEGES;
|
||||
Execute the following using the ``mysql`` command:
|
||||
|
||||
.. literalinclude:: ../../.travis/mysql.sh
|
||||
:language: shell
|
||||
|
||||
MySQL specific tests can be run by the testmysql module::
|
||||
|
||||
|
|
Loading…
Reference in New Issue