Skip to content

Z
ZODB
Commit e89db466 authored by Jeremy Hylton's avatar Jeremy Hylton
Browse files
Options

Add a summary README.txt and remove a few more outdated files.

parent 7587a410
Hide whitespace changes
Inline Side-by-side
Showing with 21 additions and 339 deletions
doc/ZEO/ClientStorage.txt deleted 100644 → 0
View file @ 7587a410
ClientStorage
The ClientStorage is a ZODB storage implementation that provides
access to data served bt a ZEO server. To use a ClientStorage,
create the SlientStorage and configure your application to use
it. To configure Zope to use a ClientStorage, create the ClientStorage
and and assign it to the 'Storage' variable in a 'custom_zodb'
module (typically a Python file, with a '.py' suffix) in the
instance home of your Zope installation.
Creating a ClientStorage
The ClientStorage requires at leats one argument, the address or
addresses of the server(s) to use. It accepts several other
optional keyword arguments.
The address argument can be one of:
- a tuple containing hostname and port number
- a string specifying the path to a Unix domain socket
- a sequence of the previous two
If a sequence of addresses is specified, the client will use the
first server from the list that it can connect to, subject to the
constraints imposed by the optional read_only and
read_only_fallback keyword arguments.
The ClientStorage constructor provides a number of additional
options (arguments). The full list of arguments is:
storage -- The name of the storage to connect to.
A ZEO storage server can serve multiple storages. Each
storage has a name, which is configured on the server. The
server adminstrator should be able to provide this name. The
default name for both the server and client is '1'.
cache_size -- The number of bytes to allow for the client cache.
The default is 20MB. A large cache can significantly
increase the performance of a ZEO system. For applications that
have a large database, the default size may be too small.
For more information on client caches, see ClientCache.txt.
name -- The name to use for the storage. This will be shown in
Zope's control panel. The default name is a representation of
the connection information.
client -- The name to be used for the persistent client cache files.
This parameter can be used instead of or to override the
ZEO_CLIENT environment variable. It is generally better to use
the environment variable because it's easier to change
environment variables that it is to change Python code for
creating the storage.
Also note that, if you are using Zope, the ZEO_CLIENT
environment variable effects whether products are initialized.
For more information on client cache files, see ClientCache.txt.
var -- The directory in which persistent cache files should be
written. If this option is provided, it is unnecessary to
set INSTANCE_HOME in __builtins__.
For more information on client cache files, see ClientCache.txt.
min_disconnect_poll -- The minimum number of seconds to wait before
retrying connections after connection failure.
When trying to make a connection, if the connection fails, the
ZEO client will wait a period of time before retrying the
connection. The amount of time waited starts at the value given
by 'min_disconnect_poll' and doubles on each attempt, but never
exceeds the number of seconds given by 'max_disconnect_poll'.
The default is 5 seconds.
max_disconnect_poll -- The maximum number of seconds to wait before
retrying connections after connection failure.
See min_disconnect_poll.
The default is 300 seconds.
wait -- Indicate whether the ClientStorage should block waiting
for a storage server connection, or whether it should proceed,
satisfying reads from the client cache.
read_only -- Open a read-only connection to the server. If the
client attempts to commit a transaction, it will get a
ReadOnlyError exception.
Each storage served by a ZEO server can be configured as either
read-write or read-only.
read_only_fallback -- A flag indicating whether a read-only
remote storage should be acceptable as a fallback when no
writable storages are available. Defaults to false. At most
one of read_only and read_only_fallback should be true.
doc/ZEO/NonZopeREADME.txt deleted 100644 → 0
View file @ 7587a410
Zope Enterprize Objects
Installation
ZEO 2.0 requires Python 2.1 or higher when used without Zope. If
you use Python 2.1, we recommend the latest minor release (2.1.3 as
of this writing) because it includes a few bug fixes that affect
ZEO.
ZEO is packaged with distutils. To install it, run this command
from the top-level ZEO directory::
python setup.py install
The setup script will install the ZEO package in your Python
site-packages directory.
You can test ZEO before installing it with the test script::
python test.py -v
Run the script with the -h option for a full list of options. The
ZEO 2.0b2 release contains 122 unit tests on Unix.
Starting (and configuring) the ZEO Server
To start the storage server, go to your Zope install directory and
run::
python lib/python/ZEO/start.py -p port_number
This run the storage sever under zdaemon. zdaemon automatically
restarts programs that exit unexpectedly.
The server and the client don't have to be on the same machine.
If they are on the same machine, then you can use a Unix domain
socket::
python lib/python/ZEO/start.py -U filename
The start script provides a number of options not documented here.
See doc/start.txt for more information.
Running a ZEO client
In your application, create a ClientStorage, rather than, say, a
FileStorage:
import ZODB
from ZEO.ClientStorage import ClientStorage
Storage = ClientStorage(('', port_number))
db = ZODB.DB(Storage)
You can specify a host name (rather than '') if you want. The port
number is, of course, the port number used to start the storage
server.
You can also give the name of a Unix domain socket file::
import ZODB
from ZEO.ClientStorage import ClientStorage
Storage = ClientStorage(filename)
db = ZODB.DB(Storage)
There are a number of configuration options available for the
ClientStorage. See ClientStorage.txt for details.
If you want a persistent client cache which retains cache contents
across ClientStorage restarts, you need to define the environment
variable, ZEO_CLIENT, or set the client keyword argument to the
constructor to a unique name for the client. This is needed so
that unique cache name files can be computed. Otherwise, the
client cache is stored in temporary files which are removed when
the ClientStorage shuts down.
Dependencies on other modules
ZEO depends on other modules that are distributed with ZODB3 and
with Zope. You can download ZODB3 from
http://www.zope.org/Products/StandaloneZODB.
doc/ZEO/README.txt 0 → 100644
View file @ e89db466
ZEO Documentation
=================
This directory contains ZEO documentation.
howto.txt
The first place to look.
It provides a high-level overview of ZEO features and details on
how to install and configure clients and servers. Includes a
configuration reference.
cache.txt
Explains how the client cache works.
trace.txt
Describe cache trace tool used to determine ideal cache size.
ZopeREADME.txt
A somewhat dated description of how to integrate ZEO with Zope.
It provides a few hints that are not yet in howto.txt.
doc/ZEO/start.txt deleted 100644 → 0
View file @ 7587a410
The ZEO Server start script, start.py
ZEO provides a Python script for starting the ZEO server. The ZEO
server is implemented as a Python class and could be used with other
main programs, however, a simple ZEO server is provided for convenience.
Basic usage
To start the storage server, go to your Zope install directory and::
python lib/python/ZEO/start.py -p port_number
(Run start without arguments to see options.)
Of course, the server and the client don't have to be on the same
machine.
If the server and client *are* on the same machine, then you can use
a Unix domain socket::
python lib/python/ZEO/start.py -U filename
Serving custom storages or multiple storages with the storage server
The Storage server can host multiple storages and can
host any kind of storage. Each storage has a unique storage
name. By default, the ZEO start.py script serves a
standard FileStorage with the name '1'.
You can control what storages are served by creating a Python
file containing definitions for the storages and using the '-S'
option to the start.py script to indicate the storage
to be served. The form of the -S option is::
-Sstorage_name=module_path:attribute_name
Where:
storage_name -- is the storage name used in the ZEO protocol.
This is the name that you give as the optional
'storage' keyword argument to the ClientStorage constructor.
module_path -- This is the path to a Python module
that defines the storage object(s) to be served.
The module path should ommit the prefix (e.g. '.py').
attribute_name -- This is the name to which the storage object
is assigned in the module.
Consider the following example. I want to serve a FileStorage
in read-only mode, which I define in the module file
/stores/fs.py::
import ZODB.FileStorage
Storage=FileStorage.FileStorage('/stores/fs1.fs', read_only=1)
I then start start.py with the argument::
python lib/python/ZEO/start.py -U /xxx/var/zeo.sock \
-S 1=/stores/fs:Storage
This option says to serve storage '1'. Storage '1' is
found in attribute 'Storage' from the module
'/stores/fs'.
Now consider a more complicated example. I want to serve the storage
from the previous example. I also want to serve two Oracle
storages that are defined in the file '/stores/oracle.py'::
import DCOracle, DCOracleStorage
system=DCOracleStorage.DCOracleStorage(
lambda : DCOracle.Connect('system/manager@spamservice')
)
scott=DCOracleStorage.DCOracleStorage(
lambda : DCOracle.Connect('scott/tiger@spamservice')
)
I simply need to include three -S options::
python lib/python/ZEO/start.py -U /xxx/var/zeo.sock \
-Ssystem=/stores/oracle:system \
-Sscott=/stores/oracle:scott \
-S1=/stores/fs:Storage
In this case, we made the storage and attribute name the
same. To connect to the 'system' or 'scott' storage, we
need to specify the storage in the ClientStorage constructor, as
in::
import ZEO.ClientStorage
Storage=ZEO.ClientStorage.ClientStorage(
'/xxx/var/zeo.sock', storage='scott')
Options
The ZEO server start script is run with one or more command line
options. An optional FileStorage file name may be provided after the
options. The options are as follows:
-D -- Run in debug mode
In debug mode, the process is not run in the background
and detailed debugging information is logged.
Note that to actually log this information, you need to
configure logging to include very low-severity (< -300) log
entries. For example, to configure the stupid logger to log
these messages, set the environment veriable
'STUPID_LOG_SEVERITY' to -999.
-U -- Unix-domain socket file to listen on
If you want to accept connections on a Unix domain socket, then
use this option to specify the socket file name.
-u username or uid number
The username to run the ZEO server as. You may want to run
the ZEO server as 'zope' or some other user with limited
resouces. The only works under Unix, and if ZServer is
started by root.
If the server *is* started as root, the 'nobody' user if this
option isn't used.
-p port -- port to listen on
Use this option together with the '-h' option to specify a host
and port to listen on.
-h adddress -- host address to listen on
Use this option together with the '-p' option to specify a host
and port to listen on.
-s -- Don't use zdeamon
This option has no effect on Unix.
-S storage_name=module_path:attr_name -- A storage specification
where:
storage_name -- is the storage name used in the ZEO protocol.
This is the name that you give as the optional
'storage' keyword argument to the ClientStorage constructor.
module_path -- This is the path to a Python module
that defines the storage object(s) to be served.
The module path should ommit the prefix (e.g. '.py').
attr_name -- This is the name to which the storage object
is assigned in the module.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7