Fixed #26610 -- Added CITextField to contrib.postgres.

11 files changed, 110 insertions, 10 deletions

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
 
@@ -139,6 +139,16 @@ class Migration(migrations.Migration):
             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=[
                 ('id', models.AutoField(verbose_name='ID', serialize=False, auto_created=True, primary_key=True)),
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')