Symfony UID Component: Using UUID and ULID in Practice

1. Why the choice of ID strategy is not a mere side note

A table's primary key is far more than a technical detail: it determines the physical ordering of rows in the clustered index (with InnoDB, the primary key literally is the clustered index), affects how efficiently rows replicate, and helps decide whether an ID exposed in a public URL leaks predictable information, such as the approximate order or count of records.

Classic auto-increment IDs are ideal from the database's point of view, since they are strictly ascending and inserts always happen at the end of the index, but they work poorly in distributed systems where multiple services need to generate IDs independently without coordinating through a central counter. The Symfony UID component resolves that tension by offering both classic UUIDs and the more modern ULID format under one consistent API.

2. UUID basics: versions and their characteristics

A UUID is a 128-bit value, usually represented as a 36 character string with four hyphens, standardized in RFC 9562 (the successor to RFC 4122). The Symfony UID component supports several versions through the class Symfony\Component\Uid\Uuid, where Uuid::v4() generates a fully random UUID and Uuid::v7() produces a newer, time-based variant that embeds a millisecond timestamp in its leading bits.

UUIDv4 remains the most widely used variant in practice, precisely because it reveals nothing about its creation time, which is genuinely desirable for security tokens. For database primary keys with a high insert rate, however, that exact property becomes a drawback, one that UUIDv7 and ULID deliberately avoid, as the following sections show.

3. ULID: the sortable, time-based alternative

ULID stands for Universally Unique Lexicographically Sortable Identifier and consists of 26 characters in the Crockford Base32 alphabet, which deliberately excludes easily confused characters like I, L, O, and U. The first 48 bits encode a millisecond timestamp, the remaining 80 bits are random, so two ULIDs generated at different points in time automatically sort in the correct chronological order once compared as strings.

In Symfony, the class Symfony\Component\Uid\Ulid represents this format, and generation could not be simpler: creating a new object with new Ulid() automatically produces a fresh, chronologically correct ULID. The example below shows a Doctrine entity that consistently uses ULID as its primary key, including the matching column definition.

<?php

declare(strict_types=1);

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Uid\Ulid;

/**
 * Represents a product with a ULID-based primary key, avoiding index
 * fragmentation under a high insert rate.
 */
#[ORM\Entity]
#[ORM\Table(name: 'product')]
class Product
{
    #[ORM\Id]
    #[ORM\Column(type: 'ulid', unique: true)]
    private Ulid $id;

    #[ORM\Column(length: 255)]
    private string $name;

    public function __construct(string $name)
    {
        $this->id = new Ulid();
        $this->name = $name;
    }

    public function getId(): Ulid
    {
        return $this->id;
    }
}

4. Why ULID fragments database indexes far less than UUIDv4

A B-tree index, as used by InnoDB or PostgreSQL for primary keys, is optimized for sequential inserts: with auto-increment IDs, every new row lands at the end of the tree without requiring existing pages to be reorganized. With a fully random UUIDv4, on the other hand, every new row lands at a completely random position in the tree, causing constant page splits, worse cache locality, and, over time, noticeably growing index fragmentation.

ULID and UUIDv7 solve this problem because their timestamp prefix causes newly generated IDs to land approximately at the end of the sorted index, much like an auto-increment ID would. In benchmarks against very large tables, this shows up directly as measurably better insert performance and a smaller index size compared to an equivalent table keyed with UUIDv4.

5. Doctrine integration: using UuidType and UlidType correctly

The Symfony Doctrine bridge automatically registers two custom Doctrine types as soon as the symfony/uid package is installed alongside the bridge: uuid for UUID objects and ulid for ULID objects. Both can be specified directly as the column type in the #[ORM\Column] attribute, exactly as shown in the example above with type: 'ulid', with no manual conversion required between the PHP object and the database format.

Internally, Doctrine usually stores these types as BINARY(16) rather than a readable CHAR(36) string, which saves storage space and further improves index performance, since 16 bytes are considerably more compact than a 36 character string. The relevant Doctrine type handles the conversion between the binary database representation and the PHP object entirely transparently in the background.

6. Generating and comparing both formats in code

Generation is deliberately kept uniform across both classes: Uuid::v4() returns a random UUID, Uuid::v7() a time-based UUID, and new Ulid() or, statically, Ulid::generate() returns a fresh ULID. Both classes inherit from the shared abstract base class AbstractUid and therefore expose identical comparison and conversion methods such as equals(), toBinary(), toBase58(), and toRfc4122().

This shared base substantially simplifies generic code meant to work with arbitrary IDs: a function that validates an ID string or converts it to a binary format can be written independently of whether it ultimately receives a UUID or a ULID, as long as it sticks to the common interface exposed by AbstractUid.

7. When UUID and when ULID is the better choice

UUIDv4 remains the right choice wherever predictability is explicitly undesirable, for instance security tokens, password reset links, or API keys, where a timestamp embedded in the value would constitute an unwanted information leak that could reveal roughly when a token was created.

ULID, or alternatively UUIDv7, is almost always the better choice for database primary keys with a high insert rate, for example orders, event logs, chat messages, or any other entity that gets created continuously in large numbers, where the built in chronological sortability even serves as a welcome bonus for queries ordered by creation time.

8. URL and API aesthetics: why ULID is also more practical day to day

Beyond pure database performance, ULID also brings concrete practical benefits in daily use: at 26 characters instead of 36 and without separating hyphens, a ULID is more compact in URLs, log lines, or support tickets, and therefore easier to copy and paste without accidentally losing a character.

The Crockford Base32 alphabet also deliberately avoids characters that are easily confused when read aloud over the phone or typed manually, such as the digit zero and the letter O. In practice, a URL like /api/orders/01ARZ3NDEKTSV4RRFFQ69G5FAV reads not only more compactly but is also more error resistant than the equivalent with a classic UUID.

9. Migration path and a practical recommendation for new projects

Retrofitting an existing UUIDv4 column to ULID is not a trivial undertaking, since the underlying format changes and every referencing foreign key would need to migrate alongside it. That makes it worth deciding deliberately and early for new tables, rather than revisiting the decision later under time pressure.

As a practical rule of thumb: for new tables with an expected high insert rate, ULID should be the default, while UUIDv4 gets used deliberately where unpredictability is a genuine security property. The unified API of the Symfony UID component makes this deliberate, per-entity decision considerably easier than any hand rolled UUID solution ever was.

10. Summary

11. FAQ: UUID vs ULID with the Symfony UID Component: The Key Points at a Glance