Snowflaked

A database-agnostic, high-performance, thread-safe Snowflake ID generator for Ruby, powered by Rust.

Snowflake IDs are 64-bit unique identifiers that encode a timestamp, machine ID, and sequence number. They're time-sortable (IDs created later are always larger), making them ideal for distributed systems where you need unique IDs without coordination between machines. Unlike UUIDs, Snowflake IDs are smaller, sortable, and index-friendly for databases.

Add to your Gemfile:

gem "snowflaked"

id = Snowflaked.id
# => 7193489234823847936

All models automatically generate a Snowflake ID for the :id attribute:

class User < ApplicationRecord
end

User.create!
# => #<User id: 7193489234823847936>

You can also define additional Snowflake columns in migrations:

class CreateUsers < ActiveRecord::Migration[8.1]
  def change
    create_table :users do |t|
      t.snowflake :external_id
      t.bigint    :uid
    end
  end
end

Columns created with t.snowflake are automatically detected and will have Snowflake IDs generated for them.

If you want to generate Snowflake IDs for additional columns, you can do so by using the snowflake_id method, without having to migrate the table:

class User < ApplicationRecord
  snowflake_id :uid
end

It is also possible to disable automatic :id generation by passing id: false to the snowflake_id method:

class Post < ApplicationRecord
  snowflake_id id: false
end

Or generate Snowflake IDs for other columns but not :id:

class Post < ApplicationRecord
  snowflake_id :external_id, id: false
end

Snowflaked.configure do |config|
  config.machine_id = 42
  config.epoch = Time.utc(1989, 1, 3) # Defaults to DEFAULT_EPOCH (2024-01-01) if not configured
end

Configuration locks after you call Snowflaked.configure, or after the first generated or parsed ID. Set your configuration during application boot. Do this before you start request threads.

If you use Ractors, set your configuration before you start any other Ractor. See Ractor Safety below for the reason.

Auto-detection is effectively a random value between 0 and 1023 per process. With only 1024 possible values, collisions follow birthday math: at ~40 concurrent processes there is a ~50% chance that two of them share a machine ID, and beyond 1024 processes a collision is guaranteed. A shared machine ID only yields a duplicate ID when both processes generate in the same millisecond with the same sequence number — unlikely, but real at scale. Duplicates on :id are caught by the primary key (ActiveRecord::RecordNotUnique); duplicates on other snowflake columns are silent unless the column has a unique index.

If your fleet is large or duplicate IDs are unacceptable, assign explicit per-process machine IDs (e.g. derived from a pod index plus a worker index).

If machine_id is not explicitly configured, it resolves in this order:

1. SNOWFLAKED_MACHINE_ID environment variable
2. MACHINE_ID environment variable
3. Auto-detected: a process-local value, effectively random between 0 and 1023

For Kubernetes deployments, only set an explicit machine ID if each pod runs a single generating process (e.g. Puma in single mode). A StatefulSet ordinal or pod index is then a good source of unique values:

env:
  - name: SNOWFLAKED_MACHINE_ID
    valueFrom:
      fieldRef:
        fieldPath: metadata.annotations['apps.kubernetes.io/pod-index']

With Puma in cluster mode, leave machine_id unset and let each worker derive its own.

Snowflake IDs require a monotonically increasing clock. If the system clock steps backwards (NTP correction, VM migration), Snowflaked.id raises a RuntimeError instead of risking duplicate IDs, and keeps raising until the clock catches up with the last generated timestamp. Run NTP in slew mode (the default on most systems) to avoid backward steps.

This gem works inside a Ruby Ractor. CI runs the audition gem on every change, to check this.

One rule applies. Call Snowflaked.configure, or generate the first ID, on the main Ractor. Do this before you start any other Ractor. Snowflaked::Configuration must stay open to change: it re-derives machine_id after each fork. For this reason, only the main Ractor can set it up safely, and every other Ractor must find it already set up.

id = Snowflaked.id

Snowflaked.parse(id)
# => {timestamp_ms: 1735123456789, machine_id: 42, sequence: 0}

Snowflaked.timestamp(id)
# => 2024-12-25 12:34:56 +0000

Snowflaked.timestamp_ms(id)
# => 1735123456789

Snowflaked.sequence(id)
# => 0

Snowflaked.machine_id(id)
# => 42

See BENCHMARKS.md for more details.

tl;dr: Snowflake IDs have a negligible performance impact compared to database-backed IDs.

• Ruby >= 3.3
• rustc / cargo >= 1.81.0 (development uses the toolchain pinned in mise.toml)
• Mise

mise install
bundle install
bundle exec rake

• snowflaked-rs - the Rust implementation of Snowflake IDs

MIT