has_public_record

Short, prefixed, URL-safe public ids for ActiveRecord models: usr_K3F9A2. The prefix says what the id belongs to, the random part is short, and it grows by itself as a table fills.

class User < ApplicationRecord
  has_public_record prefix: "usr"
end

user = User.create!
user.public_id        # => "usr_K3F9A2"
user.public_id_bare   # => "K3F9A2"
user_path(user)       # => "/users/usr_K3F9A2"   (to_param)
User.find_by_public_id!("usr_K3F9A2")

Requires Ruby 3.2+ and Rails 7.1+.

Database ids leak counts and invite enumeration. A prefixed id is safe to put in URLs and logs, and the prefix lets you resolve an id with no other context: HasPublicRecord.resolve("usr_K3F9A2") returns the User.

has_public_record prefix: "usr",          # required, unique across the app
                  column: :public_id,     # where the id is stored
                  length: 8,              # starting length of the random part for this model
                  max_bumps: 4            # how far the length may grow before ExhaustedError

A prefix is 1 to 10 characters: lower-case letters and digits only, starting with a lower-case letter ("usr" and "inv2" are fine; "Usr", "2fa" and "a_b" raise InvalidPrefixError). Two models cannot share a prefix (DuplicatePrefixError).

Declare it on the base class of an STI hierarchy, once. A subclass cannot declare it again, and an abstract class cannot declare it at all (it has no table). Declaring costs no database access, so it is safe while the app boots.

The column is a string with a unique index. It uses a custom attribute type, so anything assigned or queried is normalized: User.new(public_id: "usr_k3f9a2") stores usr_K3F9A2, and User.where(public_id: "k3f9a2") finds it. Reading a row returns exactly what is stored, so a legacy bare code stays visible as bare until you migrate it. Raw SQL (update_all with a string, execute) bypasses the type, and insert_all may or may not use it depending on your Rails version, so do not rely on either.

The id is read-only once created (regenerate_public_id! is the one way to replace it). Ids you supply on create must start with the model's prefix and use only alphabet characters.

On the model:

On a record:

On the module:

Ids are matched in any letter case (usr_k3f9a2 finds usr_K3F9A2) when the alphabet has one case; an alphabet with both cases is left as typed. Lookups do not check the alphabet, so ids made under an older alphabet stay findable. public_id_format follows the current alphabet: when you change the alphabet, widen it.

resolve_many is for a pile of mixed refs (an audit log, polymorphic references). It groups refs by prefix and runs one query per model, and refs that match nothing are left out of the result:

HasPublicRecord.resolve_many("usr_K3F9A2", "ses_7QX2B1", "zzz_nope")
# => { "usr_K3F9A2" => #<User>, "ses_7QX2B1" => #<Session> }

Ids start at default_length (6 by default, about 2 billion codes). When random tries keep hitting existing codes, the length grows by one and is remembered per table and column for the life of the process. It never grows past the starting length plus max_bumps, so a long outage cannot ratchet it up for good. Each growth is announced (see Notifications), so you can see a table getting dense before it matters.

Two inserts racing on the same random code raise ActiveRecord::RecordNotUnique from the unique index. That is very rare (it needs the same code from two writers in the same moment), so there is no built-in retry; rescue and retry in your own code if your traffic makes it worth it.

# config/initializers/has_public_record.rb  (rails g has_public_record:install writes it, all commented out)
HasPublicRecord.configure do |config|
  config.default_length = 6
  config.attempts_per_length = 10
  config.max_length_bumps = 4
  config.alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"   # 2+ distinct, no "_", no whitespace; or :unambiguous
  config.lengths = { "users" => 8 }                          # per table; beats a model's length:
end

Settings are read when an id is made, never copied at load, so an app that keeps its settings elsewhere can assign them from its own boot code. config.alphabet = :unambiguous leaves out 0/O and 1/I/L, which makes ids easier to read aloud. Prefixes are code, not settings.

Two steps, so a populated table never needs a NOT NULL column it cannot satisfy:

rails g has_public_record:migration users              # nullable column + unique index
rails db:migrate
rails has_public_record:backfill MODEL=User            # gives every row an id
rails has_public_record:report                         # all clean?
rails g has_public_record:migration users --enforce    # now NOT NULL
rails db:migrate

Options: --column=name, and --concurrently (builds the index without locking writes on PostgreSQL; other databases build it normally). For new tables, t.string :public_id, null: false, index: { unique: true } is enough.

On a very large PostgreSQL table, change_column_null scans the table under a lock. The lock-light route (PostgreSQL 12+) is a CHECK constraint added unvalidated and then validated, after which NOT NULL needs no scan; the --enforce migration carries the lines as a comment.

MODEL= accepts User, user or users.

Renaming a prefix breaks every stored URL and any id saved in another table.

The generator needs no model. Whether a code is free is a block. The examples use things that are not models with has_public_record (a model that declares a prefix cannot also be used as a standalone prefix):

HasPublicRecord.generate("key", length: 10) { |id| !Redis.exists?(id) }        # => "key_7K2QX9ABCD"
HasPublicRecord.generate(nil, length: 5, key: "codes") { |id| !Redis.exists?(id) }  # bare code: key names its growth

coupons = HasPublicRecord.identifier("cpn", length: 8) { |id| !Coupon.exists?(code: id) }
coupons.generate                  # grows and notifies exactly like models do
coupons.valid?("cpn_7K2QX9AB")    # => true
coupons.bare("cpn_7K2QX9AB")      # => "7K2QX9AB"

Standalone prefixes are not registered for HasPublicRecord.resolve; only models are.

Rails fixtures and insert_all skip callbacks, so rows get no id unless you supply one:

# fixtures: the same label always gives the same id
alice:
  public_id: <%= User.fixture_public_id(:alice) %>

# bulk inserts: one existence query for the whole batch
User.insert_all(User.with_generated_public_ids(rows))

backfill_public_ids! is the after-the-fact fix for rows that were inserted without an id.

Plain Rails associations are enough. Keep integer foreign keys inside the system and use the public id only at the edge, scoped through the owner so one person cannot reach another's records:

current_user.sessions.find_by_public_id!(params[:id])

Through ActiveSupport::Notifications, never a logger of its own:

Works inside an engine. Prefixes are global per process, so choose distinctive ones. An engine should not call HasPublicRecord.configure (it is process-wide); use the per-model length: and max_bumps: instead.

MIT.