databasetestinguuid

How to Generate Bulk UUIDs for Database Seeding

Angtool Team · June 9, 2026

Universally Unique Identifiers (UUIDs) are 128-bit numbers used to identify information in computer systems. Version 4 UUIDs are generated using random numbers and are practically guaranteed to be unique — the probability of a collision is so low that it is effectively zero for practical purposes. This makes them ideal for database primary keys, distributed system identifiers, and session tokens.

Understanding UUID Versions

There are several versions of UUIDs, each with a different generation strategy:

UUID v1: Based on the current timestamp and the MAC address of the generating machine. These are time-sortable but can leak the machine’s hardware identity.

UUID v4: Generated from random or pseudo-random numbers. These are the most common and offer the best privacy since they reveal nothing about the source.

UUID v5: Generated from a namespace and a name using SHA-1 hashing. These are deterministic — the same inputs always produce the same UUID.

UUID v7 (proposed): A new time-ordered UUID format that combines the benefits of v1 (sortability) and v4 (randomness). It encodes a Unix timestamp in the most significant bits, making UUIDs sortable by creation time.

For most applications, UUID v4 is the recommended choice because it balances uniqueness, privacy, and simplicity.

Why Do You Need Bulk UUIDs?

When developing a new feature, you often need to seed your database with dummy data. Manually generating UUIDs for foreign keys or primary keys one by one is tedious and error-prone. Common scenarios include:

Database Seeding: You need 500 unique user IDs for a load testing script. Each user needs their own UUID as a primary key, and related tables (orders, profiles, settings) need matching foreign keys.

API Testing: Your API endpoints return UUIDs for resources. Testing pagination, filtering, and sorting requires a dataset with dozens of unique identifiers.

Migration Scripts: Moving data between systems often requires generating new UUIDs for records that previously used auto-increment IDs.

Demo Data: Creating realistic demo environments for clients or stakeholders requires large sets of unique identifiers that look authentic.

The Math Behind UUID Uniqueness

UUID v4 uses 122 bits of randomness (the remaining 6 bits are reserved for version and variant information). This means there are 2^122 possible UUIDs — approximately 5.3 × 10^36. To put that number in perspective:

You could generate 1 billion UUIDs per second for 100 years and still have only a 50% chance of a single collision.
There are more possible UUIDs than there are atoms in your body (approximately 7 × 10^27).
If every person on Earth generated 1 million UUIDs per second, it would take billions of years before a collision became likely.

This mathematical certainty is why UUIDs are trusted for distributed systems where centralized ID generation is impossible.

Cryptographically Secure UUID Generation

It is important that UUIDs are generated using a cryptographically secure pseudo-random number generator (CSPRNG), not just Math.random(). The difference is critical:

Math.random(): Uses a pseudo-random number generator (PRNG) seeded with the current time. It is fast but predictable — given enough outputs, an attacker can reconstruct the internal state and predict future UUIDs.
Crypto.getRandomValues(): Uses the operating system’s CSPRNG, which gathers entropy from physical hardware events (keystroke timing, mouse movement, thermal noise, etc.). It is slower but truly unpredictable.

Modern browsers provide crypto.getRandomValues() for this exact purpose. All UUIDs generated using this API are cryptographically secure.