UUID (Universally Unique Identifier) data type implements the UUIDv4 format from RFC 4122. It stores a 128-bit value that is “unique across both space and time, with respect to the space of all UUIDs” as specified by the RFC.
To auto-generate UUIDs:
- Use the
gen_random_uuid()function as the default value of theUUIDdata type. - Use the
uuid_v4()function as the default value of theBYTESdata type.
gen_random_uuid() and uuid_v4() built-in functions. Other types of UUID are largely untested with CockroachDB and will require performance testing to avoid hotspots.
Syntax
You can expressUUID values using the following formats:
CockroachDB displays all
UUID values in the standard RFC4122 format, and implements the UUIDv4 (random) version from the RFC.
Size
AUUID value is 128 bits in width, but the total storage size is likely to be larger due to CockroachDB metadata.
Examples
Create a table with manually-entered UUID values
For performance reasons, if you are going to use UUIDs, Cockroach Labs strongly recommends using UUIDv4 as defined by RFC 4122. This is the format generated by the gen_random_uuid() and uuid_v4() built-in functions. Other types of UUID are largely untested with CockroachDB and will require performance testing to avoid hotspots.
Create a table with UUID in standard RFC4122-specified format
Create a table with UUID in BYTE format
Create a table with UUID used as URN
Express UUIDs in alternate formats
Create a table with auto-generated unique row IDs
To auto-generate unique row identifiers, you can use the following functions:- Use
gen_random_uuid(): Generates a UUIDv4 withUUIDdata type. - Use
uuid_v4(): Generates a UUIDv4 withBYTESdata type. - Use
unique_rowid(): Generates a globally uniqueINTdata type
gen_random_uuid() and uuid_v4() built-in functions. Other types of UUID are largely untested with CockroachDB and will require performance testing to avoid hotspots.
Use gen_random_uuid()
To use the UUID column with the gen_random_uuid() function as the default value:
gen_random_uuid() due to the near-zero probability of UUID collisions. UUID uniqueness checks can be enabled by setting the sql.optimizer.uniqueness_checks_for_gen_random_uuid.enabled cluster setting to true.
Use uuid_v4()
Alternatively, you can use the BYTES column with the uuid_v4() function as the default value:
Use unique_rowid()
If it is important for generated IDs to be stored in the same key-value range, you can use an integer type with the unique_rowid() function as the default value, either explicitly or via the SERIAL pseudo-type:
unique_rowid() function generates a default value from the timestamp and ID of the node executing the insert. Such time-ordered values are likely to be globally unique except in cases where a very large number of IDs (100,000+) are generated per node per second. Also, there can be gaps and the order is not completely guaranteed.
In multi-region deployments with REGIONAL BY ROW tables, uniqueness checks can add latency due to cross-partition validation. You can improve performance by setting the skip_unique_checks index storage parameter to true, but this is only recommended if the application can guarantee uniqueness. For more information, refer to skip_unique_checks.
To understand the differences between the UUID and unique_rowid() options, see the SQL FAQs. For further background on UUIDs, see What is a UUID, and Why Should You Care?.
Supported casting and conversion
UUID values can be cast to the following data type:

