Welcome to django-pgfields¶

Add django_pg to INSTALLED_APPS¶

First, you must add django_pg to your settings module’s INSTALLED_APPS:

INSTALLED_APPS = [
    # your other apps
    'django_pg',
]

It doesn’t matter where in the list you add it, as long as it’s present.

from django_pg import models¶

Second, import django-pgfields’ models module instead of the one supplied by Django.

So, everywhere that you would write this:

from django.db import models

Instead, write this:

from django_pg import models

Internally, django-pgfields loads all of the things provided by the Django models module, subclassing certain items needed to make everything work, and adding the fields it provides.

Lookups¶

When looking up data against an array field, the field supports three lookup types: exact (implied), contains, and len.

exact

The exact lookup type is the implied lookup type when doing a lookup in the Django ORM, and does not need to be explicitly specified. A straight lookup simply checks for array equality. Continuing the example immediately above:

>>> hobbit = Hobbit.objects.get(
    favorite_foods=['apples', 'lembas bread', 'potatoes'],
)
>>> hobbit.name
'Peregrin Took'

contains

The contains lookup type checks to see whether all of the provided values exist in the array. If you only need to check for a single value, and the value is not itself an array (in a nested case, for instance), you may specify the lookup value directly:

>>> hobbit = Hobbit.objects.get(favorite_foods__contains='apples')
>>> hobbit.name
'Peregrin Took'

If you choose to do a contains lookup on multiple values, then be aware that order is not relevant. The database will check to ensure that each value is present, but ignore order of values in the array altogether:

>>> hobbit = Hobbit.objects.get(
    favorite_foods__contains=['lembas bread', 'apples'],
)
>>> hobbit.name
'Peregrin Took'

len

The len lookup type checks the length of the array, rather than its contents. It maps to the array_length function in PostgreSQL (with the second argument set to 1).

Such lookups are simple and straightforward:

>>> hobbit = Hobbit.objects.get(favorite_foods__len=3)
>>> hobbit.name
'Peregrin Took'

Options¶

The JSON field implements the following field options in addition to the field options available to all fields.

type

The type option adds an additional requirement that any value sent to this field must be of that type. The default is None, which will allow any type that is JSON-serializable.

Usage looks like:

data = models.JSONField(type=dict)

Acceptable values for this option are: dict, list, str/unicode (see below), int, float, and bool.

The common use case for this option is to allow code to expect a particular type of value from this field (dict is the most common need).

If you specify this option, an appropriate empty default value of that type will automatically be set. Therefore, the example above is exactly equivalent to:

data = models.JSONField(type=dict, default={})

Values¶

The JSON field will return values back to you in the Python equivalents of the native JavaScript types:

• JavaScript number instances will be converted to int or float as appropriate.
• JavaScript array instances will be converted to Python list instances, and value conversion will be recursively applied to every item in the list.
• JavaScript object instances will be converted to Python dict, and value conversion will be recursively applied to the keys and values of the dictionary.
• JavaScript string instances will be converted to Python 3 str.
• JavaScript boolean instances will be converted to Python bool.
• JavaScript null is converted to Python None.
• JavaScript special values (NaN, Infinity) are converted to their Python equivalents. Use math.isnan and math.isinf to test for them.

The short version: write Python dictionaries, lists, and scalars, and the JSON field will figure out what to do with it.

Options¶

The UUID field implements the following field options in addition to the field options available to all fields.

auto_add

Normally, the UUIDField works like any other Field subclass; you are expected to provide a value, and the value is saved to the database directly.

If auto_add=True is set, then explicitly providing a value becomes optional. If no value is provided, then the field will auto-generate a random version 4 UUID, which will be saved to the database (and assigned to the model instance).

This is a particularly useful construct if you wish to store UUIDs for primary keys; they’re a completely acceptable substitute for auto-incrementing integers:

>>> legolas = Elf(name='Legolas Greenleaf')
>>> legolas.id
''
>>> legolas.save()
>>> legolas.id
UUID('b1f12115-3337-4ec0-acb9-1bcf63e44477')

As of django-pgfields 1.4, it is also possible to use auto_add to generate a UUID using an algorithm other than uuid.uuid4. Instead of sending in True, send in any callable which takes no arguments and reliably returns a UUID.

For instance, the following field instantiation would cause a version 1 UUID to be used instead:

from django_pg import models
import uuid

id = models.UUID(auto_add=uuid.uuid1, primary_key=True)

coerce_to

By default, the to_python method on UUIDField will coerce values to UUID objects. Setting this option will use a different class constructor within to_python.

The general use-case for this is if you want to get strings instead of UUID objects. The following example would be the output in the case that you assigned coerce_to=str:

>>> legolas = Elf(name='Legolas Greenleaf')
>>> legolas.save()
>>> legolas.id
'b1f12115-3337-4ec0-acb9-1bcf63e44477'

Values¶

The UUID field will return values from the database as Python UUID objects.

If you choose to do so, you may assign a valid string to the field. The string will be converted to a uuid.UUID object upon assignment to the instance:

>>> legolas = Elf(name='Legolas Greenleaf')
>>> legolas.id = '01234567-abcd-abcd-abcd-0123456789ab'
>>> legolas.id
UUID('01234567-abcd-abcd-abcd-0123456789ab')
>>> type(legolas.id)
<class 'uuid.UUID'>

Lookups can be performed using either strings or Python UUID objects.

Differences from Model subclasses¶

A few things differ between models and composite fields:

• Composite fields inherit from django_pg.models.CompositeField rather than django.db.models.Model.

• Composite fields do not get an id field by default, and do not need one.

• Composite fields may not contain any subclass of django.db.models.RelatedField. This includes ForeignKey, OneToOneField, or ManyToManyField fields.

• Any constraints provided to composite fields will be ignored at the database level.

  • Exception: max_length sent to CharField. This is part of the type definition, and is still required.

• Most Meta options no longer have any meaning, and a new Meta option (db_type) is available to composite fields.

• Composite fields can’t do lookups based on a single key in the composite field. PostgreSQL has this ability, but it’s not yet implemented in django-pgfields.

Type Definition Example¶

With these differences in mind, creating a composite field is straightfoward and familiar:

from django_pg import models

class AuthorField(models.CompositeField):
    name = models.CharField(max_length=75)
    sex = models.CharField(max_length=6, choices=(
        ('male', 'Male'),
        ('female', 'Female'),
    ))
    birthdate = models.DateField()

Once the subclass is defined, it can be used within a model like any other field:

class Book(models.Model):
    title = models.CharField(max_length=50)
    author = AuthorField()
    date_published = models.DateField()

Meta Options¶

db_type

All types in PostgreSQL have a name to identify them, such as text or int. Your custom type must also have a name.

If you don’t provide one, django-pgfields will introspect it from the name of the class, by converting the class name to lower-case, and then stripping off "field" from the end if it’s present. So, in the example above, our AuthorField would create an author type in the schema.

You may choose to provide one by specifying db_type in the field’s inner Meta class:

class AuthorField(models.CompositeField):
    name = models.CharField(max_length=75)
    sex = models.CharField(max_length=6, choices=(
        ('male', 'Male'),
        ('female', 'Female'),
    ))
    birthdate = models.DateField()

    class Meta:
        db_type = 'ns_author'

Manual specification of the composite type’s name is recommended, if only so that they’re namespaced (to a degree). You don’t want your type name to conflict with some new type that PostgreSQL may add in the future, after all.

Tuples¶

In many simple circumstances, the quickest way to assign values is to use a tuple. PostgreSQL accepts its write values to composite fields in a tuple-like structure, with values provided in a specified order (the order of the fields) and keys omitted.

This is a legal way to assign an author to a book:

>>> hobbit = Book(title='The Hobbit', date_published=date(1937, 9, 21))
>>> hobbit.author = ('J.R.R. Tolkien', 'male', date(1892, 1, 3))
>>> hobbit.save()

Composite Instances¶

The above method works fine in simple cases, but isn’t great for more complex ones, especially since tuples are immutable. Fortunately, there’s a solution. Whenever a composite field is created, a “composite instance” class is created alongside of it, and is available under the instance_class property of the field.

This example is identical in function to the tuple example shown above:

>>> hobbit = Book(title='The Hobbit', date_published=date(1937, 9, 21))
>>> hobbit.author = AuthorField.instance_class(
    birthdate=date(1892, 1, 3),
    name='J.R.R. Tolkien',
    sex='male',
)
>>> hobbit.save()

The actual name of the instance class is derived from the name of the field, by dropping the name Field (if present) from the field name’s subclass. If the instance name does not conflict with the field name, it is automatically assigned to the same module in which the instance was created.

In the above example, assuming that AuthorField was defined in the library.models module, we’d be able to do this:

>>> from library.models import Book, Author
>>> hobbit = Book(title='The Hobbit', date_published=date(1937, 9, 21))
>>> hobbit.author = Author(
    birthdate=date(1892, 1, 3),
    name='J.R.R. Tolkien',
    sex='male',
)
>>> hobbit.save()

Settings¶

django-pgfields exposes this functionality through optional settings in your Django project.

DJANGOPG_IMPROVED_REPR

• default: False

Set this to True to enable the improved repr. Because providing an alternate __repr__ implementaiton is not the core function of django-pgfields, it is offered on an opt-in basis.

DJANGOPG_REPR_TEMPLATE

• default: 'single_line'

django-pgfields offers two built-in templates for printing model objects: a single-line template and a multi-line template. They are the same, except the model-line template adds line breaks and indentation for increased readability. However, this readability may come at the expense of ease of parsing logs.

• Set this to 'single_line' for the single-line template (default).
• Set this to 'multi_line' for the multi-line template.

The single-line template produces output like this:

>>> mymodel = MyModel.objects.create(spam='eggs', foo='bar')
>>> mymodel
<MyModel: { 'id': 1, 'spam': 'eggs', 'foo': 'bar' }>

The multi-line template produces output like this:

>>> mymodel = MyModel.objects.create(spam='eggs', foo='bar')
>>> mymodel
<MyModel: {
    'id': 1,
    'spam': 'eggs',
    'foo': 'bar'
}>

Additionally, you may define your own template by providing a two-tuple to this setting. Each tuple should be a string. The first string is the overall template, and the second string is the glue on which the individual fields are joined.

The template is populated using the % operator, and it is passed a dictionary with four elements:

• class_name: The name of the model class
• members: The model’s members, joined on the join glue
• tab: The appropriate tab depth
• untab: The appropriate tab depth for a depth one above; useful for closing off a structure

The glue is sent only the tab variable.