Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Using Django and ZODB together

Project Description


Django-ZODB is a simple ZODB database backend for Django Framework. It’s strongly inpired in repoze.zodbconn.


Django-ZODB requires the following packages:

If you need to store your data in a RDBMS system you will need to install the following packages too:

  • RelStorage 1.5.0a1 or newer - ZODB storage system that store pickles in a relational database (in a non-relational format).
  • MySQLdb 1.2.3 or newer - required to connect MySQL database.
  • psycopg2 2.3.0-beta1 or newer - required to connect PostgreSQL database.
  • cx_Oracle 5.0.3 or newer - required to connect Oracle database.


Not tested with psycopg2 and cx_Oracle but we believe that everything will work as expected because we use RelStorage to connect to the database.

Install from sources:

$ python install

Or from PyPI (using easy_install):

$ easy_install -U django-zodb

Running tests

Install coverage if you need test coverage informations:

$ easy_install -U coverage

To run tests:

$ python test


You need to configure your like this:

ZODB = {
    'default': [
    'test':      [ 'mem://', 'mem://?database_name=catalog' ],
    'legacy_db': [ 'zconfig:///srv/www/zodb_media.conf' ],
    'user_dir':  [
    'old_app':   [

You can find a list of schemes and connection adapters in Connection Schemes.

Creating sample application

I strongly believe in “learn by doing” strategy, so, let’s create a sample Wiki application that stores their pages in ZODB.

I suggest the reading of the following tutorials and articles if you don’t know ZODB or the Traversal Algorithm (that we will use in our tutorial):


Repoze.BFG is now known as Pyramid.

Starting Django Project and Application

We will start a project called intranet with a Django application called wiki:

$ startproject intranet
$ cd intranet
intranet $ python startapp wiki

Now we need to modify our to include this new application and configure our database connections:

#!/usr/bin/env python

import os
ROOTDIR = os.path.dirname(os.path.realpath(__file__))

# No relational database...
DATABASE_NAME = ':memory:'

# append the following lines:
ZODB = {
    'default': ['file://' + os.path.join(ROOTDIR, 'wiki_db.fs')],

# ... other Django configurations ...

    # ... other middlewares ...

    # If everything is ok (aka no exception raised) this middleware will
    # run a transaction.commit() on response.

    'django_zodb',  # enable zshell command

Let’s create our model classes. We will need a “root” object that will store our objects (let’s name it Wiki) and a model to store the wiki pages itself (Page):

#!/usr/bin/env python
# wiki/

import markdown  #
from django_zodb import models

# models.RootContainer - Define a 'root' object for database. This class
#                        defines __parent__ = __name__ = None
class Wiki(models.RootContainer):
    def pages(self):
        for pagename in sorted(self):
            yield self[pagename]

    def get_absolute_url(self):
        return "/wiki"

    # It's possible to change models.RootContainer settings using Meta
    # configurations. Here we will explicitly define the default values
    class Meta:
        database = 'default'  # Optional. Default: 'default'
        rootname = 'wiki'     # Optional. Default: RootClass.__name__.lower()

# models.Container - We will use Container to add support to subpages.
class Page(models.Model):
    def __init__(self, content="Empty Page."):
        super(Page, self).__init__()
        self.content = content

    def html(self):
        md = markdown.Markdown(safe_mode="escape",
                extensions=('codehilite', 'def_list', 'fenced_code'))
        return md.convert(self.content)

    def name(self):
        return self.__name__

    def get_absolute_url(self):
        return u"/".join((self.__parent__.get_absolute_url(),

We’ve a configured application and models. It’s time to map an URL to our view function:

#!/usr/bin/env python

# ... Django default URL configurations ...

urlpatterns = patterns('',
    # ... other URL mappings ...
    (r'^(?P<path>.*)/?$', ''),

And wiki/

#!/usr/bin/env python

import re

from django.shortcuts import render_to_response
from django.http import HttpResponseRedirect
from django import forms

import transaction
from django_zodb import views
from django_zodb import models

from import Wiki, Page

wikiwords = re.compile(ur"\b([A-Z]\w+([A-Z]+\w+)+)")

class PageEditForm(forms.Form):
    content = forms.CharField(widget=forms.Textarea)

class WikiView(views.View):
    def __index__(self, request, context, root, subpath, traversed):
        return HttpResponseRedirect("FrontPage")

    def add(self, request, context, root, subpath, traversed):
            name = subpath[0]
        except IndexError:
            return HttpResponseRedirect("/")

        if request.method == "POST":
            form = PageEditForm(request.POST)
            if form.is_valid():
                page = Page(form.cleaned_data['content'])
                root[name] = page
                return HttpResponseRedirect(page.get_absolute_url())
            form = PageEditForm()

        page_data = {
            'name': name,
            'cancel_link': "javascript:history.go(-1)",
            'form': form,
        return render_to_response("edit.html", page_data)
views.registry.register(model=Wiki, view=WikiView())

class PageView(views.View):
    def __index__(self, request, context, root, subpath, traversed):
        content = context.html()

        def check(match):
            word =
            if word in root:
                page = root[word]
                view_url = page.get_absolute_url()
                return '<a href="%s">%s</a>' % (view_url, word)
                add_url = models.model_path(root, "", "add", word)
                return '<a href="%s">%s</a>' % (add_url, word)

        content = wikiwords.sub(check, content)

        page_data = {
            'context': context,
            'content': content,
            'edit_link': context.get_absolute_url() + "/edit",
            'root': root,
        return render_to_response("page.html", page_data)

    def edit(self, request, context, root, subpath, traversed):
        context_path = models.model_path(context)

        if request.method == "POST":
            form = PageEditForm(request.POST)
            if form.is_valid():
                context.content = form.cleaned_data['content']
                return HttpResponseRedirect(context_path)
            form = PageEditForm(initial={'content': context.content})

        page_data = {
            'context': context,
            'cancel_link': context_path,
            'form': form,
        return render_to_response("edit.html", page_data)
views.registry.register(model=Page, view=PageView())

def create_frontpage(root):
    frontpage = Page()
    root["FrontPage"] = frontpage
    return root

def page(request, path):
    root = models.get_root(Wiki, setup=create_frontpage)
    return views.get_response_or_404(request, root=root, path=path)


From Repoze.BFG documentation:

Traversal is a context finding mechanism. It is the act of finding a context and a view name by walking over an object graph, starting from a root object, using a request object as a source of path information.

Django-ZODB implements the traversal algorithm in function django_zodb.views.traverse() that receive two arguments:

  • root - an instance of Root model.
  • path - a string with the path to be traversed.

And return a views.TraverseResult object with the following attributes:

  • context - model object found by traversal.
  • method_name - a method name if exists.
  • subpath - aditional path arguments.
  • traversed - path elements ‘traversed’.
  • root - root object.

We’ve created some shortcuts functions to interpret these results:

  • get_response(request, root, path) -> HttpResponse
  • get_response_or_404(request, root, path) -> HttpResponse or Http404

These functions will traverse the model tree and call a registered view function that handle the context model object found. For example:

def handle_page_objects(request, result):
    # result is a TraverseResult object.
    # result.context is a Page object found by traverse
    return render_to_response(...)

# Register handle_page_objects function to handle Page objects:
views.registry.register(model=Page, view=handle_page_objects)

You can register a views.View() instance to handle model objects:

class PageView(views.View):
    # This is the 'default' handle (no method_name)
    def __index__(self, request, context, root, subpath, traversed):
        # ... context is a Page object ...
        return render_to_response(...)

    # called when method_name == "edit"
    def edit(self, request, context, root, subpath, traversed):
        # ... context is a Page object ...
        return render_to_response(...)

# Register a PageView *instance* to handle Page objects
views.registry.register(model=Page, view=PageView())

Connection Schemes

You can specify a ZODB connection using a URI. This URI is composed of the following arguments:


Depending on the chosen scheme some of these arguments are required and others optional.

Database and Connection settings

Arguments related to database connection settings. These arguments are optional and must be passed as query argument in URI (eg. ?database_name=db&...).

  • database_name - str - database name used by ZODB.
  • connection_cache_size - int - size (in bytes) of database cache.
  • connection_pool_size - int - size of connection pool.

These arguments are passed to ZODB.DB.DB() constructor.

Memory Storage mem: (ZODB.MappingStorage)

Returns an in-memory storage. It’s basically a Python dict() object.

Valid URIs:

Optional Arguments

File Storage file: (ZODB.FileStorage)

Returns a database stored in a file. You need to specify an absolute path to the database file.

Valid URIs:


Invalid URIs:

Required Arguments
  • path - str - absolute path to file where database will be stored.
Optional Arguments
  • create - bool - create database file if does not exist. Default: create=True.
  • read_only - bool - open storage only for reading. Default: read_only=False.
  • quota - int - storage quota. Default: disabled (quota=None).
  • See Demo storage argument.
  • See Blob storage arguments.

zconfig: (ZODB.DB.DB)

Returns database (or databases) specified in ZCML configuration file.


This scheme has some small differences with other schemes because it returns a DB object instead of a Storage. It’s a problem only in cases where you are creating the connection ‘by hand’ instead of use a higher level API.

URIs Examples:

Required Arguments
  • path (str) - absolute path to file where database will be stored.
Optional Arguments (and default values)
  • #fragment='' (str) - Get only an specific database. By default ('') get only the first database specified in configuration file. We don’t use a query argument (&arg=...) to specify database name to keep compatibility with repoze.zodbconn.

zeo: (ZEO.ClientStorage.ClientStorage)

Returns a connection to a ZEO server.


mysql: (RelStorage)

Returns a database stored in a MySQL relational server. This scheme uses RelStorage to establish connection with database server.

URIs Examples:


postgresql (RelStorage)

Returns a database stored in a PostgreSQL relational server. This scheme uses RelStorage to establish connection with database server.

URIs Examples:


Demo storage argument

  • demostorage (bool) - Enable the ZODB’s demo storage wrapper.

Blob storage arguments

  • blob_dir (str) - Directory where blob objects will be stored.

Relational storage arguments

Django-ZODB uses Relstorage to connect to RDBMS and we preserve the same arguments used by RelStorage. The only difference between RelStorage`s arguments and Django-ZODB arguments is that we use “_” (underline) instead of “-” (dash). For example: the RelStorage’s argument “shared-blob-dir” becomes “shared_blob_dir”.


Hi, I’m accepting all kind of collaborations to this project. You can open issues in our issue tracker, send me a patch, an e-mail message with your questions, etc.

All kind of collaboration will be welcome.


  • Review my ‘engrish’ in documentation
  • Create a new Website
  • Release 0.2 version (and announce)
  • Test Relstorage connections with Oracle and PostgreSQL
  • Create more commands for ZODB management
  • Create a Django-ORM layer (wow!)
  • Evaluate some fulltext-search, catalog, etc integrations
  • Fix performance issues (?)
  • … and fix (tons of) bugs! :D

Release History

History Node


This version
History Node


History Node


History Node


History Node


Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, Size & Hash SHA256 Hash Help File Type Python Version Upload Date
(29.5 kB) Copy SHA256 Hash SHA256
Source None Sep 24, 2015

Supported By

Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Google Google Cloud Servers DreamHost DreamHost Log Hosting