feat: support 256-symbol alphabets and an optional prefix parameter #20 #18 by nik-sta · Pull Request #24 · viascom/nanoid-postgres

nik-sta · 2026-07-13T19:44:58Z

Summary

This PR now carries two features: the prefix work from #29 was squash-merged into this branch, so its diff is part of this PR.

256-symbol alphabets (#20). Raises the maximum alphabet length from 255 to 256 symbols (validation, error message, and inline parameter documentation). For a 256-symbol alphabet every random byte maps directly to a valid alphabet index, so the previous limit was stricter than necessary; upstream ai/nanoid allows 256 as well.

Optional prefix parameter (#18, via #29). Adds prefix text DEFAULT '' as the new last parameter of nanoid(), prepended to the generated id for Stripe-style typed ids (usr_, ord_, ...):

size keeps meaning the number of random symbols; the total id length is length(prefix) + size, so columns must be sized accordingly (e.g. char(25) for nanoid(prefix => 'usr_'))
A NULL prefix behaves like an empty prefix instead of producing a NULL id (coalesce(prefix, ''))
nanoid_optimized() stays unchanged; the prefix is concatenated in nanoid()
The old signature nanoid(int, text, float) is dropped on upgrade, since the signature gains the prefix parameter and positional calls must stay unambiguous
README documents the parameter, the length semantics, and a CREATE TABLE example

Verification

Unit tests: a 256-symbol alphabet generates correct ids, and alphabets with more than 256 symbols are still rejected
Unit tests: positional prefix, named notation nanoid(prefix => 'ord_'), and NULL prefix; SELECT nanoid() behaviour is unchanged (21 characters, default alphabet)
Full multi-version suite (PostgreSQL 9.6 through 18) passed on the stack
Upgrade path verified: installing the new nanoid.sql over an existing installation leaves exactly one nanoid(size, alphabet, additionalBytesFactor, prefix) signature

Credits

Prefix idea by @abdirahmn1.

Closes #20
Closes #18

Summary by CodeRabbit

New Features
- Added optional prefixes to generated Nano IDs. Prefixes do not count toward the requested ID length, and NULL is treated as empty.
- Expanded alphabet support to up to 256 symbols.
- Added validation that rejects alphabets exceeding 256 symbols.
Documentation
- Added usage examples and guidance for prefixed IDs, including recommended column sizing.

Replace the pre-v6 power-of-two mask rejection with the modulo-cutoff rejection that ai/nanoid introduced in v6. Random bytes below 256 - (256 % alphabetLength) are accepted and mapped to a symbol with a modulo; higher bytes are rejected to avoid modulo bias. Benefits: - Far fewer rejected bytes for non-power-of-two alphabets. A 33-symbol alphabet now accepts 231 of 256 byte values instead of 33 of 64, measured 29% faster on PostgreSQL 17 (100k IDs: 0.91s vs 1.28s). - Single-symbol alphabets work now. Previously nanoid(5, 'a') failed with "cannot take logarithm of zero". - The step size formula accounts for the rejection rate itself, so the default additional bytes factor of 1.6 is a good fit for every alphabet. The README section on calculating a custom factor is replaced accordingly. Uniformity verified with chi-square tests: 30.1 (33 symbols, df=32) and 50.5 (64 symbols, df=63) over 200k+ generated characters. BREAKING CHANGE: the third parameter of nanoid_optimized() changed its meaning from a bitmask to the byte cutoff. Callers must pass 256 - (256 % length(alphabet)) instead of (2^n)-1, e.g. 256 instead of 63 for the default 64-symbol alphabet. The nanoid_optimized() calls in the regression tests are updated accordingly.

nik-sta · 2026-07-13T21:41:19Z

@coderabbitai full review

coderabbitai · 2026-07-13T21:41:26Z

✅ Action performed

Full review finished.

coderabbitai · 2026-07-13T21:41:36Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 79a89324-7de1-4660-8572-394bba03e9dd

📥 Commits

Reviewing files that changed from the base of the PR and between 681163e and 3040bd2.

📒 Files selected for processing (3)

README.md
dev/test/unit_tests.sql
nanoid.sql

Disabled knowledge base sources:

Jira integration is disabled
Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

📝 Walkthrough

Walkthrough

The nanoid function now accepts prefixes and custom alphabets containing up to 256 symbols. Unit tests cover prefix behavior, 256-symbol generation, and rejection of larger alphabets. The README documents prefixed ID usage and total-length semantics.

Changes

Nanoid enhancements

Layer / File(s)	Summary
API and alphabet validation `nanoid.sql`	The function gains a NULL-safe `prefix` parameter, removes an older conflicting signature during upgrades, prepends prefixes to generated values, and accepts alphabets up to 256 symbols.
Behavior and boundary tests `dev/test/unit_tests.sql`	Tests cover 256-symbol alphabets, rejection beyond the limit, and positional, named, NULL, multibyte, and mixed-notation prefixes.
Prefixed ID usage documentation `README.md`	Examples document prefixed calls, size and total-length behavior, NULL handling, and typed-prefix table defaults.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant nanoid
  participant nanoid_optimized
  Caller->>nanoid: Call with prefix, size, and alphabet
  nanoid->>nanoid: Validate alphabet and compute parameters
  nanoid->>nanoid_optimized: Generate random ID portion
  nanoid_optimized-->>nanoid: Return random ID portion
  nanoid-->>Caller: Return prefix plus random ID

Possibly related issues

viascom/nanoid-mysql-mariadb#5 — Describes porting these PostgreSQL nanoid enhancements to MySQL/MariaDB.

Suggested labels: breaking-change

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes match the issue requirements by accepting 256-symbol alphabets, rejecting larger ones, updating docs, and adding tests.
Out of Scope Changes check	✅ Passed	The PR stays in scope, with only the validation, docs, and test updates needed for the 256-symbol alphabet change.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title correctly captures the 256-symbol alphabet support, though it mentions an optional prefix parameter not shown in this changeset.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/20-alphabet-256

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@dev/test/unit_tests.sql`:
- Around line 111-118: Update the nanoid rejection test to capture the raised
exception’s MESSAGE_TEXT and assert it contains the expected 256-symbol limit
wording, such as “bigger than 256 symbols.” Keep re-raising assert_failure, but
replace the unconditional raise_exception acceptance with validation of the
rejection message.
- Around line 102-109: Extend the `alphabet256` test loop after generating
`generated_id` to assert every character belongs to `alphabet256`, using a
membership check such as `translate(generated_id, alphabet256, '') = ''`. Keep
the existing length assertion and notice output unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d1bdcb9c-9f41-421a-92cb-e563ebe39a9a

📥 Commits

Reviewing files that changed from the base of the PR and between 661c853 and fd629d4.

📒 Files selected for processing (2)

dev/test/unit_tests.sql
nanoid.sql

…#22 The whole script now runs in one transaction, so a DROP blocked by dependent objects rolls back atomically instead of leaving a partially upgraded install (an old nanoid_optimized() receiving a cutoff as mask would generate constant ids). The current nanoid() signature is no longer dropped (CREATE OR REPLACE upgrades it in place, also under dependent column defaults), the 2022-era nanoid(int, text) signature is dropped to keep positional calls unambiguous, the step cap moved before the int cast (least), and the test suite gained an upgrade-path stage per PostgreSQL version.

The previous limit of 255 was stricter than necessary: for a 256-symbol alphabet the computed mask is 255, so every random byte maps directly to a valid alphabet index. Raise the validation limit and error message to 256, matching the upstream ai/nanoid limit, and add unit tests covering a 256-symbol alphabet plus rejection of alphabets with more than 256 symbols.

… nanoid #20

nik-sta · 2026-07-14T06:51:22Z

@coderabbitai review

coderabbitai · 2026-07-14T06:51:29Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

nik-sta · 2026-07-14T07:15:03Z

@coderabbitai full review

coderabbitai · 2026-07-14T07:15:08Z

✅ Action performed

Full review finished.

You're currently rate limited under our Fair Usage Limits Policy. Your recent PR review activity is in the 95th percentile or higher among CodeRabbit users, so adaptive limits apply. Your next review will be available in 8 minutes.

nik-sta · 2026-07-14T07:53:26Z

@coderabbitai full review

coderabbitai · 2026-07-14T07:53:31Z

✅ Action performed

Full review finished.

# Conflicts: # nanoid.sql

# Conflicts: # README.md # dev/test/run_tests.sh # nanoid.sql

@abdirahmn1

## Summary Adds `prefix text DEFAULT ''` as the new last parameter of `nanoid()`, prepended to the generated id for Stripe-style typed ids (`usr_`, `ord_`, ...): - `size` keeps meaning the number of random symbols; the total id length is `length(prefix) + size`, so columns must be sized accordingly (e.g. `char(25)` for `nanoid(prefix => 'usr_')`) - A `NULL` prefix behaves like an empty prefix instead of producing a `NULL` id (`coalesce(prefix, '')`) - `nanoid_optimized()` stays unchanged; the prefix is concatenated in `nanoid()` - The old signature `nanoid(int, text, float)` is dropped on upgrade, as the install script already does today - README documents the parameter, the length semantics, and a `CREATE TABLE` example Stacked on #24; the diff of this PR is the prefix commit only. ## Verification - Unit tests: positional prefix, named notation `nanoid(prefix => 'ord_')`, and `NULL` prefix; `SELECT nanoid()` behavior is unchanged (21 characters, default alphabet) - Full multi-version suite passes on PostgreSQL 9.6 through 18 - Upgrade path verified: installing the new nanoid.sql over an existing installation leaves exactly one `nanoid(size, alphabet, additionalBytesFactor, prefix)` signature ## Credits Idea by @abdirahmn1. Closes #18  ## Summary by CodeRabbit * **New Features** * Added an optional `prefix` parameter to generated Nano IDs, supporting typed identifiers such as `usr_` and `ord_`. * Prefixes are included in the final ID without reducing the requested random portion size. * Prefixes can be provided positionally or by name. * **Bug Fixes** * A `NULL` prefix now behaves like no prefix (no longer yields a `NULL` identifier). * **Documentation** * Expanded “Prefixed ids” with new SQL examples and clarifications on total ID length and `NULL` prefix behavior. * **Tests** * Added unit coverage for prefix/size interactions, pattern expectations, and edge cases.

nik-sta added enhancement New feature or request upstream-parity Tracks feature parity with the original ai/nanoid library labels Jul 13, 2026

nik-sta force-pushed the feat/20-alphabet-256 branch from 3fd3674 to eae4459 Compare July 13, 2026 20:08

nik-sta changed the base branch from main to feat/22-safe-byte-cutoff July 13, 2026 20:08

nik-sta mentioned this pull request Jul 13, 2026

feat: add optional prefix parameter to nanoid() for typed ids #18 #29

Merged

nik-sta force-pushed the feat/20-alphabet-256 branch from eae4459 to fd629d4 Compare July 13, 2026 20:35

nik-sta force-pushed the feat/22-safe-byte-cutoff branch from 802804e to 661c853 Compare July 13, 2026 20:35

coderabbitai Bot reviewed Jul 13, 2026

View reviewed changes

Comment thread dev/test/unit_tests.sql

Comment thread dev/test/unit_tests.sql

nik-sta added 5 commits July 13, 2026 23:53

docs: document the 1024-byte step cap in nanoid() batching #22

362c1cd

test: assert alphabet membership and rejection message for 256-symbol…

bd35744

… nanoid #20

test: note UTF8 requirement of the 256-symbol alphabet test #20

681163e

nik-sta force-pushed the feat/20-alphabet-256 branch from 6e7a3e8 to 681163e Compare July 13, 2026 22:38

nik-sta added 4 commits July 20, 2026 20:01

docs: fix "equal or greater then 1" comment typo in nanoid() #22

bd6e3b1

Merge branch 'feat/22-safe-byte-cutoff' into feat/20-alphabet-256

101647a

# Conflicts: # nanoid.sql

Merge remote-tracking branch 'origin/main' into feat/22-safe-byte-cutoff

d170a0a

# Conflicts: # README.md # dev/test/run_tests.sh # nanoid.sql

Merge branch 'feat/22-safe-byte-cutoff' into feat/20-alphabet-256

5b490ba

nik-sta changed the title ~~feat: support alphabets with up to 256 symbols #20~~ feat: support 256-symbol alphabets and an optional prefix parameter #20 #18 Jul 20, 2026

nik-sta deleted the branch main July 20, 2026 18:30

nik-sta closed this Jul 20, 2026

nik-sta reopened this Jul 20, 2026

nik-sta changed the base branch from feat/22-safe-byte-cutoff to main July 20, 2026 18:31

Merge branch 'main' into feat/20-alphabet-256

3040bd2

nik-sta merged commit c304264 into main Jul 20, 2026

nik-sta deleted the feat/20-alphabet-256 branch July 20, 2026 18:32

Uh oh!

Conversation

nik-sta commented Jul 13, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Credits

Summary by CodeRabbit

Uh oh!

nik-sta commented Jul 13, 2026

Uh oh!

coderabbitai Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

nik-sta commented Jul 14, 2026

Uh oh!

coderabbitai Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nik-sta commented Jul 14, 2026

Uh oh!

coderabbitai Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nik-sta commented Jul 14, 2026

Uh oh!

coderabbitai Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

nik-sta commented Jul 13, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 13, 2026 •

edited

Loading

coderabbitai Bot commented Jul 13, 2026 •

edited

Loading

coderabbitai Bot commented Jul 14, 2026 •

edited

Loading

coderabbitai Bot commented Jul 14, 2026 •

edited

Loading

coderabbitai Bot commented Jul 14, 2026 •

edited

Loading