Operations
Rotating a K/V token, emptying a store, deleting one, and what CapyDB manages on your behalf.
Every operation below is available in the dashboard under a project's K/V tab, and over the API. Flush and delete run as jobs you can poll; rotation is synchronous, because the response is the only place the new token exists.
Rotate the token
Rotation mints a new token and stops the old one immediately. There is no grace window - unlike database credential rotation, which can issue a second credential and retire the first over a period you choose.
curl -X POST https://capydb.dev/api/capydb/v1/projects/$PROJECT_ID/kv/rotate-token \
-H "Authorization: Bearer $CAPYDB_API_KEY"The response is the one place the new plaintext token appears. Deploy it before rotating, or accept a gap: every client still presenting the old token starts failing authentication at once.
Rotate if a token has been exposed, and rotate if you have lost it - a lost token cannot be recovered, only replaced, because CapyDB stores its SHA-256 hash and nothing else.
Empty the store
flush deletes every key. The store itself survives with the same endpoint and the same token, so
nothing needs redeploying.
curl -X POST https://capydb.dev/api/capydb/v1/projects/$PROJECT_ID/kv/flush \
-H "Authorization: Bearer $CAPYDB_API_KEY"There is no undo and no backup to restore from. The dashboard asks for a second click before it runs.
Delete the store
Deletion removes the store and its data. The project and its database are untouched.
curl -X DELETE https://capydb.dev/api/capydb/v1/projects/$PROJECT_ID/kv \
-H "Authorization: Bearer $CAPYDB_API_KEY"The store moves to destroying while the job runs. A project may hold one store at a time, so a
delete must finish before a new store can be created.
States
| State | Meaning |
|---|---|
provisioning | Being created; the endpoint is not yet answering |
running | Serving traffic |
stopped | Stopped by the platform, data kept; stopped_reason says why |
error | Provisioning or a lifecycle operation failed; contact support |
destroying | Being torn down |
The dashboard shows running as Ready, which is the vocabulary a database cell uses for the
same condition.
stopped is not idle sleep - K/V stores never scale to zero. The only stopped_reason today is
org_suspended: the organization's suspension reached the
offline step, and the store was stopped to release its memory. Its snapshot is kept, and it starts
again automatically - and is running only once it answers - after the suspension lifts. The
dashboard's K/V tab shows a stopped store as Stopped with that explanation, and
capydb kv status spells out the reason the same way.
Connection limits
Per-store connection limits are rolling out; the plan figures below apply once they are enabled.
Each store has a cap on open RESP connections and, separately, on REST requests in flight:
| Plan | RESP connections | REST requests in flight |
|---|---|---|
| Vibe | 32 | 32 |
| Ship | 128 | 128 |
| Business | 512 | 512 |
Past the cap, a RESP handshake is answered with ERR max number of clients reached (after the token
has been checked) and a REST request with 429 and Retry-After: 1. Back off and retry. A client
that opens a connection per request is the usual way to hit the RESP cap; share one client per
process instead - see Clients. Idle RESP connections are also closed after
300 seconds.
What CapyDB manages
These are set for you and are not configurable, which is why the corresponding commands are denied at the ACL:
| Setting | Value | Why |
|---|---|---|
maxmemory | Your plan's capacity | The cell's memory ceiling is enforced by the kernel; a store that could raise its own limit would be able to breach it |
maxmemory-policy | volatile-lru | Bounded memory, and only data you marked expendable with a TTL is ever discarded |
| Persistence | Periodic snapshot | The cell's ceiling is sized so a snapshot fork has headroom |
| TLS | Required | Both endpoints; there is no plaintext listener |
A store is sized from your plan when it is created, and resized to the new plan's size shortly after the plan changes. Applying the new memory limit restarts the store, so connected clients reconnect; the snapshot is kept. A downgrade is refused while the store holds more than 90% of the smaller plan's capacity, and the store keeps its current size until you free space.
Limits and durability
A K/V store is not backed up and is not covered by point-in-time recovery, and it evicts once full. The full statement is in the K/V overview, and the numbers are in Limits.
Clients
Connecting to a CapyDB K/V store over the Upstash REST protocol or RESP - @upstash/redis, @capydb/kv, ioredis, redis-py, go-redis and redis-cli.
Programs and referrals
The startup program, the partner program and referral codes - what each grants, how a code is redeemed, and what the dashboard and API expose.