Document that UniqueConstraint may create unique indexes unassociated with actual database constraints

[Clifford Gama]

The ​docs for UniqueConstraint:

Creates a unique constraint in the database.

This is not always true. Depending on the options used, UniqueConstraint may instead create a unique index via CREATE UNIQUE INDEX rather than a database constraint via ALTER TABLE ... ADD CONSTRAINT ... UNIQUE (​source).

For example, adding the following constraints to a model with a name field:

constraints = [
    models.UniqueConstraint(models.F("name"), name="unique_name_exp"),
    models.UniqueConstraint(fields=["name"], name="unique_name_field"),
]

produces the following SQL on PostgreSQL:

BEGIN;
-- Create constraint unique_name_exp on model mymodel
CREATE UNIQUE INDEX "unique_name_exp" ON "myapp_mymodel" ("name");
-- Create constraint unique_name_field on model mymodel
ALTER TABLE "myapp_mymodel" ADD CONSTRAINT "unique_name_field" UNIQUE ("name");
COMMIT;

See also ​Allow unique indexes (via UniqueConstraint) to be created/dropped CONCURRENTLY on PostgreSQL where this came up as something of an issue.

[Jacob Walls]

I agree we can improve this a bit. Maybe "create a uniqueness rule"?

[Clifford Gama]

Replying to Jacob Walls:

Thanks Jacob for the triage. I think we should opt for something more specific rather than leave folks guessing. What do you think of "Creates a unique constraint or a unique index in the database, depending on the options used" and maybe calling out which options create what in an admonition?

[Jacob Walls <jacobtylerwalls@…>]

In 1c550a8:

Fixed #37069 -- Clarified that UniqueConstraint may create a unique index.

Thanks Jacob for the triage and James for the review.

[Jacob Walls <jacobtylerwalls@…>]

In 370a6e2d:

[6.1.x] Fixed #37069 -- Clarified that UniqueConstraint may create a unique index.

Thanks Jacob for the triage and James for the review.

Backport of 1c550a8151c84d7e221ccc42821aae25f43f0452 from main.

[Jacob Walls <jacobtylerwalls@…>]

In e85df4d2:

[6.0.x] Fixed #37069 -- Clarified that UniqueConstraint may create a unique index.

Thanks Jacob for the triage and James for the review.

Backport of 1c550a8151c84d7e221ccc42821aae25f43f0452 from main.