# How to Get Started with Upstash Redis

> Sign up for Upstash Redis free tier (256MB, 500K commands/month), connect via TypeScript SDK or REST API, and start caching in minutes. No infrastructure setup required.

**TL;DR:** Sign up at [upstash.com](https://upstash.com), create a free Redis database (256 MB, 500K commands/month), grab your REST URL and token, then use the TypeScript SDK or REST API to start caching, rate limiting, or managing sessions in under 5 minutes. No infrastructure setup required.

## Key Takeaways

- Free tier supports up to 256 MB storage and 500K commands per month, no credit card required.
- [Upstash Redis is HTTP/REST-based](https://upstash.com/docs/redis/features/restapi), making it native to serverless (Vercel, Cloudflare Workers, AWS Lambda).
- The [@upstash/redis SDK](https://www.npmjs.com/package/@upstash/redis) handles authentication and command serialization automatically.
- [Upstash charges $0.2 per 100K commands](https://upstash.com/pricing) on pay-as-you-go; fixed plans start at $10/month.
- Database is live and queryable within seconds of creation; no waiting for infrastructure provisioning.

## Sign Up and Create Your Database

Let's head to [console.upstash.com](https://console.upstash.com) and click **Sign Up**. We can use email, GitHub, or Google to register. Once logged in, we'll click **+ Create Database** in the top right.

A dialog appears asking for a database name, primary region (closest to our writes), and read region (closest to our reads). Let's select a region near our users for lowest latency. The free tier is available globally; we pick one primary region.

Let's click **Next** and select the **Free** plan. Our database is running within seconds. We land on a dashboard showing our database endpoint, password, and monthly command usage.

## Grab Your Credentials

On the database detail page, we'll see two credentials under the "REST API" tab:

- `UPSTASH_REDIS_REST_URL` — Something like `https://[name].upstash.io`
- `UPSTASH_REDIS_REST_TOKEN` — A long alphanumeric string

Let's copy both. These are what authenticate our API requests. Let's treat the token like an API key: don't commit it to version control, let's use environment variables instead.

## Option 1: Connect with the TypeScript SDK

The [@upstash/redis SDK](https://www.npmjs.com/package/@upstash/redis) is the easiest way to work with Upstash in Node.js, Vercel, or Cloudflare Workers.

Let's install it:

```tsx id="code-66hjnerj"
npm install @upstash/redis
```

Let's create a connection:

```tsx id="code-7marzfrv"
import { Redis } from "@upstash/redis";

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL,
  token: process.env.UPSTASH_REDIS_REST_TOKEN,
});

// Set a key
await redis.set("greeting", "hello world");

// Get a key
const value = await redis.get("greeting");
console.log(value); // "hello world"
```

The SDK includes TypeScript types, so you get autocomplete and type safety automatically. No connection pooling to manage: each `redis.*` call fires an HTTP request to Upstash.

## Option 2: Use the REST API Directly

If we prefer raw HTTP, [Upstash's REST API](https://upstash.com/docs/redis/features/restapi) maps Redis commands to POST endpoints:

```tsx id="code-ncbe8q8w"
curl -X POST "https://[name].upstash.io/set/mykey/myvalue" \
  -H "Authorization: Bearer $UPSTASH_REDIS_REST_TOKEN"
```

For example, to increment a counter:

```tsx id="code-5oshgtsa"
curl -X POST "https://[name].upstash.io/incr/page_views" \
  -H "Authorization: Bearer $UPSTASH_REDIS_REST_TOKEN"
```

This is useful for edge runtimes (Cloudflare Workers, Fastly Compute) or languages without a first-class SDK. The response is JSON.

## Common Patterns: Caching, Rate Limiting, Counters

Let's walk through some practical examples using the TypeScript SDK.

**Cache API responses:**

```tsx id="code-sm237vt4"
const cacheKey = `user:${userId}:profile`;
let user = await redis.get(cacheKey);

if (!user) {
  user = await fetchUserFromDB(userId);
  // Cache for 1 hour
  await redis.set(cacheKey, JSON.stringify(user), { ex: 3600 });
}

return JSON.parse(user);
```

**Rate limiting with sorted sets:**

```tsx id="code-zz6su2xn"
const key = `rate:${ip}`;
const now = Date.now();
const window = now - 60000; // Last 60 seconds

// Add current request
await redis.zadd(key, { score: now, member: `${now}:${Math.random()}` });

// Count requests in window
const count = await redis.zcount(key, window, now);

if (count > 100) {
  return { status: 429, message: "Too many requests" };
}

// Clean up old entries
await redis.zremrangebyscore(key, "-inf", window);
```

**Increment counters:**

```tsx id="code-28o2565r"
await redis.incr("daily_signups");
const total = await redis.get("daily_signups");
console.log(`${total} new users today`);
```

## Monitoring and Costs

Your Upstash console shows real-time metrics: command count, data size, bandwidth, and response times. The free tier refreshes every 10 seconds.

On pay-as-you-go, you're charged per command. A simple `set` or `get` is one command. Pipelined commands (multiple operations in one request) count individually. The first 500K commands per month stay free; after that, it's $0.2 per 100K commands.

For consistent, heavy usage (10K+ commands/day), a fixed plan is cheaper. The $10/month plan handles most applications.

## Comparison: When to Use Upstash vs. Other Options

| Aspect | Upstash | Redis Cloud | AWS ElastiCache |
| --- | --- | --- | --- |
| Connection | HTTP/REST (serverless-native) | TCP (connection pooling) | VPC only (not serverless) |
| Free tier | 256 MB, 500K commands/month | 30 MB free | No free tier |
| Pricing | $0.2/100K commands or fixed plans | $0.15/100K or fixed | Per-instance + data transfer |
| Setup | 30 seconds | 2 minutes | 5+ minutes (VPC setup) |
| Latency | Ultra-low globally (multi-region) | Good, regional | Variable (depends on VPC) |
| Best for | Serverless, edge, hobby projects | Production TCP apps | Enterprise VPC deployments |

Choose Upstash if you're on Vercel, Cloudflare Workers, or building a serverless app where you don't have persistent TCP connections. Choose Redis Cloud if you need traditional TCP pooling. Choose ElastiCache only if you're running inside AWS and need VPC isolation.

## FAQ

**Do I need to manage connections?**
No. Every request is stateless HTTP. Upstash handles pooling on their side.

**Can I use Upstash with any Redis client?**
Most clients expect TCP. Use the [@upstash/redis SDK](https://www.npmjs.com/package/@upstash/redis) or raw REST API calls. For traditional clients (redis-py, redis-go), you'd need a TCP bridge.

**What happens when I hit the free tier limit?**
Your commands will fail until the next billing cycle (or you upgrade). Upstash doesn't automatically charge or shut you down; you have to manually upgrade to pay-as-you-go.

**How long does a database live?**
Indefinitely, as long as you have an active account. Upstash doesn't delete inactive databases.

**Can I replicate across regions?**
Global replication (read replicas) is available on paid plans. The free tier is single-region.

**What data structures does Upstash support?**
All standard Redis types: strings, lists, sets, sorted sets, hashes, and streams. [Redis Search](https://upstash.com/docs/search/overall/getstarted) is available as a separate product.

**Is my data encrypted?**
At rest: encryption is available on fixed and enterprise plans. In transit: TLS is always on. Free tier stores data encrypted on disk but doesn't highlight it.

**Can I migrate from Redis Cloud or AWS?**
Yes. Use [redis-migrate](https://github.com/swapnilmishra/redis-migrate) or a script to dump and restore. Upstash is fully Redis-compatible.

**How do I delete my database?**
Go to the database settings and click **Delete Database**. Data is gone immediately.