PostgreSQL Nanoid

84,000+ IDs/second • Secure by default • URL-safe • Collision-resistant

❌ Stop using auto-increment IDs that leak your business data.
❌ Stop using UUIDs that are ugly, long, and random.
✅ Use nanoids: secure, compact, and beautiful.

⚡ Try It Now (30 seconds)

-- 1. Enable extension
CREATE EXTENSION IF NOT EXISTS pgcrypto;

-- 2. Install functions (copy from bottom of README)

-- 3. Generate secure, random IDs (recommended default)
SELECT nanoid('cus_');    -- cus_V1StGXR8_Z5jdHi6B
SELECT nanoid('ord_');    -- ord_K3JwF9HgNxP2mQrTy  
SELECT nanoid('user_');   -- user_9LrfQXpAwB3mHkSt

-- 4. Generate sortable IDs (only if you need time ordering)
SELECT nanoid_sortable('log_');  -- log_0uQzNrIBqK9ayvN1T (⚠️ leaks timing)

🎯 Why Nanoids?

Problem	Auto-increment	UUID	Nanoid	Nanoid Sortable
Leaks business data	❌ Reveals count	✅ Secure	✅ Secure	⚠️ Leaks timing
Length	❌ Predictable	❌ 36 chars	✅ 21 chars	✅ 21 chars
Sortable by time	⚠️ Single DB only	❌ Random	❌ Random	✅ Lexicographic
URL-friendly	✅ Yes	❌ Has dashes	✅ Clean	✅ Clean
Performance	✅ Fast	⚠️ Slower	✅ Fast	✅ Fast

Security recommendation: Use nanoid() by default. Only use nanoid_sortable() when time-ordering is essential and you understand the privacy trade-offs.

🚀 Performance

-- Secure random nanoids (recommended)
SELECT nanoid('ord_') FROM generate_series(1, 10000);   -- ~85ms = 117,000 IDs/sec
SELECT nanoid('user_') FROM generate_series(1, 100000); -- ~0.9s = 111,000 IDs/sec

-- Sortable nanoids (use only when needed)
SELECT nanoid_sortable('log_') FROM generate_series(1, 10000);   -- ~123ms = 81,200 IDs/sec
SELECT nanoid_sortable('event_') FROM generate_series(1, 100000); -- ~1.18s = 84,700 IDs/sec

Production ready:

⚡ 110,000+ IDs/second - random nanoids (fastest, most secure)
🏃 84,000+ IDs/second - sortable nanoids (when time-ordering needed)
🔒 Security-first - random by default, sortable by choice
💾 Memory efficient - streaming generation

🎨 Beautiful, Meaningful IDs

-- Your old UUIDs
f47ac10b-58cc-4372-a567-0e02b2c3d479  -- 😵 36 chars, random order
2514e1ae-3ab3-431e-aa45-225d70d89f61  -- 🤷 Which was created first?

-- Secure random nanoids (recommended)
cus_V1StGXR8_Z5jdHi6B  -- 😍 21 chars, secure & random
ord_K3JwF9HgNxP2mQrTy  -- 🔒 No timing information leaked

-- Sortable nanoids (use carefully)
log_0uQzNrIBqK9ayvN1T  -- ⏰ 21 chars, time-ordered
evt_0uQzNrIEg13LGTj4c  -- ⚠️ But reveals creation timing

When you need time-ordering:

-- Generate sortable IDs over time - naturally sorted!
WITH events AS (
    SELECT nanoid_sortable('evt_') as id, pg_sleep(0.001)
    FROM generate_series(1, 5)
)
SELECT id FROM events ORDER BY id;  -- Chronological! (but less secure)

Security consideration: Sortable IDs make business activity patterns observable to anyone with access to multiple IDs.

🛠️ Production Setup

-- Secure table with random nanoid defaults (recommended)
CREATE TABLE customers (
    id SERIAL PRIMARY KEY,
    public_id TEXT NOT NULL UNIQUE DEFAULT nanoid('cus_'),
    name TEXT NOT NULL
);

-- Optional: Time-ordered table (use only when chronological sorting is essential)
CREATE TABLE audit_logs (
    id SERIAL PRIMARY KEY,
    event_id TEXT NOT NULL UNIQUE DEFAULT nanoid_sortable('log_'),
    message TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

INSERT INTO customers (name) VALUES ('Acme Corp'), ('Widget Co');
SELECT public_id, name FROM customers ORDER BY public_id;
-- cus_V1StGXR8_Z5jdHi6B | Acme Corp    ← Secure, no timing info
-- cus_K3JwF9HgNxP2mQrTy | Widget Co    ← Random order preserves privacy

Production Validation

✅ Collision resistant - 2×10¹⁴ years to 1% probability at 1000 IDs/hour
✅ Scale tested - Millions of records, faster than UUIDs
✅ Index efficient - Time-ordered = better B-tree locality

📖 API

`nanoid(prefix, size, alphabet, additionalBytesFactor)` - Secure Random (Recommended)

SELECT nanoid();                    -- V1StGXR8_Z5jdHi6B-myT
SELECT nanoid('user_');             -- user_V1StGXR8_Z5jdHi6B
SELECT nanoid('cus_', 25);          -- cus_V1StGXR8_Z5jdHi6B-my

✅ Secure: No timing information
✅ Fast: ~10% faster than sortable
✅ Private: Random order preserves business intelligence

`nanoid_sortable(prefix, size, alphabet, additionalBytesFactor)` - Time-Ordered

SELECT nanoid_sortable();           -- 0uQzNrIBqK9ayvN1T-abc
SELECT nanoid_sortable('log_');     -- log_0uQzNrIEg13LGTj4c
SELECT nanoid_sortable('evt_', 25); -- evt_0uQzNrIEutvmf1aS-xy

⚠️ Security trade-off: Embeds creation timestamp
✅ Sortable: Lexicographic time ordering
⚠️ Privacy risk: Reveals business activity patterns

`nanoid_extract_timestamp(nanoid_value, prefix_length)` - Sortable Only

-- Extract creation time from sortable nanoids (debugging/analysis)
SELECT nanoid_extract_timestamp('log_0uQzNrIBqK9ayvN1T', 4);
-- 2025-07-11 19:13:10.204

🚀 Advanced Usage

-- Multiple entity types with secure random IDs (recommended)
SELECT nanoid('cus_');  -- Customer ID (random, secure)
SELECT nanoid('ord_');  -- Order ID (random, secure)
SELECT nanoid('inv_');  -- Invoice ID (random, secure)

-- Time-ordered IDs for logs/events (use sparingly)
SELECT nanoid_sortable('log_');  -- Log entry (sortable, less secure)
SELECT nanoid_sortable('evt_');  -- Event ID (sortable, less secure)

-- Database constraints
CREATE TABLE orders (
    public_id TEXT NOT NULL UNIQUE
        CHECK (public_id ~ '^ord_[0-9a-zA-Z]{17}$')
        DEFAULT nanoid('ord_'),  -- Secure random
    customer_id TEXT CHECK (customer_id ~ '^cus_[0-9a-zA-Z]{17}$')
);

-- Mixed approach: secure customer IDs, sortable audit trail
CREATE TABLE user_actions (
    user_id TEXT CHECK (user_id ~ '^usr_[0-9a-zA-Z]{17}$'), -- Random
    action_id TEXT DEFAULT nanoid_sortable('act_')           -- Sortable
);

-- Batch generation
WITH batch_ids AS (
    SELECT nanoid('item_') as id, 'Product ' || generate_series as name
    FROM generate_series(1, 100000)
)
INSERT INTO products (public_id, name) SELECT id, name FROM batch_ids;
-- ~0.9 seconds for 100k secure random IDs

🤔 When to Use

✅ Use `nanoid()` (secure random) for:

Public-facing IDs (APIs, URLs, customer references)
User-facing identifiers (account IDs, order numbers)
Multi-tenant applications (tenant isolation)
Distributed systems (no coordination needed)
Any case where privacy matters

⚠️ Use `nanoid_sortable()` only when:

Temporal ordering is essential (audit logs, event streams)
You need lexicographic time sorting (without separate timestamp)
Privacy trade-offs are acceptable (internal systems only)
Users won't see multiple IDs (preventing pattern analysis)

❌ Consider alternatives for:

Internal foreign keys (integers might be faster)
Legacy system integration (if systems expect UUIDs)
High-security contexts (consider longer random IDs)

🔧 Installation

Copy-Paste SQL

Click to expand nanoid functions (240+ lines)

CREATE EXTENSION IF NOT EXISTS pgcrypto;

-- Drop existing functions to ensure clean state
DROP FUNCTION IF EXISTS nanoid CASCADE;
DROP FUNCTION IF EXISTS nanoid_sortable CASCADE;
DROP FUNCTION IF EXISTS nanoid_optimized CASCADE;
DROP FUNCTION IF EXISTS nanoid_extract_timestamp CASCADE;

-- Create the optimized helper function for random part generation
CREATE OR REPLACE FUNCTION nanoid_optimized(size int, alphabet text, mask int, step int)
    RETURNS text
    LANGUAGE plpgsql
    VOLATILE LEAKPROOF PARALLEL SAFE
    AS $$
DECLARE
    idBuilder text := '';
    counter int := 0;
    bytes bytea;
    alphabetIndex int;
    alphabetArray text[];
    alphabetLength int := 64;
BEGIN
    alphabetArray := regexp_split_to_array(alphabet, '');
    alphabetLength := array_length(alphabetArray, 1);
    LOOP
        bytes := gen_random_bytes(step);
        FOR counter IN 0..step - 1 LOOP
            alphabetIndex :=(get_byte(bytes, counter) & mask) + 1;
            IF alphabetIndex <= alphabetLength THEN
                idBuilder := idBuilder || alphabetArray[alphabetIndex];
                IF length(idBuilder) = size THEN
                    RETURN idBuilder;
                END IF;
            END IF;
        END LOOP;
    END LOOP;
END
$$;

-- Sortable nanoid function with timestamp encoding (use only if temporal ordering is required)
-- WARNING: This function embeds timestamps in IDs, which can leak business intelligence
-- and timing information. Use the regular nanoid() function for better security.
CREATE OR REPLACE FUNCTION nanoid_sortable(
    prefix text DEFAULT '', 
    size int DEFAULT 21, 
    alphabet text DEFAULT '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ', 
    additionalBytesFactor float DEFAULT 1.02
)
    RETURNS text
    LANGUAGE plpgsql
    VOLATILE LEAKPROOF PARALLEL SAFE
    AS $$
DECLARE
    timestamp_ms bigint;
    timestamp_encoded text := '';
    remainder int;
    temp_ts bigint;
    random_size int;
    random_part text;
    finalId text;
    alphabetArray text[];
    alphabetLength int;
    mask int;
    step int;
BEGIN
    -- Input validation
    IF size IS NULL OR size < 1 THEN
        RAISE EXCEPTION 'The size must be defined and greater than 0!';
    END IF;
    IF alphabet IS NULL OR length(alphabet) = 0 OR length(alphabet) > 255 THEN
        RAISE EXCEPTION 'The alphabet can''t be undefined, zero or bigger than 255 symbols!';
    END IF;
    IF additionalBytesFactor IS NULL OR additionalBytesFactor < 1 THEN
        RAISE EXCEPTION 'The additional bytes factor can''t be less than 1!';
    END IF;
    
    -- Get current timestamp and encode using nanoid alphabet (inline for simplicity)
    timestamp_ms := extract(epoch from clock_timestamp()) * 1000;
    alphabetArray := regexp_split_to_array(alphabet, '');
    alphabetLength := array_length(alphabetArray, 1);
    temp_ts := timestamp_ms;
    
    -- Handle zero case
    IF temp_ts = 0 THEN
        timestamp_encoded := alphabetArray[1];
    ELSE
        -- Convert to base using nanoid alphabet
        WHILE temp_ts > 0 LOOP
            remainder := temp_ts % alphabetLength;
            timestamp_encoded := alphabetArray[remainder + 1] || timestamp_encoded;
            temp_ts := temp_ts / alphabetLength;
        END LOOP;
    END IF;
    
    -- Pad to 8 characters for consistent lexicographic sorting
    WHILE length(timestamp_encoded) < 8 LOOP
        timestamp_encoded := alphabetArray[1] || timestamp_encoded;
    END LOOP;
    
    -- Calculate remaining size for random part  
    random_size := size - length(prefix) - 8; -- 8 = timestamp length
    
    IF random_size < 1 THEN
        RAISE EXCEPTION 'The size including prefix and timestamp must leave room for random component! Need at least % characters.', length(prefix) + 9;
    END IF;
    
    -- Generate random part using optimized function
    mask := (2 << cast(floor(log(alphabetLength - 1) / log(2)) AS int)) - 1;
    step := cast(ceil(additionalBytesFactor * mask * random_size / alphabetLength) AS int);
    
    IF step > 1024 THEN
        step := 1024;
    END IF;
    
    random_part := nanoid_optimized(random_size, alphabet, mask, step);
    
    -- Combine: prefix + timestamp + random
    finalId := prefix || timestamp_encoded || random_part;
    
    RETURN finalId;
END
$$;

-- Main nanoid function - purely random, secure by default
CREATE OR REPLACE FUNCTION nanoid(
    prefix text DEFAULT '', 
    size int DEFAULT 21, 
    alphabet text DEFAULT '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ', 
    additionalBytesFactor float DEFAULT 1.02
)
    RETURNS text
    LANGUAGE plpgsql
    VOLATILE LEAKPROOF PARALLEL SAFE
    AS $$
DECLARE
    random_size int;
    random_part text;
    finalId text;
    alphabetLength int;
    mask int;
    step int;
BEGIN
    -- Input validation
    IF size IS NULL OR size < 1 THEN
        RAISE EXCEPTION 'The size must be defined and greater than 0!';
    END IF;
    IF alphabet IS NULL OR length(alphabet) = 0 OR length(alphabet) > 255 THEN
        RAISE EXCEPTION 'The alphabet can''t be undefined, zero or bigger than 255 symbols!';
    END IF;
    IF additionalBytesFactor IS NULL OR additionalBytesFactor < 1 THEN
        RAISE EXCEPTION 'The additional bytes factor can''t be less than 1!';
    END IF;
    
    -- Calculate random part size (full size minus prefix)
    random_size := size - length(prefix);
    
    IF random_size < 1 THEN
        RAISE EXCEPTION 'The size must be larger than the prefix length! Need at least % characters.', length(prefix) + 1;
    END IF;
    
    alphabetLength := length(alphabet);
    
    -- Generate purely random part using optimized function
    mask := (2 << cast(floor(log(alphabetLength - 1) / log(2)) AS int)) - 1;
    step := cast(ceil(additionalBytesFactor * mask * random_size / alphabetLength) AS int);
    
    IF step > 1024 THEN
        step := 1024;
    END IF;
    
    random_part := nanoid_optimized(random_size, alphabet, mask, step);
    
    -- Combine: prefix + random (no timestamp)
    finalId := prefix || random_part;
    
    RETURN finalId;
END
$$;

-- Helper function to extract timestamp from sortable nanoid (only works with nanoid_sortable)
CREATE OR REPLACE FUNCTION nanoid_extract_timestamp(
    nanoid_value text, 
    prefix_length int DEFAULT 0,
    alphabet text DEFAULT '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
)
    RETURNS timestamp
    LANGUAGE plpgsql
    IMMUTABLE LEAKPROOF PARALLEL SAFE
    AS $$
DECLARE
    timestamp_encoded text;
    timestamp_ms bigint := 0;
    alphabetArray text[];
    alphabetLength int;
    char_pos int;
    i int;
BEGIN
    -- Extract 8-character timestamp after the prefix
    timestamp_encoded := substring(nanoid_value, prefix_length + 1, 8);
    alphabetArray := regexp_split_to_array(alphabet, '');
    alphabetLength := array_length(alphabetArray, 1);
    
    -- Decode from base using nanoid alphabet (inline for simplicity)
    FOR i IN 1..length(timestamp_encoded) LOOP
        char_pos := array_position(alphabetArray, substring(timestamp_encoded, i, 1));
        IF char_pos IS NULL THEN
            RAISE EXCEPTION 'Invalid character in timestamp: %', substring(timestamp_encoded, i, 1);
        END IF;
        timestamp_ms := timestamp_ms * alphabetLength + (char_pos - 1);
    END LOOP;
    
    -- Convert to timestamp
    RETURN to_timestamp(timestamp_ms / 1000.0);
EXCEPTION
    WHEN OTHERS THEN
        RAISE EXCEPTION 'Invalid nanoid format or timestamp extraction failed: %', SQLERRM;
END
$$;

Development Environment

# Clone and test with Docker
git clone https://github.com/your-repo/postgres-nanoid
cd postgres-nanoid
make up && make test-all  # Start + test everything
make psql                 # Connect and try it

Made your IDs better? Give us a ⭐ on GitHub!

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.github/workflows		.github/workflows
init		init
scripts		scripts
tests		tests
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml
nanoid.sql		nanoid.sql

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

PostgreSQL Nanoid

⚡ Try It Now (30 seconds)

🎯 Why Nanoids?

🚀 Performance

🎨 Beautiful, Meaningful IDs

🛠️ Production Setup

Production Validation

📖 API

`nanoid(prefix, size, alphabet, additionalBytesFactor)` - Secure Random (Recommended)

`nanoid_sortable(prefix, size, alphabet, additionalBytesFactor)` - Time-Ordered

`nanoid_extract_timestamp(nanoid_value, prefix_length)` - Sortable Only

🚀 Advanced Usage

🤔 When to Use

✅ Use `nanoid()` (secure random) for:

⚠️ Use `nanoid_sortable()` only when:

❌ Consider alternatives for:

🔧 Installation

Copy-Paste SQL

Development Environment

About

Uh oh!

Contributors 2

Uh oh!

Languages

elitan/postgres-nanoid

Folders and files

Latest commit

History

Repository files navigation

PostgreSQL Nanoid

⚡ Try It Now (30 seconds)

🎯 Why Nanoids?

🚀 Performance

🎨 Beautiful, Meaningful IDs

🛠️ Production Setup

Production Validation

📖 API

nanoid(prefix, size, alphabet, additionalBytesFactor) - Secure Random (Recommended)

nanoid_sortable(prefix, size, alphabet, additionalBytesFactor) - Time-Ordered

nanoid_extract_timestamp(nanoid_value, prefix_length) - Sortable Only

🚀 Advanced Usage

🤔 When to Use

✅ Use nanoid() (secure random) for:

⚠️ Use nanoid_sortable() only when:

❌ Consider alternatives for:

🔧 Installation

Copy-Paste SQL

Development Environment

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Contributors 2

Uh oh!

Languages

`nanoid(prefix, size, alphabet, additionalBytesFactor)` - Secure Random (Recommended)

`nanoid_sortable(prefix, size, alphabet, additionalBytesFactor)` - Time-Ordered

`nanoid_extract_timestamp(nanoid_value, prefix_length)` - Sortable Only

✅ Use `nanoid()` (secure random) for:

⚠️ Use `nanoid_sortable()` only when: