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?