Skip to content
Velloreth
Projects 7 min read

Case Study: Building a URL Shortener

First-person case study of building a URL shortener: stack choices, code generation, database schema, open redirect bug, rate limiting, and the mistakes that mattered.

By

A URL shortener looks like a weekend project until you run it for real. It takes a long URL, gives back a short code, and redirects anyone who visits the short link to the original. That is the whole product. The trap is everything around it: code generation, collisions, redirect speed, spam, abuse, and what happens when someone sends your links in a phishing campaign.

I built one over two weekends and ran it for about six weeks. Here is what I built, what broke, and what I would change if I started over.

What I set out to build

The goal was simple: I paste https://example.com/a/very/long/path, I get https://shrt.example/xk9L2p, and visiting the second URL sends the browser to the first. I also wanted a count of how many times each link was clicked, and a page where I could see my own links.

I did not want custom domains, user accounts, or an API in version one. One domain, one table, one redirect. That scope held for two days and then kept expanding.

Stack and why

I chose Node.js with Express, PostgreSQL for the mapping table, and Redis as a hot cache for redirects.

ComponentChoiceReason
Language/runtimeNode.jsWhat I already knew; fast to ship
Web frameworkExpressMinimal, one route does the redirect
DatabasePostgreSQLDurable, one table, SQL is fine
CacheRedisSub-millisecond reads on the redirect path
Short code generationRandom base62Six characters, unpredictable

I deliberately did not use a NoSQL store or a message queue. The data model is one row per link: id, code, target_url, created_at, click_count. PostgreSQL handles that without thinking. The queue would have been complexity for a problem I did not have.

The data model

CREATE TABLE links (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  code varchar(12) NOT NULL UNIQUE,
  target_url text NOT NULL,
  created_at timestamptz NOT NULL DEFAULT now(),
  click_count bigint NOT NULL DEFAULT 0
);

CREATE INDEX idx_links_code ON links(code);

The code column is the short slug. target_url is the destination. click_count is incremented asynchronously so it never blocks the redirect.

Code generation: base62 and collisions

I generate codes by picking random characters from 0-9, a-z, A-Z — base62 — six characters long. That gives roughly 56 billion combinations, which sounds like enough until you remember the birthday problem: collisions become likely well before you exhaust the space.

My first implementation used a counter encoded in base62: aaaaaa, aaaaab, and so on. It never collided, but it was guessable. Anyone could enumerate every link ever created by incrementing the code, and they could see links meant to be unlisted. I threw that out.

The second version picked random six-character codes and inserted them. On a unique violation, it retried with a new code:

function generateCode(retries = 5) {
  const chars = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
  let code = '';
  for (let i = 0; i < 6; i++) {
    code += chars[Math.floor(Math.random() * chars.length)];
  }
  return code;
}

async function createLink(targetUrl) {
  for (let i = 0; i < 5; i++) {
    const code = generateCode();
    try {
      return await db.insert({ code, targetUrl });
    } catch (err) {
      if (err.code === '23505') continue; // unique_violation
      throw err;
    }
  }
  throw new Error('could not generate unique code');
}

PostgreSQL error code 23505 is the unique violation. The retry loop handles the rare collision. This was the right shape, but I will come back to the randomness source below.

The redirect route

The redirect path is the only path that matters for performance. It reads the cache first, falls back to the database, and issues a 302 Found:

app.get('/:code', async (req, res) => {
  const code = req.params.code;
  let url = await redis.get(`link:${code}`);

  if (!url) {
    const row = await db.query('SELECT target_url FROM links WHERE code = $1', [code]);
    if (row.rows.length === 0) {
      return res.status(404).send('not found');
    }
    url = row.rows[0].target_url;
    await redis.setex(`link:${code}`, 3600, url);
  }

  incrementClickAsync(code); // fire and forget
  res.redirect(302, url);
});

302 instead of 301 because I wanted to count every click. A 301 is cached by browsers, so repeat visitors never hit my server and the click count lies. The trade-off is a server hit on every visit, which was fine at my traffic level.

The cache-aside pattern keeps the redirect fast: Redis returns in under a millisecond, and the database is only touched on a miss.

The open redirect mistake

Three days after launch I tested something obvious I had not tested before: what happens if the target URL is https://evil.com? Answer: my shortener happily redirected there. Worse, I had not validated the target at all, so someone could create shrt.example/xk9L2p pointing at a login-phishing page and send it to victims. The short domain lent it credibility because the first hop was mine.

I added validation before saving:

function isSafeUrl(url) {
  try {
    const parsed = new URL(url);
    return parsed.protocol === 'https:' || parsed.protocol === 'http:';
  } catch {
    return false;
  }
}

I blocked non-HTTP schemes (javascript:, data:) and required a parseable URL. I did not maintain an allowlist of domains — that would have blocked legitimate uses — but validation stopped the obvious abuse.

The lesson: a redirector is an open redirect by default. Validate the target before you store it, not after someone reports it.

Rate limiting on creation

I forgot rate limiting on the create endpoint entirely. Within a week someone was using it to generate hundreds of links per minute — spam destinations, affiliate pages, things I did not want associated with my domain. There was no CAPTCHA, no limit, no friction.

I added express-rate-limit keyed on IP:

const createLimiter = rateLimit({
  windowMs: 60 * 60 * 1000,
  limit: 20,
  standardHeaders: 'draft-8',
  legacyHeaders: false,
});

app.post('/links', createLimiter, createLinkHandler);

Twenty links per hour per IP is enough for a person and too little for a spammer. I should have had it from the first deploy. Creation is the write path; the write path is where abuse lands first.

Click counting without slowing the redirect

Incrementing click_count synchronously inside the redirect handler added 20–40 ms of database latency to every redirect. That does not sound like much, but it doubled the redirect time and held the connection open.

I moved it out of the request path:

// inside the redirect handler, before res.redirect
await redis.publish('clicks', JSON.stringify({ code, at: Date.now() }));
res.redirect(302, url);

A small worker subscribes to the clicks channel and increments PostgreSQL in batches every ten seconds. The user gets the redirect immediately; the count catches up asynchronously. The count is eventually consistent, which is fine for a dashboard — it is not fine for billing, and I never pretended it was.

What I got wrong

Guessable codes in version one. The counter-based scheme let anyone enumerate links. Random base62 fixed it, but I should have started there.

No target validation. The open redirect was a real vulnerability, not a theoretical one. It went live because I never tested the create flow with a malicious URL.

No rate limiting on creation. The write path was wide open for a week. Rate limiting belongs on creation before the first user signs up.

I built analytics before traffic. I spent an evening on a dashboard with graphs before anyone had clicked a single link. No one looked at it. The redirect and the create form were the product; everything else was procrastination.

I did not think about link rot. Targets change, pages disappear, and short links outlive their destinations. I had no expiry, no way to mark a link as archived, and no report of which links returned 404 at the target. That is still open work.

What stayed simple

The redirect route never changed. One cache lookup, one database fallback, one 302. That is the part that worked from day one and is still running. When in doubt, optimize the path that runs on every click and leave the rest alone.

The database schema also survived unchanged. One table, one index, no migrations beyond the initial create. If I were building it again I would start with exactly that and resist adding columns until a real query needed them.

A URL shortener is not interesting technology. It is a cache with a shorter name. The interesting part is operating it — validation, rate limiting, collision handling, and deciding what not to build. I got some of those right and some wrong, and the redirects kept working either way.

Frequently asked questions

How do you stop short codes from colliding?
Check the database before inserting, and if the code exists, generate a new one. With enough entropy — six or more base62 characters chosen randomly — collisions are rare, but you still handle them because they will happen eventually.
What database should a URL shortener use?
PostgreSQL works fine for the mapping table, and Redis is a good cache for hot redirects. You do not need a specialized store; you need a fast read path for the redirect and a durable write path for new links.
Do you need custom domains?
Not at first. A custom domain adds DNS, SSL, and reputation management. Start on your own domain, prove people click, then offer custom domains as a paid feature once the redirect path is solid.
How do you count clicks without slowing the redirect?
Redirect immediately, then increment the counter asynchronously in a background job or a Redis stream. The user gets a 302 within milliseconds; the analytics write happens after the response is sent.