https://github.com/ksuid/ksuid
K-Sortable Globally Unique IDs for Java
https://github.com/ksuid/ksuid
coordination java ksuid unique-id uuid
Last synced: 26 days ago
JSON representation
K-Sortable Globally Unique IDs for Java
- Host: GitHub
- URL: https://github.com/ksuid/ksuid
- Owner: ksuid
- License: mit
- Created: 2021-04-05T04:03:14.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-08-20T17:54:02.000Z (6 months ago)
- Last Synced: 2025-08-20T19:41:59.658Z (6 months ago)
- Topics: coordination, java, ksuid, unique-id, uuid
- Language: Java
- Homepage:
- Size: 395 KB
- Stars: 136
- Watchers: 7
- Forks: 10
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-java - KSUID
README
# ksuid
[](https://maven-badges.herokuapp.com/maven-central/com.github.ksuid/ksuid)
[](https://javadoc.io/doc/com.github.ksuid/ksuid)
This is a Java port of [Segment's K-Sortable Globally Unique IDs](https://github.com/segmentio/ksuid).
KSUID is for K-Sortable Unique IDentifier. It's a way to generate globally unique IDs similar to RFC 4122 UUIDs,
but contain a time component so they can be "roughly" sorted by time of creation.
The remainder of the KSUID is randomly generated bytes.
In summary:
* Roughly sortable by creation time;
* Can be stored as a string of 27 chars;
* Can be stored as an array of 20 bytes;
* String format is encoded to [base-62](https://en.wikipedia.org/wiki/Base62) (0-9A-Za-z);
* String format is URL safe and has no hyphens.
For the story of how KSUIDs came about, see [A brief history of the UUID](https://segment.com/blog/a-brief-history-of-the-uuid).
## Usage as cli
To use this as a command-line program on Unix-like systems, run
```bash
wget https://repo1.maven.org/maven2/com/github/ksuid/ksuid/1.1.4/ksuid-1.1.4-cli.jar
sudo mv ksuid-1.1.4-cli.jar /usr/local/bin/ksuid.jar
wget https://github.com/ksuid/ksuid/raw/refs/tags/ksuid-1.1.4/ksuid.sh
sudo mv ksuid.sh /usr/local/bin/ksuid
sudo chmod +x /usr/local/bin/ksuid
ksuid
# prints 1HCpXwx2EK9oYluWbacgeCnFcLf
```
## Usage as library
Add the library to maven pom.xml (or the equivalent in your build system):
```xml
com.github.ksuid
ksuid
1.1.4
```
If using JPMS, add the library to your `module-info.java`:
```java
requires com.github.ksuid;
```
Then simply generate a ksuid string like this:
```java
import com.github.ksuid.Ksuid;
...
String ksuid = Ksuid.newKsuid().toString();
System.out.println(ksuid); // prints 1HCpXwx2EK9oYluWbacgeCnFcLf
```
For more complex use cases, create a `KsuidGenerator` with a `SecureRandom` and get a new `Ksuid` for use.
Note that `KsuidGenerator` is threadsafe and `Ksuid` is immutable (and therefore threadsafe).
```java
import com.github.ksuid.KsuidGenerator;
...
// Construct a new KsuidGenerator object. Since it is threadsafe you only need one.
private static final KsuidGenerator KSUID_GENERATOR = new KsuidGenerator(new SecureRandom());
// Get a new Ksuid object.
final Ksuid ksuid = ksuidGenerator.newKsuid();
// The toString() method is the string representation of KSUID.
System.out.println("ksuid:\n" + ksuid + "\n");
// The log string format shows some details on one line, suitable for logging.
System.out.println("ksuid.toLogString():\n" + ksuid.toLogString() + "\n");
// The inspect string format shows details.
System.out.println("ksuid.toInspectString():\n" + ksuid.toInspectString());
```
The output from the code block above is
```
ksuid:
1HCpXwx2EK9oYluWbacgeCnFcLf
ksuid.toLogString():
Ksuid[timestamp = 150215977, string = 1HCpXwx2EK9oYluWbacgeCnFcLf payload = [124, 76, 43, -110, 116, -6, \
-91, 45, 0, -125, -127, 109, 28, 24, 28, -17], ksuidBytes = [8, -12, 29, 41, 124, 76, 43, -110, 116, \
-6, -91, 45, 0, -125, -127, 109, 28, 24, 28, -17]]
ksuid.toInspectString():
REPRESENTATION:
String: 1HCpXwx2EK9oYluWbacgeCnFcLf
Raw: 08F41D297C4C2B9274FAA52D0083816D1C181CEF
COMPONENTS:
Time: 2019-02-14 23:32:57 -0800 PST
Timestamp: 150215977
Payload: 7C4C2B9274FAA52D0083816D1C181CEF
```
## Performance
A very rough performance profile for generating KSUIDs was run on a MacBook Pro with a 3.1 GHz Intel Core i7 and 16 GB 2133 MHz LPDDR3 RAM.
```java
public static void main(final String[] args) {
final KsuidGenerator generator = new KsuidGenerator(new SecureRandom());
IntStream.range(0, 100).forEach(i -> generator.newKsuid()); // prime the random
IntStream.iterate(1000, operand -> operand * 10)
.limit(5)
.forEach(count -> {
final long start = System.nanoTime();
IntStream.range(0, count).forEach(i -> generator.newKsuid());
final long duration = TimeUnit.MILLISECONDS.convert(System.nanoTime() - start, TimeUnit.NANOSECONDS);
System.out.println(String.format("%,d in %,d ms. rate = %,d/ms", count, duration, count / duration));
});
}
```
The output from the code block above is
```
1,000 in 14 ms. rate = 71/ms
10,000 in 32 ms. rate = 312/ms
100,000 in 95 ms. rate = 1,052/ms
1,000,000 in 881 ms. rate = 1,135/ms
10,000,000 in 6,665 ms. rate = 1,500/ms
```
## License
This library is Open Source software released under the [MIT license](https://opensource.org/licenses/MIT).