From 5ae090613864cb8e0b22efaeb9ed1c7b59de7be5 Mon Sep 17 00:00:00 2001 From: Nathan Bogale Date: Tue, 10 Dec 2024 19:30:37 +0300 Subject: [PATCH 1/3] doc(docs): Adds ADR on the migration to UUID7 --- .../0009-uuid7-vs-ulid.md | 80 +++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 docs/src/architecture/09_architecture_decisions/0009-uuid7-vs-ulid.md diff --git a/docs/src/architecture/09_architecture_decisions/0009-uuid7-vs-ulid.md b/docs/src/architecture/09_architecture_decisions/0009-uuid7-vs-ulid.md new file mode 100644 index 00000000000..db9979e03a9 --- /dev/null +++ b/docs/src/architecture/09_architecture_decisions/0009-uuid7-vs-ulid.md @@ -0,0 +1,80 @@ +--- + title: 0009 UUIDv7 vs ULID + adr: + author: Assistant + created: 17-Oct-2024 + status: proposed + tags: + - uuid + - identifiers +--- + +## Context + +The system needs globally unique identifiers for various entities and resources. Currently, we use ULIDs (Universally Unique Lexicographically Sortable Identifiers) in some parts of the system. With the recent standardization of UUIDv7 through [RFC 9562], we need to evaluate our identifier strategy. + +## Assumptions + +* We need time-ordered, globally unique identifiers for certain system components +* We need non-time-ordered unique identifiers for type identification +* Our systems must interact with various external systems and databases + +## Decision + +We will: + +* Use UUIDv7 for all time-bound unique identifiers (replacing ULID usage) +* Use UUIDv4 for type-specific identifiers where time ordering is not required +* Phase out ULID usage in favor of UUIDv7 + +### Rationale + +* UUIDv7 provides similar benefits to ULID: + * Time-ordered + * Globally unique + * Contains timestamp information +* UUIDv7 has several advantages over ULID: + * Standardized through RFC 9562 + * Wider system compatibility (native UUID support) + * No special encoding requirements + * Clear disambiguation from UUIDv4 (allowing two distinct identifier spaces) + * Eliminates need for custom ULID code + * Better database indexing support +* Standard UUID implementations are widely available across programming languages and platforms + +### Implementation Guidelines + +* New features should exclusively use: + * UUIDv7 for time-ordered identifiers + * UUIDv4 for non-time-ordered type identifiers +* Existing ULID implementations should be migrated to UUIDv7 during regular maintenance cycles +* Database schemas should use UUID types rather than string/custom types +* API contracts should specify UUID format requirements in their documentation + +## Risks + +* Migration from existing ULID implementations requires careful planning +* Some existing data may need conversion +* Team members need to understand when to use UUIDv4 vs UUIDv7 + +## Consequences + +### Positive + +* Improved system interoperability +* Reduced custom code maintenance +* Better alignment with industry standards +* Simplified database operations +* Two distinct identifier spaces (v4 and v7) for different use cases + +### Negative + +* Migration effort required for existing ULID implementations +* Team training needed for proper UUID version selection + +## More Information + +* [RFC 9562 - UUIDv7 Specification](https://datatracker.ietf.org/doc/rfc9562/) +* [ULID Specification](https://github.com/ulid/spec) + +[RFC 9562]: https://datatracker.ietf.org/doc/rfc9562/ \ No newline at end of file From bfbde20e63c73715b3600134febe083a85515ac6 Mon Sep 17 00:00:00 2001 From: Nathan Bogale Date: Wed, 11 Dec 2024 08:21:43 +0300 Subject: [PATCH 2/3] fix: Markdown lint check failure --- .../09_architecture_decisions/0009-uuid7-vs-ulid.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/src/architecture/09_architecture_decisions/0009-uuid7-vs-ulid.md b/docs/src/architecture/09_architecture_decisions/0009-uuid7-vs-ulid.md index db9979e03a9..66a08e4b2e7 100644 --- a/docs/src/architecture/09_architecture_decisions/0009-uuid7-vs-ulid.md +++ b/docs/src/architecture/09_architecture_decisions/0009-uuid7-vs-ulid.md @@ -11,7 +11,9 @@ ## Context -The system needs globally unique identifiers for various entities and resources. Currently, we use ULIDs (Universally Unique Lexicographically Sortable Identifiers) in some parts of the system. With the recent standardization of UUIDv7 through [RFC 9562], we need to evaluate our identifier strategy. +The system needs globally unique identifiers for various entities and resources. +Currently, we use ULIDs (Universally Unique Lexicographically Sortable Identifiers) in some parts of the system. +With the recent standardization of UUIDv7 through [RFC 9562], we need to evaluate our identifier strategy. ## Assumptions From 7a730c48338a5719ec4737f0cd3d8c5e51d8edcb Mon Sep 17 00:00:00 2001 From: Nathan Bogale Date: Wed, 11 Dec 2024 08:34:22 +0300 Subject: [PATCH 3/3] fix: Markdown check failure over new line --- .../09_architecture_decisions/0009-uuid7-vs-ulid.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/architecture/09_architecture_decisions/0009-uuid7-vs-ulid.md b/docs/src/architecture/09_architecture_decisions/0009-uuid7-vs-ulid.md index 66a08e4b2e7..60c537b3762 100644 --- a/docs/src/architecture/09_architecture_decisions/0009-uuid7-vs-ulid.md +++ b/docs/src/architecture/09_architecture_decisions/0009-uuid7-vs-ulid.md @@ -79,4 +79,4 @@ We will: * [RFC 9562 - UUIDv7 Specification](https://datatracker.ietf.org/doc/rfc9562/) * [ULID Specification](https://github.com/ulid/spec) -[RFC 9562]: https://datatracker.ietf.org/doc/rfc9562/ \ No newline at end of file +[RFC 9562]: https://datatracker.ietf.org/doc/rfc9562/