Connect to Upstash Redis from your Mac

Everything about Upstash on this page comes from Upstash’s documentation as of October 2026; we didn’t connect to an Upstash database ourselves.

What you need

• Your database’s endpoint, port and token, from the Upstash Console. The token is the password; there is no separate one.
• A client with TLS turned on. Upstash enables TLS on every database, and it can’t be disabled.
• A client that speaks the Redis protocol over TCP, as redis-cli, Inlet and the usual client libraries do. Upstash also serves the same database over an HTTP REST API, made for serverless and edge runtimes where TCP connections are restricted; that’s a different endpoint and token, not something a Redis client uses.
• If the database has an IP allowlist, your Mac’s public IPv4 address on it. The allowlist is available on every plan except the free one; with no entries, any address can connect.

Find your connection details

1. Sign in to the Upstash Console and open your database.
2. On the Details tab, note the Endpoint, Port and Token. The tab also has a ready-made redis-cli command with all three filled in.
3. Or copy the whole connection string from the Connect section’s TCP tab, which Upstash’s troubleshooting pages point to.

Users. The token belongs to the default user. If you choose Read-Only Token under Connect › TCP, the connection string switches to the default_ro user, and the read-only token only works with that user name. On paid databases you can create your own ACL users with ACL SETUSER.

One database. Upstash exposes a single logical database: SELECT 0 is accepted so clients that send it keep working, and any other number returns an error. Separate data with key prefixes instead.

Regional and global databases. New databases are global: you pick a primary region, where every write goes, and optional read regions. Clients are routed to the nearest region, and writes reach the read regions asynchronously, so a value someone has written can take a moment to appear there. Upstash says a single TCP connection reads its own writes. Its older regional (single-region) databases are, in its words, legacy and deprecated, and it suggests migrating to a global one.

Limits. On the free plan and Pay-as-you-go, one request can be up to 10 MB, one record up to 100 MB, at up to 10,000 commands a second (fixed plans allow more). The free plan includes 500,000 commands a month and 250 MB of data. Every command counts, including the ones a client sends while you browse: Inlet, for example, reads keys a page at a time with SCAN.

Commands. Upstash supports the Redis protocol up to version 8.4 and lists the commands it supports, by category, in its command reference; most of what’s missing is on its roadmap. Its search uses its own SEARCH.* commands, which aren’t compatible with the FT.* commands of the RediSearch module. The REST API has extra gaps (no blocking commands such as BLPOP, no WATCH), which don’t apply over TCP.

Connection string

rediss://default:<token>@<endpoint>:6379

Two s’s in rediss: that’s what turns TLS on. Keep default: before the token. Upstash points out that ioredis needs the colon before the password, and a URL without a user means different things to different clients (see Redis connection strings). With the read-only token:

rediss://default_ro:<read-only-token>@<endpoint>:6379

TLS

Always on. A client that connects without TLS fails: Upstash’s documentation shows ioredis reporting Error: read ECONNRESET, because the server drops the connection.

Upstash’s examples connect with redis-cli --tls and no CA file. Without --cacert, redis-cli checks the server’s certificate against the system’s trusted root certificates, so there’s nothing to download.

Connect with Inlet

1. Copy the rediss:// connection string from the console and paste it into Inlet, which fills in the connection form with TLS on. Or choose New Connection, pick Redis, and enter the endpoint, port, user default and the token as the password, with TLS turned on.
2. Inlet checks the server’s certificate. Save the token in the Keychain, or have Inlet ask every time.
3. Leave the database at 0.
4. Tag the environment. On a connection tagged production, Inlet refuses write and admin commands before they’re sent. To have the server refuse writes as well, connect as default_ro with the read-only token.

Connect from the command line

Upstash’s command, from its documentation:

redis-cli --tls -a <token> -h <endpoint> -p 6379

That prints Warning: Using a password with '-a' or '-u' option on the command line interface may not be safe. To keep the token off the command line, put it in REDISCLI_AUTH:

REDISCLI_AUTH='<token>' redis-cli --tls -h <endpoint> -p 6379

Or pass the URL: redis-cli -u 'rediss://default:<token>@<endpoint>:6379'. Homebrew’s redis formula builds redis-cli with TLS support, so brew install redis gives you one that works here. Without --tls, or with redis:// instead of rediss://, Upstash says the connection fails.

Troubleshooting

• read ECONNRESET, or a connection closed right away: TLS is off. Use rediss:// or --tls. Inlet says The server closed the connection while Inlet was signing in. If it accepts only TLS, turn on TLS for this connection.
• NOAUTH Authentication required: the token is missing. With ioredis and a URL, check the colon before the token. Inlet says The server needs a password. and asks for it.
• WRONGPASS invalid username-password pair: a wrong or reset token, or the read-only token with the default user (use default_ro). Inlet says Wrong user name or password.
• ERR max concurrent connections exceeded: you’ve reached the database’s limit on open connections. Upstash’s advice is to close connections you don’t need (serverless functions often leave them open), or use its REST-based SDK.
• ERR max request size exceeded, ERR max single record size exceeded, ERR max daily request limit exceeded, ERR DB capacity quota exceeded: one of the plan limits above. Upstash has a troubleshooting page for each.
• A timeout: check the endpoint and port, and whether the database has an IP allowlist that doesn’t include your current address. Changes to the allowlist can take a few minutes to apply.
• A value changed elsewhere a moment ago isn’t there yet: in a global database, reads come from the nearest region and replication is asynchronous. Reload after a moment.