sqids generator

Sqids (pronounced "squids") is a small, open-source library for encoding numbers into short, URL-safe, non-sequential string identifiers. Unlike most entries in the unique-ID landscape, Sqids does not generate new identifiers. Instead, it transforms existing numbers -- typically database auto-increment IDs or composite keys -- into obfuscated string representations that can be deterministically reversed back into the original values. The project is the official successor to the widely adopted Hashids library, which was renamed and rewritten as Sqids in 2023 to address algorithmic weaknesses, improve consistency across language ports, and shed the misleading "hash" branding that implied one-way cryptographic behavior. Sqids is maintained by Ivan Akimov and an open-source community, with official implementations available in over 40 programming languages, from JavaScript and Python to Rust, Go, Swift, and Elixir.

The core philosophy behind Sqids is that many applications already have perfectly good numeric identifiers -- sequential primary keys, composite integer tuples, or auto-generated bigint values -- but need to present them to end users in a form that is short, unpredictable-looking, and safe for use in URLs. Rather than replacing the underlying numbering scheme, Sqids adds a reversible encoding layer on top. This approach keeps the database schema simple, avoids the storage and indexing overhead of long string-based IDs, and gives developers full control over how identifiers appear in public-facing contexts.

How Sqids Works

Sqids operates on one or more non-negative integers and produces a compact alphanumeric string. The algorithm is symmetric: encoding turns numbers into a string, and decoding turns that string back into the original numbers. There is no information loss and no collision risk -- different inputs always produce different outputs for a given configuration.

The encoding process begins with an alphabet, which defaults to the lowercase Latin letters and digits (a total of 36 characters) but can be replaced with any set of unique characters. At initialization, the alphabet is shuffled using a deterministic algorithm seeded by a user-provided string. This shuffle is the primary mechanism that makes the output appear random: consecutive input numbers map to visually unrelated strings because the internal character mapping has been permuted.

When encoding, Sqids selects a prefix character based on the input values and then iterates through each number, dividing it by the alphabet length and collecting remainder characters much like a base conversion. Between each number's encoding, a separator character drawn from the shuffled alphabet is inserted, allowing the decoder to identify boundaries. The alphabet is re-shuffled after each number is encoded, which further scrambles the output and prevents patterns from emerging even when encoding sequences of related numbers.

A configurable minimum length parameter lets developers enforce a consistent string size. If the raw encoding produces a string shorter than the minimum, Sqids pads it using additional characters derived from the shuffled alphabet. This is useful for applications that need fixed-width identifiers for visual consistency or to meet URL slug conventions.

An important design constraint is that Sqids includes a built-in blocklist of common profanity and offensive words. If an encoding happens to produce a string that matches a blocklist entry, the algorithm automatically re-encodes with a different prefix until a clean result is found. This prevents embarrassing or harmful strings from appearing in user-facing URLs.

Because the encoding is entirely deterministic and stateless, Sqids requires no database lookups, no network calls, and no random number generation. The same input with the same configuration always yields the same output, and the same output always decodes to the same input. This makes it trivially cacheable and easy to reason about in distributed systems.

Use Cases

Obfuscating database primary keys in URLs. The most common use of Sqids is hiding sequential auto-increment IDs from end users. Exposing raw IDs like /users/42 or /orders/1053 reveals business metrics (how many users or orders exist) and invites enumeration attacks. Sqids transforms these into opaque slugs like /users/Xk9v2 or /orders/bR7qT, preserving the ability to decode back to the original ID on the server side without any additional database lookup.

Short links and invite codes. URL shorteners, referral programs, and invitation systems need compact, unique, human-friendly codes. Sqids can encode a link's database row ID into a short string suitable for sharing in emails, text messages, or social media. Because the encoding is reversible, resolving a short link requires only decoding the string -- no separate mapping table is necessary.

Multi-value composite identifiers. Sqids can encode multiple numbers into a single string. This is useful for scenarios like encoding a user ID and a resource ID together into one URL parameter, or combining a shard number and a record number into a single token. The decoder returns all original values in order, making it straightforward to reconstruct composite keys.

User-facing references in customer support. Order numbers, ticket IDs, and confirmation codes benefit from being short and easy to read aloud over the phone. Sqids strings are alphanumeric with no special characters, and the blocklist feature ensures they never contain offensive substrings. Combined with a minimum length setting, they produce consistent, professional-looking reference codes.

Comparison with Alternatives

Sqids and Nano ID solve fundamentally different problems. Nano ID is a random string generator -- it creates new, unique identifiers from scratch using a cryptographically secure random source. Sqids is an encoder that transforms existing numbers into strings and back. If you need to mint fresh identifiers without any underlying numeric system, Nano ID is the right tool. If you already have numeric IDs and want to present them differently to users, Sqids is the appropriate choice. The two can even complement each other in the same system: Nano ID for session tokens, Sqids for public-facing record slugs.

Compared to Short-UUID, Sqids serves a different niche. Short-UUID takes standard UUIDs and re-encodes them into shorter strings using a larger character alphabet, reducing a 36-character UUID to roughly 22 characters. It operates on 128-bit UUID values, not arbitrary integers. Sqids, on the other hand, works with plain numbers and supports encoding multiple values at once. Short-UUID is the better fit when your system already uses UUIDs and you want a more compact representation; Sqids is better when your source identifiers are simple integers or integer tuples.

It is also worth comparing Sqids to general-purpose base encoding schemes like base62 or base64. A naive base62 encoding of an integer will produce a shorter string than decimal, but consecutive inputs will still produce visibly sequential outputs (42 encodes to something obviously close to 43). Sqids adds alphabet shuffling, prefix selection, and inter-number separators specifically to break this sequential relationship. The result is that two adjacent inputs look completely unrelated in their encoded forms, which is the entire point for user-facing identifiers. Base62 is simpler if you do not care about obfuscation; Sqids is the better choice when non-sequential appearance matters.