Doctrine and composite unique keys

Doctrine and composite unique keys

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Doctrine and Composite Unique Keys

Enforcing uniqueness on a single column is straightforward in Doctrine: you add @UniqueConstraint(columns={"field"}) or configure it in your migration file. However, when you need to guarantee that a combination of columns—like videoDimension and videoBitrate in your example—is unique across the entire table, the syntax requires a specific adjustment.

To tell Doctrine that these two fields form a composite unique key, you must explicitly list both column names within the constraint definition. In modern Doctrine ORM (version 2.x), this is typically handled via the UniqueConstraint annotation or attribute. You would annotate your entity class as follows:

use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity
 * @ORM\Table(name="videos")
 */
class Video
{
    /**
     * @var string $id
     *
     * @ORM\Id
     * @ORM\GeneratedValue
     * @ORM\Column(type="integer")
     */
    private $id;

    /**
     * @var string $videoDimension
     *
     * @Column(name="video_dimension", type="string", nullable=false)
     */
    private $videoDimension;

    /**
     * @var string $videoBitrate
     *
     * @Column(name="video_bitrate", type="string", nullable=false)
     */
    private $videoBitrate;

    /**
     * This tells Doctrine to create a unique index on both columns together.
     *
     * @ORM\UniqueConstraint(columns={"video_dimension", "video_bitrate"})
     */
}

The critical detail here is the columns array inside the @UniqueConstraint. If you omit this array and simply use @ORM\UniqueConstraint(), Doctrine will treat it as a constraint on a single column, which might default to an internal identifier or throw an error because no specific column was targeted. By listing both video_dimension and video_bitrate, you are instructing the database engine to reject any record where that exact pair of values already exists, regardless of what other data is present in the row.

When you run your migrations using Doctrine Migrations, this annotation translates into a specific SQL command executed against your database. For PostgreSQL, the resulting DDL looks like this:

ALTER TABLE "videos" ADD CONSTRAINT "unique_video_dimension_bitrate" UNIQUE ("video_dimension", "video_bitrate");

In MySQL or MariaDB, it similarly creates an index that covers both columns. It is important to understand what happens at the database level during an insert or update operation. If you attempt to save a Video object where $videoDimension is '1080p' and $videoBitrate is '5000k', but a row with that exact combination already exists, the database will throw a violation exception (e.g., SQLSTATE[23000]: Integrity constraint violation). Doctrine will catch this as an entity validation error if configured to do so, or you may need to handle the Doctrine\DBAL\Exception\UniqueConstraintViolationException in your application logic.

There is a subtle but important trade-off regarding nullability. In your source material, both fields are marked as nullable=false. This means the database constraint applies only when both columns contain actual values. If one field were nullable, composite unique constraints behave differently depending on the database system; some databases allow multiple rows with all-null values in a unique index, while others treat them as distinct. Since your schema enforces non-nullability, you avoid this ambiguity entirely, ensuring strict uniqueness for any valid combination of dimension and bitrate.

If you are working within the Laravel ecosystem, managing these constraints often feels seamless because Doctrine handles the metadata mapping automatically. However, if you prefer a more explicit approach or need to fine-tune migration behavior without relying on annotations, you can define the constraint directly in your Schema class for migrations:

$table->unique(['video_dimension', 'video_bitrate'], 'unique_video_specs');

This manual definition gives you full control over the index name and ensures the constraint is applied exactly as intended, independent of any ORM annotations. Whether you choose the annotation approach or the migration-only approach, the underlying principle remains the same: explicitly defining the columns involved in the constraint is mandatory for composite keys.

Our network