From 094d630ae8d8e5e68817c313da0fd737898b216b Mon Sep 17 00:00:00 2001 From: Mads Jensen Date: Wed, 1 Jun 2016 23:43:59 +0200 Subject: [PATCH] Fixed #26610 -- Added CITextField to contrib.postgres. --- django/contrib/postgres/fields/__init__.py | 1 + django/contrib/postgres/fields/citext.py | 8 +++++ django/contrib/postgres/operations.py | 6 ++++ docs/ref/contrib/postgres/fields.txt | 20 +++++++++++++ docs/ref/contrib/postgres/operations.txt | 9 ++++++ docs/releases/1.11.txt | 5 ++++ tests/postgres_tests/fields.py | 6 ++-- .../migrations/0001_setup_extensions.py | 6 ++-- .../migrations/0002_create_test_models.py | 16 ++++++++-- tests/postgres_tests/models.py | 13 ++++++-- tests/postgres_tests/test_citext.py | 30 +++++++++++++++++++ 11 files changed, 110 insertions(+), 10 deletions(-) create mode 100644 django/contrib/postgres/fields/citext.py create mode 100644 tests/postgres_tests/test_citext.py diff --git a/django/contrib/postgres/fields/__init__.py b/django/contrib/postgres/fields/__init__.py index 9158f1e7cc..ef110279db 100644 --- a/django/contrib/postgres/fields/__init__.py +++ b/django/contrib/postgres/fields/__init__.py @@ -1,4 +1,5 @@ from .array import * # NOQA +from .citext import * # NOQA from .hstore import * # NOQA from .jsonb import * # NOQA from .ranges import * # NOQA diff --git a/django/contrib/postgres/fields/citext.py b/django/contrib/postgres/fields/citext.py new file mode 100644 index 0000000000..cab1f87957 --- /dev/null +++ b/django/contrib/postgres/fields/citext.py @@ -0,0 +1,8 @@ +from django.db.models import CharField + +__all__ = ['CITextField'] + + +class CITextField(CharField): + def db_type(self, connection): + return 'citext' diff --git a/django/contrib/postgres/operations.py b/django/contrib/postgres/operations.py index 6253011217..951c82cfca 100644 --- a/django/contrib/postgres/operations.py +++ b/django/contrib/postgres/operations.py @@ -23,6 +23,12 @@ class CreateExtension(Operation): return "Creates extension %s" % self.name +class CITextExtension(CreateExtension): + + def __init__(self): + self.name = 'citext' + + class HStoreExtension(CreateExtension): def __init__(self): diff --git a/docs/ref/contrib/postgres/fields.txt b/docs/ref/contrib/postgres/fields.txt index 3d22b13577..93f14fcca0 100644 --- a/docs/ref/contrib/postgres/fields.txt +++ b/docs/ref/contrib/postgres/fields.txt @@ -250,6 +250,26 @@ At present using :attr:`~django.db.models.Field.db_index` will create a A more useful index is a ``GIN`` index, which you should create using a :class:`~django.db.migrations.operations.RunSQL` operation. +``CITextField`` +=============== + +.. class:: CITextField(**options) + + .. versionadded:: 1.11 + + This field is a subclass of :class:`~django.db.models.CharField` backed by + the citext_ type, a case-insensitive character string type. Read about `the + performance considerations`_ prior to using this field. + + To use this field, setup the ``citext`` extension in PostgreSQL before the + first ``CreateModel`` migration operation using the + :class:`~django.contrib.postgres.operations.CITextExtension` operation. The + code to setup the extension is similar to the example for + :class:`~django.contrib.postgres.fields.HStoreField`. + + .. _citext: https://www.postgresql.org/docs/current/static/citext.html + .. _the performance considerations: https://www.postgresql.org/docs/current/static/citext.html#AEN169274 + ``HStoreField`` =============== diff --git a/docs/ref/contrib/postgres/operations.txt b/docs/ref/contrib/postgres/operations.txt index 656be8e976..4dcc85105f 100644 --- a/docs/ref/contrib/postgres/operations.txt +++ b/docs/ref/contrib/postgres/operations.txt @@ -27,6 +27,15 @@ the ``django.contrib.postgres.operations`` module. Install the ``btree_gin`` extension. +``CITextExtension`` +=================== + +.. class:: CITextExtension() + + .. versionadded:: 1.11 + + Installs the ``citext`` extension. + ``HStoreExtension`` =================== diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt index 307ed9ab52..4b17754cde 100644 --- a/docs/releases/1.11.txt +++ b/docs/releases/1.11.txt @@ -160,6 +160,11 @@ Minor features parameter to specify a custom class to encode data types not supported by the standard encoder. +* The new :class:`~django.contrib.postgres.fields.CITextField` and + :class:`~django.contrib.postgres.operations.CITextExtension` migration + operation allow using PostgreSQL's ``citext`` extension for case-insensitive + lookups. + :mod:`django.contrib.redirects` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/tests/postgres_tests/fields.py b/tests/postgres_tests/fields.py index c02bc2faf4..14283ccd61 100644 --- a/tests/postgres_tests/fields.py +++ b/tests/postgres_tests/fields.py @@ -6,8 +6,9 @@ from django.db import models try: from django.contrib.postgres.fields import ( - ArrayField, BigIntegerRangeField, DateRangeField, DateTimeRangeField, - FloatRangeField, HStoreField, IntegerRangeField, JSONField, + ArrayField, BigIntegerRangeField, CITextField, DateRangeField, + DateTimeRangeField, FloatRangeField, HStoreField, IntegerRangeField, + JSONField, ) from django.contrib.postgres.search import SearchVectorField except ImportError: @@ -29,6 +30,7 @@ except ImportError: ArrayField = DummyArrayField BigIntegerRangeField = models.Field + CITextField = models.Field DateRangeField = models.Field DateTimeRangeField = models.Field FloatRangeField = models.Field diff --git a/tests/postgres_tests/migrations/0001_setup_extensions.py b/tests/postgres_tests/migrations/0001_setup_extensions.py index a32319b911..41628030b7 100644 --- a/tests/postgres_tests/migrations/0001_setup_extensions.py +++ b/tests/postgres_tests/migrations/0001_setup_extensions.py @@ -5,8 +5,8 @@ from django.db import migrations try: from django.contrib.postgres.operations import ( - BtreeGinExtension, CreateExtension, HStoreExtension, TrigramExtension, - UnaccentExtension, + BtreeGinExtension, CITextExtension, CreateExtension, HStoreExtension, + TrigramExtension, UnaccentExtension, ) except ImportError: from django.test import mock @@ -15,6 +15,7 @@ except ImportError: HStoreExtension = mock.Mock() TrigramExtension = mock.Mock() UnaccentExtension = mock.Mock() + CITextExtension = mock.Mock() class Migration(migrations.Migration): @@ -27,4 +28,5 @@ class Migration(migrations.Migration): HStoreExtension(), TrigramExtension(), UnaccentExtension(), + CITextExtension(), ] diff --git a/tests/postgres_tests/migrations/0002_create_test_models.py b/tests/postgres_tests/migrations/0002_create_test_models.py index 161f883d3f..8f72183f5c 100644 --- a/tests/postgres_tests/migrations/0002_create_test_models.py +++ b/tests/postgres_tests/migrations/0002_create_test_models.py @@ -5,9 +5,9 @@ from django.core.serializers.json import DjangoJSONEncoder from django.db import migrations, models from ..fields import ( - ArrayField, BigIntegerRangeField, DateRangeField, DateTimeRangeField, - FloatRangeField, HStoreField, IntegerRangeField, JSONField, - SearchVectorField, + ArrayField, BigIntegerRangeField, CITextField, DateRangeField, + DateTimeRangeField, FloatRangeField, HStoreField, IntegerRangeField, + JSONField, SearchVectorField, ) from ..models import TagField @@ -138,6 +138,16 @@ class Migration(migrations.Migration): options=None, bases=None, ), + migrations.CreateModel( + name='CITextTestModel', + fields=[ + ('name', CITextField(primary_key=True, max_length=255)), + ], + options={ + 'required_db_vendor': 'postgresql', + }, + bases=None, + ), migrations.CreateModel( name='Line', fields=[ diff --git a/tests/postgres_tests/models.py b/tests/postgres_tests/models.py index 8913e60869..9687a874c0 100644 --- a/tests/postgres_tests/models.py +++ b/tests/postgres_tests/models.py @@ -2,9 +2,9 @@ from django.core.serializers.json import DjangoJSONEncoder from django.db import models from .fields import ( - ArrayField, BigIntegerRangeField, DateRangeField, DateTimeRangeField, - FloatRangeField, HStoreField, IntegerRangeField, JSONField, - SearchVectorField, + ArrayField, BigIntegerRangeField, CITextField, DateRangeField, + DateTimeRangeField, FloatRangeField, HStoreField, IntegerRangeField, + JSONField, SearchVectorField, ) @@ -101,6 +101,13 @@ class Character(models.Model): return self.name +class CITextTestModel(PostgreSQLModel): + name = CITextField(primary_key=True, max_length=255) + + def __str__(self): + return self.name + + class Line(PostgreSQLModel): scene = models.ForeignKey('Scene', models.CASCADE) character = models.ForeignKey('Character', models.CASCADE) diff --git a/tests/postgres_tests/test_citext.py b/tests/postgres_tests/test_citext.py new file mode 100644 index 0000000000..7f86f6a205 --- /dev/null +++ b/tests/postgres_tests/test_citext.py @@ -0,0 +1,30 @@ +""" +The citext PostgreSQL extension supports indexing of case-insensitive text +strings and thus eliminates the need for operations such as iexact and other +modifiers to enforce use of an index. +""" +from django.db import IntegrityError + +from . import PostgreSQLTestCase +from .models import CITextTestModel + + +class CITextTestCase(PostgreSQLTestCase): + + @classmethod + def setUpTestData(cls): + CITextTestModel.objects.create(name='JoHn') + + def test_equal_lowercase(self): + """ + citext removes the need for iexact as the index is case-insensitive. + """ + self.assertEqual(CITextTestModel.objects.filter(name='john').count(), 1) + + def test_fail_case(self): + """ + Creating an entry for a citext-field which clashes with an existing + value isn't allowed. + """ + with self.assertRaises(IntegrityError): + CITextTestModel.objects.create(name='John')