KSUID Generator

Introduction

KSUID (K-Sortable Unique IDentifier) is a unique identifier format that offers several advantages over traditional UUID (Universally Unique Identifier) and other identifier systems. This tool allows you to generate KSUIDs quickly and easily.

What is a KSUID?

A KSUID is a 20-byte sortable identifier that consists of:

1. A 32-bit timestamp (4 bytes)
2. 16 bytes of randomness

When represented as a string, a KSUID is encoded in base62 and is 27 characters long.

Structure of a KSUID

The structure of a KSUID can be broken down as follows:

1. Timestamp (4 bytes): This represents the number of seconds since the Unix epoch (January 1, 1970, at 00:00 UTC). The timestamp allows KSUIDs to be roughly sortable by generation time.

2. Random Component (16 bytes): This is a cryptographically secure random number that ensures uniqueness even when multiple KSUIDs are generated in the same second.

3. Base62 Encoding: The combined 20 bytes (timestamp + random) are then encoded using base62 (A-Z, a-z, 0-9) to produce the final 27-character string.

KSUID Formula

A KSUID can be represented mathematically as:

$KSUID = Base62(T || R)$

Where:

• $T$ is the 32-bit timestamp
• $R$ is the 128-bit random component
• $||$ denotes concatenation

The timestamp $T$ is calculated as:

T = \text{floor}(\text{current_time} - \text{KSUID_epoch})

Where KSUID_epoch is 1400000000 (2014-05-13T16:53:20Z).

KSUID Structure Diagram

Use Cases for KSUIDs

KSUIDs are particularly useful in the following scenarios:

1. Distributed Systems: When you need unique identifiers across multiple servers or services without coordination.

2. Time-Sortable Data: When you want to sort data by creation time without storing a separate timestamp.

3. Database Keys: As primary keys in databases, especially in distributed databases where auto-incrementing integers are not suitable.

4. URL-Safe Identifiers: For creating short, unique, URL-safe identifiers for resources in web applications.

5. Log Correlation: To correlate log entries across different services in a microservices architecture.

Advantages of KSUIDs

KSUIDs offer several advantages over other identifier systems:

1. Sortability: Unlike UUIDs, KSUIDs can be sorted chronologically, which is useful for database indexing and log analysis.

2. No Coordination Required: Unlike auto-incrementing IDs, KSUIDs can be generated independently by different servers without risking collisions.

3. Compact Representation: At 27 characters, KSUIDs are more compact than UUIDs when represented as strings.

4. Timestamp Embedded: The embedded timestamp allows for time-based sorting and filtering without needing a separate timestamp field.

5. URL-Safe: The base62 encoding makes KSUIDs safe for use in URLs without any additional encoding.

6. Reduced Collision Probability: The 16-byte random component makes collisions extremely unlikely, even at high generation rates.

How to Use This Generator

1. Enter any additional parameters if required (e.g., custom timestamp).
2. Click the "Generate KSUID" button to create a new KSUID.
3. The generated KSUID will be displayed in the output field.
4. You can generate multiple KSUIDs by repeating steps 1-3.
5. Use the "Copy" button next to each KSUID to copy it to your clipboard.
6. Optionally, use the "Export" feature to download a list of generated KSUIDs.

Remember that each KSUID is unique and should be used only once. Generate a new KSUID each time you need a unique identifier.

Code Examples

Here are examples of generating KSUIDs in various programming languages:

1## Python
2import ksuid
3
4new_id = ksuid.ksuid()
5print(f"Generated KSUID: {new_id}")
6

1// JavaScript
2const { ksuid } = require('ksuid')
3
4const newId = ksuid()
5console.log(`Generated KSUID: ${newId}`)
6

1// Java
2import com.github.ksuid.KsuidGenerator;
3
4public class KsuidExample {
5    public static void main(String[] args) {
6        String newId = KsuidGenerator.generate();
7        System.out.println("Generated KSUID: " + newId);
8    }
9}
10

1// C++
2#include <iostream>
3#include <ksuid/ksuid.hpp>
4
5int main() {
6    ksuid::Ksuid newId = ksuid::Ksuid::generate();
7    std::cout << "Generated KSUID: " << newId.string() << std::endl;
8    return 0;
9}
10

1## Ruby
2require 'ksuid'
3
4new_id = KSUID.new
5puts "Generated KSUID: #{new_id}"
6

1// PHP
2<?php
3require_once 'vendor/autoload.php';
4
5use Tuupola\KsuidFactory;
6
7$factory = new KsuidFactory();
8$newId = $factory->create();
9echo "Generated KSUID: " . $newId . "\n";
10?>
11

1// Go
2package main
3
4import (
5    "fmt"
6    "github.com/segmentio/ksuid"
7)
8
9func main() {
10    newId := ksuid.New()
11    fmt.Printf("Generated KSUID: %s\n", newId.String())
12}
13

1// Swift
2import KSUID
3
4let newId = KSUID()
5print("Generated KSUID: \(newId)")
6

References

1. Segment's KSUID GitHub Repository: https://github.com/segmentio/ksuid
2. "Generating good unique identifiers" by Peter Bourgon: https://peter.bourgon.org/blog/2019/05/20/generating-good-unique-ids.html
3. KSUID Specification: https://github.com/segmentio/ksuid/blob/master/README.md