GUIDs

Granit.Guids provides IGuidGenerator with three strategies for generating identifiers optimized for database performance. The default — UUIDv7 — uses Guid.CreateVersion7() from .NET 9: a standard time-ordered format that appends rows to the last index page and eliminates B-tree page splits on PostgreSQL, MySQL, and SQL Server 2019+.

Package

Package	Role	Depends on
`Granit.Guids`	`IGuidGenerator`, UUIDv7 / sequential / random strategies	`Granit.Timing`

Setup

[DependsOn(typeof(GranitGuidsModule))]
public class AppModule : GranitModule { }

Usage

public class PatientService(IGuidGenerator guidGenerator, AppDbContext db)
{
    public Patient Create(string firstName, string lastName)
    {
        return new Patient
        {
            Id = guidGenerator.Create(), // UUIDv7 by default
            FirstName = firstName,
            LastName = lastName,
        };
    }
}

Strategies

Three strategies are available via GuidStrategy:

Strategy	Implementation	When to use
`UuidV7` (default)	`Guid.CreateVersion7(DateTimeOffset)`	PostgreSQL, MySQL, SQL Server 2019+, any modern DB
`Sequential`	`SequentialGuidGenerator` (custom byte layout)	Oracle, pre-2019 SQL Server
`Random`	`Guid.NewGuid()`	Public-facing IDs where enumeration must be prevented

UUIDv7 layout (RFC 9562)

block-beta
    columns 16
    block:v7["UUIDv7 (default)"]
        columns 16
        t1["T"] t2["T"] t3["T"] t4["T"] t5["T"] t6["T"]
        v["ver"] r1["R"] r2["R"] r3["R"] r4["R"] r5["R"] r6["R"] r7["R"] r8["R"] r9["R"]
    end

    style t1 fill:#4a9eff
    style t2 fill:#4a9eff
    style t3 fill:#4a9eff
    style t4 fill:#4a9eff
    style t5 fill:#4a9eff
    style t6 fill:#4a9eff
    style v fill:#f0a500

T = 48-bit Unix timestamp (milliseconds), ver = version nibble (7), R = random.

Legacy sequential types (`Strategy = Sequential`)

Used when Strategy = GuidStrategy.Sequential. The byte layout is tuned per database engine:

`SequentialGuidType`	Timestamp position	Database
`SequentialAsString`	Front (sorted by string representation)	PostgreSQL, MySQL
`SequentialAsBinary`	Front (sorted by byte array)	Oracle
`SequentialAtEnd`	End (Data4 block)	SQL Server pre-2019

Configuration

// Default — UUIDv7, recommended for modern databases
services.AddGranitGuids();

// SQL Server 2019+ — still use UUIDv7
services.AddGranitGuids();

// Oracle — legacy sequential
services.AddGranitGuids(options =>
{
    options.Strategy = GuidStrategy.Sequential;
    options.DefaultSequentialGuidType = SequentialGuidType.SequentialAsBinary;
});

// Pre-2019 SQL Server — legacy sequential
services.AddGranitGuids(options =>
{
    options.Strategy = GuidStrategy.Sequential;
    options.DefaultSequentialGuidType = SequentialGuidType.SequentialAtEnd;
});

// Public-facing IDs — random
services.AddGranitGuids(options =>
{
    options.Strategy = GuidStrategy.Random;
});

Property	Type	Default	Description
`Strategy`	`GuidStrategy`	`UuidV7`	Generator strategy
`DefaultSequentialGuidType`	`SequentialGuidType?`	`SequentialAsString`	Byte layout for `Sequential` strategy

IGuidGenerator

public interface IGuidGenerator
{
    Guid Create();
}

All three implementations are singletons. TryAddSingleton is used — register a custom IGuidGenerator before calling AddGranitGuids() to override the default.

SimpleGuidGenerator.Instance is also available as a static instance for non-DI contexts (domain events, value objects).

Public API summary

Category	Key types	Package
Module	`GranitGuidsModule`	—
Strategies	`GuidStrategy`	`Granit.Guids`
Generators	`IGuidGenerator`, `UuidV7GuidGenerator`, `SequentialGuidGenerator`, `SimpleGuidGenerator`	`Granit.Guids`
Options	`GuidGeneratorOptions`, `SequentialGuidType`	`Granit.Guids`
Extensions	`AddGranitGuids()`	`Granit.Guids`