mxODBC Plone/Zope DA

mxODBC Database Adapter for Plone and Zope

Connect your Plone/Zope installation to all ODBC compliant databases and data sources in a hassle-free, robust and scalable way - with our easy to use mxODBC Database Adapter for Plone and Zope.
Version: 2.2.3

Introduction

The mxODBC Zope DA product allows you to easily connect your Zope installation or Plone CMS to just about any database backend on the market today, giving you the reliability of the commercially supported eGenix.com product mxODBC and the flexibility of the ODBC standard as middle-tier architecture.

mxODBC Zope DA works on Windows, Linux, Mac OS X, FreeBSD, Solaris and AIX, providing you with the same interface, flexibility and robustness across all on all these platforms.

The mxODBC Zope DA implements thread-safe connection pooling and multiple physical connects per logical Zope connection. You can safely run Z SQL Methods in parallel, achieving a much better performance than other Zope database adapters under heavy load. This makes it ideal for deployment in ZEO Clusters and Zope hosting environments where stability and high performance are a top priority.

mxODBC Zope DA for Plone 4 and Plone 5 Database Applications

Our new version mxODBC Zope DA 2.2 was specifically engineered to make it easy to install the adapter in the Plone 4.x and 5.0 versions. It fully integrates into the zc.buildout installation system used by these Plone versions and supports Python versions 2.6 and 2.7.

If you need database access for older Plone/Zope releases, please consider using version 2.0 or version 1.0 of our mxODBC Zope DA product. These support Zope versions as old as Zope 2.3.

mxODBC Zope DA for Zope 2.12 and 2.13 Database Applications

mxODBC Zope DA is made available as egg archives that can be installed via the zc.buildout installation system used by Zope 2.12 and 2.13. You can use the same installation instructions as for Plone to get the Zope DA installed.

Zope and Relational Database Systems (RDBMS)

At EuroPython 2007, we gave a talk about Zope and relational database systems (RDBMS). The talk provides a high-level introduction on how Zope can be used for database web applications and where the mxODBC Zope DA can help. Please see our Presentations & Talks section for details.

Features

  • Zope Level 3 Database Adapter: the mxODBC Zope DA is fully multi-threaded and can handle multiple connections to multiple databases.

  • Fully compatible to standard Z SQL Methods.

  • Fully compatible with Zope External Methods and Zope's built-in transaction mechanism: use Connection Objects in Python modules set up as Zope External Methods to all the features of the mxODBC Zope DA from Python and even tap into the low-level features of mxODBC within Zope's transaction mechanism.
  • Full support of Stored Procedures: when using Zope External Methods, you have full access to SQL stored procedures, which allows direct integration with external database APIs.
  • Connection Pooling: physical database connections are pooled and kept open, to reduce the connection overhead to a minimum. This is especially important for high latency database connections and ones like Oracle which take a considerable amount of time to setup

  • Parallel Execution of Queries on a single logical connection: the mxODBC Zope DA can manage any number of physical connections on a single logical connection. This enables running truly parallel Z SQL Method queries -- a feature not available in other Zope DAs.

  • Zero Maintenance Mode of Operation: connections which are having temporary network problems are automatically reconnected as they become available again.

  • Full Unicode Support: The Zope DA can communicate with the database using Unicode, 8-bit strings or a mix of the two. It provides automatic conversion as necessary to make it possible to adapt the database or the Zope application to the required needs.
  • Full 64-bit Support: The underlying mxODBC 3.3 library fully supports 64-bit platforms such as Windows Server 2008, Mac OS X 10.6 (Snow Leopard) and 64-bit Linux systems.
  • Compatible with all recent Zope and Python releases: Supports Zope 2.12 and 2.13; supports Python 2.6 and 2.7. If you need support for older Zope releases, please use version 2.0 or version 1.0 of our mxODBC Zope DA.
  • Compatible with Plone 4.0 - 4.3 and Plone 5.0: The zc.buildout compatible installation process allows easy integration with your existing Plone  4.x and 5.0 installations.
  • Based on mxODBC 3.3: The mxODBC Zope DA uses mxODBC 3.3 to connect Plone and Zope to ODBC data sources and provides access to many of its advanced features, as well as its robust ODBC driver compatibility.
  • Compatible with all major ODBC managers: mxODBC 3.3 supports the Windows ODBC manager, the Mac OS X ODBC manager and the three most popular ODBC managers on Linux: unixODBC, iODBC and DataDirect.
  • Cross-platform Connection Objects: The Zope DA will automatically choose the right platform specific ODBC manager for you.

  • Per Connection Adjustable ODBC Interface: mxODBC comes with many different subpackages to choose from on Unix. The Zope DA allows you to select these subpackages on a per-connection basis.

  • Per Connection Error Handling: you can tell each connection whether it should report ODBC warnings or not; furthermore all warnings and errors are made available as list .messages on the DatabaseConnection object.

  • Per Connection Cursor Type: The ODBC cursor type used on the connection can be adjusted to the application's result set needs, ranging from the high performance forward only cursors to the slower but more predictable static cursors.
  • Transaction-safe Automatic Reconnect: when the DA finds that a connection has timed out, it automatically tries a reconnect and replays the transaction on the connection (unlike other DAs which break the transaction scheme by doing a reconnect without replay).

  • Built-in Schema Cache: this results in improved performance under heavy load.

  • Database Schema Access: all ODBC catalog methods are made available for much better database schema inquiry. The catalog methods allow building generic database interrogation or manipulation tools and facilitates writing database independent Zope products.

  • Native Support for Python data types: the Zope DA can optionally use Python datetime object, decimal objects in result sets to simplify integration. It also supports Zope's DateTime objects, mxDateTime objects, strings and tuples.
  • Lazy Connect: the mxODBC Zope DA only connects to the database backends when a connection is actually requested. This results in a better use of resources compared to other Zope DAs.

  • Fully compatible to the popular Znolk SQL Wizard Product and other similar products relying on the common database schema access methods .tables() and .columns().

System Requirements

The mxODBC Zope DA distribution includes all software needed to connect Zope to an ODBC manager. However, it does not include an ODBC manager or any ODBC drivers. You have to have these installed in order to be able to use mxODBC Zope DA.

Windows:

On Windows, the situation is very simple: most databases come with ODBC drivers and register them with the Windows ODBC manager that's part of every Windows system.

Please consult the ODBC driver documentation for details on how to setup ODBC data sources. The mxODBC Zope DA Administration and User Manual also includes a section on this topic and some helpful hints in case you run into problems.

Linux, FreeBSD, Solaris, AIX:

On Unix, you will have to install one of the popular ODBC managers iODBC, unixODBC or DataDirect and then register the ODBC drivers for your database with these ODBC managers.

Linux systems usually come with at least one of these ODBC managers preinstalled. Please see the mxODBC Zope DA Administration and User Manual for setup instructions.

Mac OS X:

On Mac OS X, you can use the system system ODBC manager (which actually is a version of the popular iODBC manager). If this is not installed on your system, you can download it from Apple or use the alternative ODBC Manager which is maintained by Actual Technologies.

Please see the mxODBC Zope DA Administration and User Manual for setup instructions.

Licensing

The mxODBC Zope DA product is a commercial product and made available under the terms and conditions of the eGenix.com Commercial License Agreement, Version 1.3.0 (PDF file).

When purchasing a license for the mxODBC Zope DA product, you will receive a digitally signed Proof of Authorization authorizing you to install the product for use within one Zope Instance.

If you are using Zope clusters or multiple Zope instances on a single machine, you will have to buy one Zope Instance license per Zope instance that you have installed on the machine.

Evaluation

If you would like to evaluate the mxODBC Zope DA, please request an evaluation license or send an email to the eGenix.com Sales Team and include the following information: name of the licensee, number of evaluation licenses.

We will then send you the requested number of evaluation licenses. The evaluation licenses have a built-in timeout of 30 days, but are otherwise fully functional.

If you are satisfied with the product, you can then proceed to the next section.

Buy Licenses

Production licenses for the mxODBC Zope DA product can be bought via our eGenix.com Online Shop. For quotes on prices, volume discounts, site and corporate licenses please write to sales@egenix.com.

After purchase, you will receive the necessary license files from eGenix.com within two business days by email to the address you specified in the ordering process.

If you need to buy licenses for third parties (e.g. as contractor), please contact sales@egenix.com for instructions.

If you have questions about the ordering process, or the needed number of licenses, please write to the eGenix.com Sales Team.

License Upgrades

If you are intending to upgrade from an existing mxODBC Zope DA license to the new mxODBC Zope DA 2.2, please contact the eGenix.com Sales Team with your existing license serials for details for an upgrade discount coupon.

We will give out 20% discount coupons for upgrade purchases going from mxODBC Zope DA 1.x to 2.2 and 50% coupons for upgrades from mxODBC Zope 2.x to 2.2. After upgrade, use of the original license from which you upgraded is no longer permitted.

Documentation

The following documentation is available for the mxODBC Zope DA:

mxODBC Zope DA Administration and User Manual - HTML and PDF

This manual includes instructions on how to install, configure and use the mxODBC Zope DA as well as a reference of the available programming interfaces.

mxODBC Reference Manual - HTML and PDF

The mxODBC Reference describes the included eGenix.com product mxODBC which is used by the mxODBC Zope DA to interface to the various database backends.

Please note that the mxODBC package included in the mxODBC Zope DA can only be used from within Zope and is usually a different version than the stand-alone mxODBC package.

The PDF files are also available as part of the installation. The mxODBC Zope DA Connection help screens provide links to the local copies after installation.

Download

Since Zope 2.12 has switched to egg archives for managing the Zope installation, we have followed that approach for our mxODBC Zope DA and provide egg archives for the various platforms and versions.

You normally do not need to download these egg archives manually, since the easy_install script or zc.buildout will  fetch the right archive for you. Please see the installation instructions for details.

However, if you are installing Zope on a firewall-protected server or intranet server without direct Internet-access, you can also download the egg archives manually and then point the easy_install or buildout to the already downloaded egg archives.

For some platforms, manual download may also be needed due to differences in platform name between our build systems and the target installation systems or due to missing support in setuptools to parse the platform string part of the egg archives.

Please note that these binary distributions do not contain any license keys. You will either have to obtain evaluation licenses or buy production licenses in order to successfully install the package.

These files are made available to you under the terms and conditions of the eGenix.com Commercial License Agreement, Version 1.3.0 (PDF file).

Note: You are not allowed to redistribute these files.

Plone/Zope on Windows (x86 - 32-bit):

>>> URL MD5 SHA1 GPG

Please note: The Plone Windows installers ship with Python 2.6, so you only need the Python 2.7 builds in case you have a manually installed Plone/Zope version.

These egg archives include the mxODBC Zope DA Zope Product and all necessary eGenix.com mx Products (including mxODBC 3.3) prebuilt for Plone/Zope installations in one binary archive.

The Windows ODBC manager which comes with the Windows Operating System will be used by this distribution. On 64-bit Windows versions, the 32-bit variant of the ODBC manager will be used.

For instructions on how to install the egg archives, please see the installation section below.

Plone/Zope on Windows (x64 - 64-bit):

>>> URL MD5 SHA1 GPG

Please note: The Plone 4.3 Windows installers ship with Python 2.6, so you only need the Python 2.7 builds in case you have a manually installed Plone/Zope version. Earlier versions of Plone did not come with a 64-bit Windows installer at all.

These egg archives include the mxODBC Zope DA Zope Product and all necessary eGenix.com mx Products (including mxODBC 3.3) prebuilt for Plone/Zope installations in one binary archive.

The 64-bit variant of the Windows ODBC manager which comes with the Windows Operating System will be used by this distribution.

For instructions on how to install the egg archives, please see the installation section below.

Plone/Zope on Linux (i686 - 32-bit):

>>> URL MD5 SHA1 GPG

These egg archives include the mxODBC Zope DA Zope Product and all necessary eGenix.com mx Products (including mxODBC 3.3) prebuilt for Plone/Zope installations in one binary archive.

You will need to have one of popular ODBC managers for Unix installed on the target system: iODBC 3.52.x or unixODBC 2.3.x. We have successfully tested the Zope DA with iODBC 3.52.7 and unixODBC 2.3.2.

If you are using unixODBC and getting linker errors about a missing libodbc.so.2, please see this posting for help.

For instructions on how to install the egg archives, please see the installation section below.

Plone/Zope on Linux (x86_64 - 64-bit):

>>> URL MD5 SHA1 GPG

These egg archives include the mxODBC Zope DA Zope Product and all necessary eGenix.com mx Products (including mxODBC 3.3) prebuilt for Plone/Zope installations in one binary archive.

You will need to have one of popular ODBC managers for Unix installed on the target system: iODBC 3.52.x or unixODBC 2.3.x. We have successfully tested the Zope DA with iODBC 3.52.7 and unixODBC 2.3.2.

If you are using unixODBC and getting linker errors about a missing libodbc.so.2, please see this posting for help.

For instructions on how to install the egg archives, please see the installation section below.

Plone/Zope on Mac OS X (PPC + Intel - 32-bit):

>>> URL MD5 SHA1 GPG

These egg archives include the mxODBC Zope DA Zope Product and all necessary eGenix.com mx Products (including mxODBC 3.3) prebuilt for Plone/Zope installations in one binary archive.

Note that Mac OS X comes with a UCS2 build of Python, so please try the UCS2 product versions first.

Mac OS X ships with the iODBC ODBC manager as system default ODBC manager. Please configure your data sources using the system ODBC manager. If you instead want to use the unixODBC manager from MacPorts, you additionally have to add the ports lib dir to DYLD_LIBRARY_PATH, e.g. using export DYLD_LIBRARY_PATH=/opt/local/lib

For instructions on how to install the egg archives, please see the installation section below.

Plone/Zope on Mac OS X (Intel - 64-bit):

>>> URL MD5 SHA1 GPG

These egg archives include the mxODBC Zope DA Zope Product and all necessary eGenix.com mx Products (including mxODBC 3.3) prebuilt for Plone/Zope installations in one binary archive.

Note that Mac OS X comes with a UCS2 build of Python, so please try the UCS2 product versions first.

Mac OS X ships with the iODBC ODBC manager as system default ODBC manager. Please configure your data sources using the system ODBC manager. If you instead want to use the unixODBC manager from MacPorts, you additionally have to add the ports lib dir to DYLD_LIBRARY_PATH, e.g. using export DYLD_LIBRARY_PATH=/opt/local/lib

For instructions on how to install the egg archives, please see the installation section below.

Plone/Zope on FreeBSD (i386 - 32-bit):

>>> URL MD5 SHA1 GPG

These egg archives include the mxODBC Zope DA Zope Product and all necessary eGenix.com mx Products (including mxODBC 3.3) prebuilt for Plone/Zope installations in one binary archive.

You will need to have one of popular ODBC managers for Unix installed on the target system: iODBC 3.52.x or unixODBC 2.3.x. We have successfully tested the Zope DA with iODBC 3.52.7 and unixODBC 2.3.2.

For instructions on how to install the egg archives, please see the installation section below.

Plone/Zope on FreeBSD (AMD64 - 64-bit):

>>> URL MD5 SHA1 GPG

These egg archives include the mxODBC Zope DA Zope Product and all necessary eGenix.com mx Products (including mxODBC 3.3) prebuilt for Plone/Zope installations in one binary archive.

You will need to have one of popular ODBC managers for Unix installed on the target system: iODBC 3.52.x or unixODBC 2.3.x. We have successfully tested the Zope DA with iODBC 3.52.7 and unixODBC 2.3.2.

For instructions on how to install the egg archives, please see the installation section below.

Plone/Zope on Solaris and AIX:

Solaris and AIX binaries can be made available on demand.

Source Code:

mxODBC Zope DA is a commercial product for which we don't distribute the source code.

Other Platforms

If you have requirements for other platforms or Zope versions, please send us a note. The mxODBC Zope DA will compile on most Unix-like platforms where iODBC and/or unixODBC are available.

We can also prepare special versions which link directly against the database ODBC drivers. This may in some cases give you access to more advanced native database features.

Dependencies

In addition to the mxODBC Zope DA you will also need to download and install the following two dependencies:

Python Unicode Version (UCS2 vs. UCS4)

On Unix it is important to know whether you need to download a distribution for a narrow Unicode build of Python (UCS2) or a wide version (UCS4).

Most Unixes ship with wide UCS4 Python builds these days (including RedHat and SuSE). In order to make sure, please run the following command which will tell you what kind of Python installation you have:

bin/zopepy -c "import sys;print(sys.maxunicode<66000)and'UCS2'or'UCS4'"

If you get errors such as "unresolved symbol PyUnicodeUCS2_AsEncodedString" when trying to load an extension from the distribution, you have likely installed an archive for a wrong Unicode version.

Installation

Please see the mxODBC Zope DA Administration and User Manual on how to install and setup the package. It is available as PDF for offline reading and HTML for online reading:

If you already know how to install the mxODBC Zope DA, you can also follow the  quick install instructions.

Quick Install Guide for standalone Plone/Zope Instances

Please note that these instructions are based on a typical Plone/Zope installation such as the one that comes with Zope and the Plone Unified Installer. Depending on your installation, the configuration files may require slightly different settings and parts.

In the buildout.cfg file and add/adapt the following content:

[buildout]
...

### Add eGenix Index to the buildout setup
#
# IMPORTANT: Use the URL
# https://downloads.egenix.com/python/index/ucs2/
# if your Python version is a UCS build. If you have a UCS4
# build of Python, use the URL
# https://downloads.egenix.com/python/index/ucs4/
#
find-links =
...
https://downloads.egenix.com/python/index/ucs2/

# If your buildout.cfg has an entry allow-hosts, you need
# to add our server to that list as well:
allow-hosts =
...
downloads.egenix.com

### Add eGenix mxODBC Zope DA eggs
#
# ThreadLock and Products.ZSQLMethods are dependencies of the
# egenix-mxodbc-zopeda, but included here for completeness, since
# you have to add versions for these further below.
#
# The new egenix-mxodbc-zopeda-license part takes care of
# automatically installing your license files in the instance.
#
eggs =
...
egenix-mxodbc-zopeda
ThreadLock
Products.ZSQLMethods

parts =
...
egenix-mxodbc-zopeda-license

...

# Add this new section:

### Install the Zope instance licenses for egenix-mxodbc-zopeda
#
# This part copies the license files you extracted to the
# instance directory to the right directory on the instance's
# Python path.
#
# IMPORTANT: You need to replace ***license-serial*** with the
# directory containing the mxodbc_zopeda_license.py file for
# your instance.
#
[egenix-mxodbc-zopeda-license]
recipe = collective.recipe.template
input = ***license-serial***/mxodbc_zopeda_license.py
output = ${instance:location}/lib/python/mxodbc_zopeda_license.py

### Define versions of packages to be used
#
# buildout will automatically use the latest version it finds
# for building instances. This may not always be what you
# want, so it's usually better to pin down the version you're
# interested in.
#
[versions]
...
egenix-mxodbc-zopeda = 2.2.3
ThreadLock = 2.13.0.1
Products.ZSQLMethods = 2.13.4
collective.recipe.template = 1.9

In the above file, you have to make two adjustments:

  • Adjust the URL used in the find-links directive to use either the ucs2/ or the ucs4/ version of the eGenix PyPI-style distribution index.
  • Adjust the egenix-mxodbc-zopeda version to the one that you would like to use.
  • Replace the ***license-serial***/ path component with the license directory containing the license for the instance you are configuring. The directories extracted from the license.zip file  are usually named after the license serial, e.g. 2100-8789-0322-0926-2568-6429/.
  • The ThreadLock egg which includes a Python C extension will be downloaded from our indexes as well. We provide binaries for all supported platforms to avoid the need to have a compiler installed for the buildout run. Please see our ThreadLock distribution release announcement for details.

After a buildout run and restart of the Plone/Zope Instance, you will then find a new entry for the eGenix mxODBC Zope DA Connection object in the Zope Management Interface (ZMI) add object drop-downs.

Quick Install Guide for ZEO Plone/Zope Clusters

For a ZEO cluster installation with two client instances, you can use the same approach as above, but you instead of having only one license installed, you need to adjust the buildout.cfg file to make sure the two needed licenses are installed correctly:

[buildout]
...
parts =
...
egenix-mxodbc-zopeda-license-client1
egenix-mxodbc-zopeda-license-client2
...

# Add these new sections:

### Install the Zope instance licenses for egenix-mxodbc-zopeda
#
# This part copies the license files you extracted to the
# instance directory to the right directory on the client
# instance's Python path.
 
# ZEO Client 1
#
# IMPORTANT: You need to replace ***license-serial-1*** with the 
# directory containing the mxodbc_zopeda_license.py file for
# your client1 instance.
#
[egenix-mxodbc-zopeda-license-client1]
recipe = collective.recipe.template
input = ***license-serial-1***/mxodbc_zopeda_license.py
output = ${client1:location}/lib/python/mxodbc_zopeda_license.py
 
# ZEO Client 2
#
# IMPORTANT: You need to replace ***license-serial-2*** with the 
# directory containing the mxodbc_zopeda_license.py file for
# your client1 instance.
#
[egenix-mxodbc-zopeda-license-client2]
recipe = collective.recipe.template
input = ***license-serial-2***/mxodbc_zopeda_license.py
output = ${client2:location}/lib/python/mxodbc_zopeda_license.py

After a buildout run and restart of the Plone/Zope cluster, you will then find a new entry for the eGenix mxODBC Zope DA Connection object in the Zope Management Interface (ZMI) add object drop-downs.

Please see the mxODBC Zope DA documentation for more details on the ZEO cluster installation.

Installation using pip and virtualenv

Starting with mxODBC Zope DA 2.2.3, it is also possible to use pip install for installing the mxODBC Zope DA:

virtualenv .
bin/pip install Zope2 ThreadLock Products.ZSQLMethods egenix-mxodbc-zopeda

You will then need to install the license files by copying them to the lib/python/ directory of your Zope instance.

Reviews

If you prefer third-party reviews, have a look at these independent product reviews:

Support

eGenix offers these support options:

Commercial Support

Professional level support for this product as well as all other eGenix products and Python itself is available directly from the developers at eGenix.com.

Consulting

eGenix.com offers professional consulting services for all questions and tasks around this product, including customized modifications, help with integration and on-site problem solving. Please contact sales@egenix.com for details.

Free User Support

In order for our users to keep in touch and be able to help themselves, we have created the egenix-users user mailing list.

References

The mxODBC Zope DA is in production use on several high-volume Zope sites, among these some very well-known companies in the industry. Please write to sales@egenix.com for more information.

History & Changes

Please see the change log for details regarding changes to the package between releases.

Older versions of the mxODBC Zope DA which are still available: