UUID Usage Scenarios: Complete Developer Guide

What are UUIDs?

UUID (Universally Unique Identifier) is a 128-bit identifier standardized by RFC 4122. UUIDs are designed to be globally unique across space and time, making them ideal for distributed systems where coordination between nodes is difficult or impossible.

Example UUID: 123e4567-e89b-12d3-a456-426614174000

UUIDs solve several problems in distributed systems:

No central authority needed for ID generation
Can be generated independently across multiple nodes
Extremely low probability of collisions
No coordination overhead between distributed systems

UUID Versions and Characteristics

Version 1: Time-based UUID

Generated based on timestamp and MAC address. Provides temporal ordering but reveals machine identity.

Pros: Time-ordered, sortable
Cons: Reveals MAC address, not cryptographically secure
Use case: Legacy systems, temporal ordering needed

Version 4: Random UUID

Generated using random or pseudo-random numbers. Most commonly used version.

Pros: No information leakage, simple to generate
Cons: Not sortable, requires good random source
Use case: General purpose, session IDs, API tokens

Version 5: SHA-1 based UUID

Generated from namespace and name using SHA-1 hash. Deterministic - same input produces same UUID.

Pros: Deterministic, namespace support
Cons: SHA-1 security concerns
Use case: Content addressing, deterministic IDs

Version 7: Time-ordered Random UUID

New draft standard (RFC 9562) combining timestamp with random bits. Time-ordered but no MAC address leakage.

Pros: Time-ordered, no information leakage
Cons: Newer standard, less library support
Use case: Modern applications needing temporal ordering

Common Use Cases

1. Distributed Database Primary Keys

When multiple database instances generate records independently without coordination.

-- PostgreSQL example with UUID primary key
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Insert without specifying ID (auto-generated)
INSERT INTO users (email) VALUES ('user@example.com');
                        

2. Session Management

Session IDs, authentication tokens, and API keys that need to be globally unique.

// Node.js example: Generate session ID
const { randomUUID } = require('crypto');

function createSession(userId) {
    const sessionId = randomUUID(); // Version 4 UUID
    const expiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000);
    
    return {
        sessionId,
        userId,
        expiresAt
    };
}
                        

3. File Storage and CDN

Unique filenames for uploaded content to prevent collisions and enable content addressing.

4. Event Sourcing and CQRS

Event IDs in event-sourced systems where events are generated across multiple services.

5. Microservices Communication

Correlation IDs for tracing requests across service boundaries.

Performance Considerations

Storage Size

UUIDs require 16 bytes (128 bits) compared to:

4 bytes for 32-bit integer
8 bytes for 64-bit integer (bigint)
~20 bytes for ULID (128-bit but more efficient encoding)

Index Performance

Random UUIDs (v4) cause index fragmentation in B-tree indexes. Consider:

Using UUID v1/v7 for temporal ordering
Using hash indexes instead of B-tree for random UUIDs
Adding created_at timestamp for range queries

-- PostgreSQL: Create hash index for UUID columns
CREATE INDEX idx_users_id_hash ON users USING hash(id);

-- Or use BRIN index for time-ordered UUIDs
CREATE INDEX idx_users_created_brin ON users USING brin(created_at);
                        

Generation Performance

Cryptographically secure random number generation can be expensive. Consider:

Using /dev/urandom or crypto.getRandomValues()
Pre-generating UUID batches for high-throughput systems
Using UUID v7 for better performance than v4

Implementation Guidelines

Choosing the Right Version

Requirement	Recommended Version	Notes
General purpose, no ordering needed	v4	Most common, simple to implement
Time ordering needed	v7	Modern alternative to v1
Deterministic IDs	v5	For content addressing
Legacy compatibility	v1	Avoid for new systems

Database Design Patterns

-- Pattern 1: UUID as primary key with auto-generation
CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    amount DECIMAL(10,2),
    status VARCHAR(50),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Pattern 2: Composite key with UUID
CREATE TABLE order_items (
    order_id UUID REFERENCES orders(id),
    item_id UUID DEFAULT gen_random_uuid(),
    product_id UUID REFERENCES products(id),
    quantity INTEGER,
    PRIMARY KEY (order_id, item_id)
);

-- Pattern 3: External reference with UUID
CREATE TABLE audit_log (
    id BIGSERIAL PRIMARY KEY,
    entity_type VARCHAR(50),
    entity_id UUID, -- References external UUID
    action VARCHAR(50),
    performed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
                        

Alternatives to UUID

ULID (Universally Unique Lexicographically Sortable Identifier)

128-bit identifier with timestamp (48 bits) and randomness (80 bits). More efficient than UUID for indexing.

Format: 01ARZ3NDEKTSV4RRFFQ69G5FAV
Pros: Lexicographically sortable, Crockford's Base32 encoding
Cons: Less standardized than UUID

Snowflake ID

Twitter's distributed ID generation algorithm using timestamp, worker ID, and sequence.

Format: 64-bit integer
Pros: Time-ordered, compact (8 bytes)
Cons: Requires coordination for worker IDs

CUID (Collision-resistant Unique Identifier)

Designed for horizontal scaling and web applications.

Format: cjld2cyuq0000t3rmniod1foy
Pros: URL-safe, collision-resistant
Cons: Variable length, less common

Tools and Resources

DailyTools.uk UUID Tool

Use our UUID Generator Tool to generate UUIDs in different versions, validate existing UUIDs, and learn about UUID formats.

External Resources

Conclusion

UUIDs are essential for building distributed systems that require globally unique identifiers without central coordination. Choose the appropriate UUID version based on your requirements:

Use UUID v4 for general-purpose random identifiers
Use UUID v7 for time-ordered identifiers in new systems
Use UUID v5 for deterministic content addressing
Consider ULID or Snowflake ID for specific use cases

Remember to consider performance implications, especially for database indexing, and always use cryptographically secure random number generators for UUID v4. For high-throughput systems, consider batching UUID generation or using time-ordered variants to improve database performance.