Limitations

PostgreSQL’s implementation of hstore has no concept of type; it stores a
mapping of string keys to string values. Values are stored as strings in the
database regarding of their original type.

Hstore extension is not automatically installed on use this package. You must install it manually.

To run tests, hstore extension must be installed on template1 database.

If django.middleware.transaction.TransactionMiddleware is enabled and the project is deployed
through uwsgi, the first request to a view working with models featuring hstore fields will raise an exception;
see Django Ticket #22297 for more details on this issue. This issue is specific to Django 1.6 and below.

Important Note: the future version of HStore will bring types, nested structures and more advanced features, for more info read On the state of HStore by Engine Yard.

Setup

Upgrade from older versions

In version 1.2.x some internals have been changed in order to simplify usage and prevent errors.

Values are automatically converted to strings, fields costantly validate input and so on.

If you are upgrading from an older version ensure your application code works as expected. If it doesn’t you will either have to update your code or tie your application’s requirement to the older version of django-hstore (1.1.1).

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
settings.py:

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

Admin widget

django-hstore ships a nice admin widget that makes the field more user-friendly.

Each time a key or a value is modified the underlying textarea is updated:

Grappelli Admin widget

If you use the awsome django-grappelli there’s an even nicer looking widget for you too!

Each time a key or a value is modified the underlying textarea is updated:

Usage

The library provides three principal classes:

django_hstore.hstore.DictionaryField

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

django_hstore.hstore.ReferencesField

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

django_hstore.hstore.HStoreManager

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

django_hstore.hstore.HStoreGeoManager

An additional ORM manager to provide Geodjango functionality as well.

Model fields

Model definition is straightforward:

fromdjango.dbimportmodelsfromdjango_hstoreimporthstoreclassSomething(models.Model):name=models.CharField(max_length=32)data=hstore.DictionaryField()# can pass attributes like null, blank, ecc.objects=hstore.HStoreManager()# IF YOU ARE USING POSTGIS:# objects = hstore.HStoreGeoManager()

# equivalenceSomething.objects.filter(data={'a':'1','b':'2'})# comparison (greater than, less than or equal to, ecc)Something.objects.filter(data__gt={'a':'1'})Something.objects.filter(data__gte={'a':'1'})Something.objects.filter(data__lt={'a':'2'})Something.objects.filter(data__lte={'a':'2'})# subset by key/value mappingSomething.objects.filter(data__contains={'a':'1'})# subset by list of some key valuesSomething.objects.filter(data__contains={'a':['1','2']})# subset by list of keysSomething.objects.filter(data__contains=['a','b'])# subset by single keySomething.objects.filter(data__contains=['a'])

You can still do classic django “contains” lookups as you would normally do for normal text
fields if you were looking for a particular string. In this case, the HSTORE field
will be converted to text and the lookup will be performed on all the keys and all the values:

HSTORE manager

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(id=instance.id,attr='data')['a','b']# peek at a a named value within an hstore field>>>Something.objects.hpeek(id=instance.id,attr='data',key='a')'1'# do the same, after filter>>>Something.objects.filter(id=instance.id).hpeek(attr='data',key='a')'1'# 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().

ReferenceField Usage

ReferenceField is a field that allows to reference other database objects
without using a classic ManyToMany relationship.

Here’s an example with the ReferenceContainer model defined in the Model fields section:

The database is queried only when references are accessed directly.
Once references have been retrieved they will be stored for any eventual subsequent access:

r=ReferenceContainer.objects.get(name='test')# this won't query the databaser.refs{u'another_object':u'myapp.models.AnotherModel:1',u'some_object':u'myapp.models.AnotherModel:2'}# this will query the databaser.refs['another_object']'<AnotherModel: AnotherModel object>'# retrieved reference is now visible also when calling the HStoreDict object:r.refs{u'another_object':<AnotherModel:AnotherModelobject>,u'some_object':u'myapp.models.AnotherModel:2'}

Multiple database setup

If for some reason you have to use django-hstore in a multi-database setup and
some of the database you are using don’t have the hstore extension installed,
you can skip hstore registration by setting HAS_HSTORE to False in your
database config:

Running the tests

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

python runtests.py

By default the tests run with the postgis backend.

If you want to run the tests with psycopg2 backend you can do:

python runtests.py --settings=settings_psycopg

You might need to tweak the DB settings according to your DB configuration.
If you need to do so you can copy the file local_settings.py.example to local_settings.py and add
your database tweaks on it. local_settings.py will be automatically imported in settings.py.
The same applies for local_settings_psycopg.py.example, which will be imported in
local_settings_psycopg.py.

Deprecation policy

At any momment of time, django-hstore developers will mantain support for three versions of django.

As example: The current stable release of django is 1.6, so django-hstore official supported versions are: 1.4, 1.5 and 1.6. When
django 1.7 is released, 1.4 version will become on unsupported django version.