Sqinky - 🦑 Sqids for your Active Record models.

What is Sqids?

Sqids (pronounced "squids") is an open-source library that lets you generate short unique identifiers from numbers. These IDs are URL-safe, can encode several numbers, and do not contain common profanity words.

This is what they look like: https://example.com/CN4Xst

Source: https://sqids.org/

Sqinky brings Sqids-based identifier encoding¹ and decoding directly to your Active Record models.

The library adds a thin access layer on top of Sqids to work effortlessly with short, unique, and URL-safe identifiers. It supports encodings composed of multiple attributes and multiple encodings per model. Sqinky does not store encodings in the database. Instead, it decodes them on the fly back to the initial arguments and uses standard Active Record methods to retrieve the records.

• Dynamic Encodings: Computed from record attributes on the fly. No extra data is stored in the database.
• Auto-generated Helpers: Provides find_by_*, find_by_*!, destroy_by_*, and delete_by_* methods.
• Multiple Attributes: Encode and decode composite identifiers (e.g., [account_id, id]).
• Customizable: Pass any Sqids option (alphabet, min_length, and blocklist) per encoder.

Run the following command to add Sqinky to your Gemfile:

bundle add sqinky

Sqinky officially supports only the Ruby and Rails versions that still receive maintenance from their maintainers, see the Ruby and Rails maintenance policies. The test workflow lists the versions currently tested.

The gemspec allows older versions (ruby >= 3.3, activerecord >= 7.0) so that you are not blocked from installing Sqinky. They may work, but they aren't tested, and bugs that only occur on end-of-life versions may not get fixed.

To use it include Sqinky::IdentifierEncoding in your Active Record model and

• add the encodes_identifier macro for a single attribute (defaults to :id), or
• add the encodes_identifiers macro for multiple attributes.
• See Parameter Overview for all configuration options.

This generates the encoding methods <attribute>_encoding and <attribute>_encoding! (by default; configurable), and the dynamic Active Record methods find_by_*, find_by_*!, delete_by_*, and destroy_by_*. See Generated Method Overview for a detailed overview.

class Comment < ApplicationRecord
  include Sqinky::IdentifierEncoding
  
  encodes_identifier :id
end

# Retrieving the encoding
comment = Comment.create!(text: "Sqinky is the linky that breaks when you drinky.")
comment.id # => 1
comment.id_encoding # => "Uk"

# Finding the comment back
Comment.find_by_id_encoding("Uk") # => #<Comment id: 1, ...>
Comment.find_by_id_encoding!("Uk") # Raises ActiveRecord::RecordNotFound if not found
Comment.destroy_by_id_encoding("Uk")
Comment.delete_by_id_encoding("Uk")

1. Receive encoding from a persisted record: user.id_encoding # => "Uk".
2. Pass the encoding around, either via URL /users/Uk/show or store it in a session.
3. Retrieve the record through the encoding User.find_by_id_encoding("Uk") # => #<User id: 1, ...>

Sqinky can compose multiple attributes into a single encoding, here: :id and :account_id. Normally, this would dynamically generate id_and_account_id_encoding methods, but here we rename them to token with the as: parameter.

class Invitation < ApplicationRecord
  include Sqinky::IdentifierEncoding

  # Encode both `id` and `account_id` into a single `token`
  encodes_identifiers :id, :account_id, as: :token
end

invitation = Invitation.create!(account_id: 42)
invitation.token # => "ySrS"

# Internally calls find_by(id: 1, account_id: 42)
Invitation.find_by_token("ySrS")

If you need to access the decoded hash, you can pass your preferred method name to the decodes_as: parameter, e.g. decodes_as: :id_decoding. This will generate a dynamic class method, that takes a single argument: the encoding.

class Order < ApplicationRecord
  include Sqinky::IdentifierEncoding

  encodes_identifier :id, as: :public_id, decodes_as: :decode_public_id
end

Order.decode_public_id("Uk") # => { id: 1 }

Configure Sqids by passing in the Sqids options: alphabet, min_length, and blocklist. Each coder can have its own configuration.

class Comment < ApplicationRecord
  include Sqinky::IdentifierEncoding

  encodes_identifier :id, alphabet: "abcdef0123456789", min_length: 10
end

A model can have multiple encodings, even for the same attribute, as long as they have distinct as: method names.

class Post < ApplicationRecord
  include Sqinky::IdentifierEncoding
  
  encodes_identifier
  encodes_identifiers :id, :tenant_id
end

post = Post.create!(title: "How Sqinky became so inkie.")
post.id # => 212
post.tenant_id # => 42
post.id_encoding # => "37E"
post.id_and_tenant_id_encoding # => "jGTwn"

Post.find_by_id_encoding("37E") # => #<Post id: 212, ...>
Post.find_by_id_and_tenant_id_encoding("jGTwn") # => #<Post id: 212, ...>

Since Sqinky generates regular methods, it can be included anywhere in the class tree. Child classes can use the parents' methods or overwrite them with their own. It isn't required for the including class to have the configured attributes.

class ApplicationRecord < ActiveRecord::Base
  include Sqinky::IdentifierEncoding
  
  encodes_identifier
end

class Label < ApplicationRecord
end

label = Label.create!(text: "Pinky")
label.id = 1
label.id_encoding # => "Uk"

Sqinky raises an ArgumentError instead of replacing a method that already exists. This includes attributes like id, methods inherited from Active Record like to_param, your own methods, and the methods of another encoding in the same class. Redeclaring an encoding inherited from a parent class is allowed.

class Comment < ApplicationRecord
  include Sqinky::IdentifierEncoding

  encodes_identifier as: :id # => ArgumentError: Comment already defines #id. Choose a different name with `as:` or `decodes_as:`.
end

To use an encoding in URLs, give it its own name and delegate to it:

class Comment < ApplicationRecord
  include Sqinky::IdentifierEncoding

  encodes_identifier as: :token

  def to_param = token
end

By default only canonical encodings are accepted, so every record has exactly one valid encoding. As a consequence, changing a Sqids option invalidates previously issued encodings. This includes raising min_length: "Uk" still decodes to [1], but the canonical encoding becomes "UkLWZg9DAJ", so "Uk" is rejected.

If old encodings must keep working after raising min_length or changing blocklist, pass canonical: false. Encodings with the wrong number of values are still rejected, but several encodings may then resolve to the same record.

class Comment < ApplicationRecord
  include Sqinky::IdentifierEncoding

  # Issues "UkLWZg9DAJ", but still accepts the previously issued "Uk".
  encodes_identifier :id, min_length: 10, canonical: false
end

Sqinky generates these methods when invoking encodes_identifier(s):

After checking out the repo, run the setup script to install dependencies:

bin/setup

This project uses mise for managing Ruby versions and tasks. If you have mise installed, you can use it to run common tasks.

• bin/console: Open an interactive prompt to experiment with the code.
• rake spec: Run the test suite.
• rake standard: Run the StandardRB linter.
• bundle exec appraisal install: Install the dependencies for all supported Rails versions.
• bundle exec appraisal rake spec: Run tests against all supported Rails versions.
• mise run ci: Run the local CI pipeline (linting and multi-Rails tests).
• bundle exec ruby benchmarks/id_encoding.rb: Benchmark encoding and decoding against raw Sqids.
• bundle exec ruby benchmarks/db_retrieval.rb: Benchmark finding records by encoding against SQLite and, if reachable via DATABASE_URL, PostgreSQL. Set NUM_RECORDS, WARMUP, and TIME for quicker runs.

This library aims to adhere to Semantic Versioning 2.0.0. Violations of this scheme should be reported as bugs.

Bug reports and pull requests are welcome on GitHub at https://github.com/david-uhlig/sqinky. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Please report security vulnerabilities privately as described in the security policy.

The gem is available as open source under the terms of the MIT License.