Skip to main content

Support for PostgreSQL's hstore for Django.

Project description

Django-hstore is a niche library which integrates the hstore extension of PostgreSQL into Django, assuming one is using Django 1.2+, PostgreSQL 9.0+, and Psycopg 2.3+.


  • Due to how Django implements its ORM, you will need to use the custom postgresql_psycopg2 backend defined in this package, which naturally will prevent you from dropping in other django extensions which require a custom backend (unless you fork and combine).

  • PostgreSQL’s implementation of hstore has no concept of type; it stores a mapping of string keys to string values. This library makes no attempt to coerce keys or values to strings.

Running the tests

Assuming one has the dependencies installed, and a PostgreSQL 9.0+ server up and running:

python test


First, update your settings module to specify the custom database backend:

    'default': {
        'ENGINE': 'django_hstore.postgresql_psycopg2',

Note to South users: If you keep getting errors like There is no South database module ‘south.db.None’ for your database., add the following to

SOUTH_DATABASE_ADAPTERS = {'default': 'south.db.postgresql_psycopg2'}

The library provides three principal classes:


An ORM field which stores a mapping of string key/value pairs in an hstore column.


An ORM field which builds on DictionaryField to store a mapping of string keys to django object references, much like ForeignKey.


An ORM manager which provides much of the query functionality of the library.

Model definition is straightforward:

from django.db import models
from django_hstore import hstore

class Something(models.Model):
    name = models.CharField(max_length=32)
    data = hstore.DictionaryField()
    objects = hstore.HStoreManager()

    def __unicode__(self):

You then treat the data field as simply a dictionary of string pairs:

instance = Something.objects.create(name='something', data={'a': '1', 'b': '2'})
assert['a'] == '1'

empty = Something.objects.create(name='empty')
assert == {}['a'] = '1'
assert Something.objects.get(name='something').data['a'] == '1'

You can issue indexed queries against hstore fields:

# equivalence
Something.objects.filter(data={'a': '1', 'b': '2'})

# subset by key/value mapping
Something.objects.filter(data__contains={'a': '1'})

# subset by list of keys
Something.objects.filter(data__contains=['a', 'b'])

# subset by single key

You can also take advantage of some db-side functionality by using the manager:

# identify the keys present in an hstore field
>>> Something.objects.hkeys(, attr='data')
['a', 'b']

# peek at a a named value within an hstore field
>>> Something.objects.hpeek(, attr='data', key='a')

# do the same, after filter
>>> Something.objects.filter('data', key='a')

# remove a key/value pair from an hstore field
>>> Something.objects.filter(name='something').hremove('data', 'b')

The hstore methods on manager pass all keyword arguments aside from attr and key to .filter().

Project details

Download files

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

Source Distribution

django-hstore-1.1.1.tar.gz (13.3 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page