• Get started

    • Getting started
    • Concepts
    • Tour
  • Using shpyrd

    • Deploying
    • shpyrd.yaml
    • Resources
    • Databases and caches
    • Domains and exposure
    • Sign-in for your app
    • Teams, roles and security
    • AI assistants (MCP)
    • Logs
    • Dashboard
    • CLI reference
  • Running it yourself

    • Installation
    • Oracle Cloud (OKE)
    • AWS (EKS)
    • Extensions and sign-in
    • Platform backups
    • Architecture guide
  • Project

    • Design principles
    • Roadmap
    • How to contribute
    • Support the project
  1. Using shpyrd
  2. Databases and caches
Sign in
Start free

Databases and caches

PostgreSQL databases (CloudNativePG) and Redis-compatible stores (Valkey) as project resources, attached to apps as config vars.

A project can have PostgreSQL databases (run by the CloudNativePG operator) and Valkey or Redis caches and queues. Attach one to the app and it appears as DATABASE_URL or REDIS_URL.

On shpyrd cloud, add them from the project's Resources page: its Add resource menu creates a database or a store, and Attach hands it to the app; shpyrd attach and shpyrd detach work from the CLI as well (Attaching).

Self-hosted

On a cluster you run, two extensions add the data stores. The shpyrd pg and shpyrd redis commands then work the same way, signed in with shpyrd login, or through a kubeconfig with --context (see the CLI reference):

shpyrd-ctl extensions enable postgresshpyrd-ctl extensions enable redis

PostgreSQL

shpyrd pg create db --project shop                        # PostgreSQL 17, 5Gi (on a 50Gi disk on Oracle Cloud, the block volume minimum), 1 instance, size shared-s (128Mi)shpyrd pg create db --project shop --size shared-m --storage 20Gi --instances 3   # HA with replicasshpyrd pg resize db shared-l --project shop               # another size; the instances restart one at a timeshpyrd pg list --project shopshpyrd pg psql db --project shop -- -c 'select version()'shpyrd pg delete db --project shop --yes                  # refused while attached (or --force)

Each database is its own CloudNativePG cluster in the project namespace: streaming replication and failover when --instances is 2 or 3, a db-rw service for the primary and db-ro for replicas, a database app owned by user app. The instance size sets CPU and memory; The data volume is a block volume on shpyrd cloud and the cloud profiles (at least 50 GiB on Oracle Cloud, the provider minimum; a smaller request keeps its size on a 50 GiB disk, and the status says so) and sits on the node's own disk on the local profile, like every project volume (Volumes); the database's backups are what protect it.

Shared and dedicated

A database has a type, set when it is created and changed only by shpyrd pg convert:

  • dedicated (the default where the plan allows it): a PostgreSQL cluster of its own, with a disk, a size, a version, one or more instances and a sleep setting. Everything on this page about sizes, backups and sleep is about dedicated databases.
  • shared: a database and a role on a platform-owned PostgreSQL 17 server, always on. It has no instance settings; --storage is its size cap instead of a disk ("900Mi of 1Gi" in shpyrd pg info). Shared databases have no instance size, number of instances, version or sleep setting; they are always on. Those belong to a dedicated database.
shpyrd pg create db --project shop --type shared              # the plan's cap, 1Gi unless the workspace says otherwiseshpyrd pg create db --project shop --type shared --storage 5Gi

The workspace's plan says which types it allows and which one a creation without --type gets ("Your plan includes a shared database. A dedicated database comes with a paid plan." on a plan without dedicated ones), how many databases of both kinds the workspace may have ("This would bring the workspace to 2 of 1 databases."), and how many instances a dedicated one may run. A dedicated database's disk counts against the block storage ceiling once per instance; a shared database counts as a database and nothing else. Apps see no difference: DATABASE_URL keeps its shape, the host is the database's own name, and the connection is encrypted to the server (sslmode=require; the server's certificate names the server, so verify-full is a dedicated feature). The URL also carries connect_timeout=10: a client that connects while the server fails over (about five seconds) waits ten seconds and tries again rather than hanging on the old address until TCP gives up, which takes two minutes. The database and user inside the URL are hashed names (db_…, u_…): an app that hard-codes app must read them from the config vars.

What a shared database does differently:

  • The cap. It is what the database is metered by, as a disk is metered by its size. Its size is measured every five minutes. At 80 % the status warns; at 150 % connections are paused (the role's connection limit goes to zero and its sessions end) until the database is back below 95 %. Free space, or raise the limit.
  • Neighbours. Nobody but the owner may connect to the database. pg_database and pg_roles are world-readable in PostgreSQL, so other tenants' hashed names are visible, never their project names; pg_stat_activity shows other sessions' presence, not their queries.
  • Extensions. PostgreSQL's trusted extensions are yours to CREATE EXTENSION as the database's owner: pgcrypto, uuid-ossp, citext, hstore, pg_trgm, unaccent, btree_gin, btree_gist, ltree, intarray and the others PostgreSQL marks trusted. pgvector (vector) is installed in every database by the platform, shared and dedicated (CREATE EXTENSION vector is not yours to run; it is already there). Anything else PostgreSQL does not mark trusted is not available (PostgreSQL answers "permission denied to create extension").
  • psql. shpyrd pg psql runs in a helper pod of your project with your credentials, never inside the shared server.
  • Archives and moves. A project archive carries a shared database's definition, not its data, which lives on the platform's server: a restore recreates it empty (its copies come back with shpyrd pg restore), and a move of the project's disks leaves it where it is. The operation's report says so.
  • Connections. When a server's connections run high (the seven-day 95th percentile above 60 % of its limit), the platform puts a connection pooler in front of it: PgBouncer in transaction mode, one per server. DATABASE_URL then reaches the pooler with no change to your app, and DATABASE_DIRECT_URL reaches the server itself, for what a transaction pool cannot carry: a migration that needs its session, LISTEN/NOTIFY, session-level SET, an advisory lock held across transactions. DATABASE_DIRECT_URL is there from the first day, pointing at the same place until a pooler comes, so an app can use it before one does. pg info says when a database goes through its pooler.
  • Conversion. shpyrd pg convert <name> --to dedicated moves a shared database into a cluster of its own, under its name: the cluster takes the shared user, database and credentials, so DATABASE_URL changes only its host and the apps bound to it restart once; --storage and --size set its disk (default 5Gi) and instance size. shpyrd pg convert <name> --to shared goes the other way, when the workspace's plan allows: the database must fit the shared cap (refused up front with its measured size: "This database holds 3 GB; a shared database holds up to 1 GB.") and hold only the extensions a shared database can (PostgreSQL's trusted ones and pgvector; refused in words otherwise, before anything moves), its disk goes, and it gets new user and database names, so the apps restart once with the new credentials. Either way connections pause while the rows are copied and counted (a few minutes per gigabyte), pg info follows the steps, and a copy of the source stays restorable for seven days (shpyrd pg backups list shows it as "converted"). A conversion that cannot land puts the database back as it was and says why.
  • Rotation. shpyrd pg rotate <name> gives the role a new password, rewritten into the project's credentials; the apps bound to the database restart with it within a minute.
  • Deletion. The role can no longer log in and its sessions are ended at once, and a last copy is taken; the data stays seven days and is then dropped, the role and the copies with it. shpyrd pg restore <deleted> --as <new> still works meanwhile.
  • Backups. The server itself is archived continuously and backed up daily by the platform, for the day a server is lost with everyone on it; that is an operator's tool. For your database: every night the platform takes a pg_dump of each shared database, as a read-only role of its own, into a bucket of the server's; the newest seven are kept. shpyrd pg backups list shows the copies, shpyrd pg backup takes one now, and shpyrd pg backups enable <name> --retention 14d keeps fourteen instead of seven (7, 14 or 30); there is nothing to turn off. shpyrd pg restore <name> --as <new> loads the newest copy (or the one --backup names) into a new shared database, as its owner; a point in time (--to) is a dedicated database feature.

Sizes

Databases have a list of sizes of their own, as Heroku's add-ons have plans of their own: the names are the processes' (shpyrd sizes list shows the three lists), but a Postgres shared-s is not a process shared-s. A database takes only a Postgres size, and gets the smallest when it names none. Each size sets the CPU, the memory, the connections and PostgreSQL's settings for them:

SizeCPUMemoryConnectionsshared_bufferswork_mem
shared-s (default)0.5, shared128 MiB2016MB1MB
shared-m0.5, shared256 MiB4064MB1.2MB
shared-l1, shared512 MiB80128MB1.2MB
shared-xl2, shared1 GiB120256MB1.6MB
dedicated-s11 GiB120256MB1.6MB
dedicated-m24 GiB2001GB3.8MB
dedicated-l48 GiB3002GB5.1MB
dedicated-xl816 GiB4004GB7.7MB
dedicated-2xl1632 GiB5008GB12.3MB

From 256 MiB up, shared_buffers is a quarter of the memory, effective_cache_size three quarters, maintenance_work_mem a sixteenth (at most 2GB) and work_mem what remains shared by four sorts or hashes per connection. Under 256 MiB, shared-s keeps the settings measured for it (maintenance_work_mem 16MB, effective_cache_size 48MB, wal_buffers 1MB, autovacuum_work_mem 16MB) and a patient liveness probe: a small app's database, a Prisma or Rails migration with its CREATE INDEX, a web process with a pool of 5 to 10 connections; not a reporting database. A few connections of each size are kept for the platform (17 of 20 are the app's).

How they were chosen: each size up to 1 GiB ran PostgreSQL 17 in its memory, less what CloudNativePG's instance manager keeps, with pgbench on every connection the app may open, a write load and then hash-and-sort queries on all of them while an index was built. None was killed for memory; the peaks were 86% (shared-s), 87% (shared-m), 57% (shared-l) and 41% (shared-xl) of what was left.

shpyrd pg resize, or Resize on the project's Resources page, gives a database another size of the list; its instances restart with it one at a time, so a database with one instance is unavailable for a moment. Memory goes down only when the size does. The workspace's memory and CPU limits count databases with the processes: a database or a resize that would pass them is refused, and so is a process scaled into memory a database holds.

A database made before databases had sizes of their own is given the Postgres size with the CPU and memory it runs with (one that named no size ran 256 MiB: shared-m), and restarts once with that size's settings: its connections become the size's.

Backups and point-in-time recovery

With the object-storage extension enabled (Extensions), a database can be backed up continuously: WAL archiving plus a daily base backup into a bucket of the platform's store that only this database's key can open, kept for the retention period.

shpyrd pg create db --project shop --backups --retention 14d       # or later:shpyrd pg backups enable db --project shop --retention 7d --schedule "0 3 * * *"shpyrd pg backups list db --project shop                           # base backups, with the recovery windowshpyrd pg backup db --project shop                                 # one now, before something riskyshpyrd pg restore db --as db-restored --to 2026-09-25T16:58:02Z --project shop

These commands speak the workspace API: signed in with shpyrd login, they need no kubeconfig. pg info and the dashboard show the state (on, daily at 02:00 UTC, kept 7d, last …, recoverable from …). A restore never touches the source: it creates a new database recovered to the moment you name (RFC 3339, UTC; the latest possible when omitted), any second inside the window, with its own credentials; when it is ready, shpyrd attach db-restored and detach the old one. Restores are refused before the earliest recoverable point, in the future and onto the database itself; the new database takes the source's size unless --size names another Postgres size. shpyrd pg backups disable stops archiving; existing backups stay restorable until the database is deleted, when its bucket goes with it.

Where the backups live depends on the platform's object store (Object storage). On shpyrd cloud, and on a cluster you run that was installed with --object-storage-credentials-file, they go through the platform's S3 gateway into a bucket at the cloud provider: they outlive the cluster, and the operator can reach them there during a recovery. On a cluster without the gateway (a local one), they live in the cluster's own store and go with the cluster; pg_dump what must survive it. Either way, a platform backup restores the database's definition on a new cluster, not its contents.

Sleep

A database nobody is connected to can be put to sleep: its instance stops, its volume and data stay, and the first connection wakes it. While it sleeps you pay for the volume only. Sleep is an enterprise feature (auto sleep): always on shpyrd cloud, with a license on a self-hosted install.

shpyrd pg sleep db --project shop --after 30m      # sleep after 30 min without client connectionsshpyrd pg sleep db --project shop --after off      # never sleep, whatever the workspace's defaultshpyrd pg sleep db --project shop --after default  # follow the workspace's default againshpyrd pg suspend db --project shop                # stop now and stay stopped; connections are refusedshpyrd pg resume db --project shop

A workspace can set a default quiet period for its databases; a database with no policy of its own follows it. off is a policy of its own: the database stays awake even when the workspace's default changes. shpyrd pg sleep db --project shop with no flag says which of the three applies, where it comes from and the state now; pg info and the project's Resources page say the same, and the page's Sleep button on a dedicated database sets it.

Backups and sleep: a sleeping database archives nothing, so a database with backups is copied before it sleeps when its last copy is older than a schedule period (a day by default). The copy runs first and the database sleeps once it is done; if it has not finished in an hour, or it failed, the database sleeps anyway and its status says so ("no fresh backup"). The schedule is suspended while it sleeps and resumed at the wake, and a copy is taken after a wake when the last one is still older than a period. pg backups list shows these copies with the scheduled ones.

How it decides: every five minutes the platform counts the database's client sessions. Any connection counts — an application's idle connection pool keeps its database awake, on purpose; a database sleeps when its app has no connection open, which is what happens when the app itself is asleep or has no pool. The database will not sleep when the count is stale (the metrics pipeline is down), when the quiet period has not elapsed, or when the wake proxy is not running; pg info says which.

How it wakes: the database's address stays the same. While it sleeps, connections land on a proxy that holds them, starts the database and hands them over once PostgreSQL accepts connections — the client sees a slow connect, not an error. Expect up to 30–40 s for the first connection after sleep, while PostgreSQL starts; the next connections take milliseconds. An app whose first request needs its database therefore sees the app wake plus the database wake; the app's resuming: page mode covers that with a "waking up" page, wait mode may exceed HTTP client timeouts.

Only single-instance databases sleep; a database with --instances 2 or more exists to be available. Setting or removing a policy re-releases the attached apps once (their database host changes to the platform's wake-capable address). Sleep keeps the volume; it is not a backup — see above for those.

Not there yet: connection pooling and credential rotation.

Redis and Valkey

shpyrd redis create cache --project shop                  # Valkey 8, cache modeshpyrd redis create queue --project shop --persistent --storage 2Gi   # append-only file on a volumeshpyrd redis create legacy --project shop --engine redis  # upstream Redis 7shpyrd redis resize cache shared-m --project shop         # another size; the store restartsshpyrd redis cli cache --project shop -- INFO memory

A store takes a size from the Redis list, the processes' names with clients of their own, and gets the smallest when it names none:

SizeCPUMemorymaxmemoryClients
shared-s (default)0.5, shared64 MiB48 MiB100
shared-m0.5, shared256 MiB192 MiB400
shared-l1, shared512 MiB384 MiB1000
shared-xl2, shared1 GiB768 MiB2000
dedicated-s11 GiB768 MiB2000
dedicated-m24 GiB3 GiB5000
dedicated-l48 GiB6 GiB10000

A resize restarts the store: a cache comes back empty, a persistent store reloads its file. A store made before stores had sizes of their own and naming a size the list does not have is given the Redis size its pod runs with.

Valkey (BSD licensed, protocol compatible) is the default engine; --engine redis selects upstream Redis. A store is a single instance run by the shpyrd controller: maxmemory is 75% of the size's memory; a cache evicts with allkeys-lru and loses its content on restart, which is the expected behaviour of a cache; a persistent store keeps an append-only file on a volume and refuses writes instead of evicting when full. Persistence cannot change after creation. A cache sleeps with the project's web process: while the web process sleeps and no other process of the project runs, the cache is scaled to zero, and it comes back with the web process, empty; a persistent store stays up. High availability through an operator comes later.

Attaching

shpyrd attach db --project shop                 # DATABASE_URL, DATABASE_HOST, DATABASE_PORT, DATABASE_USER, DATABASE_PASSWORD, DATABASE_NAMEshpyrd attach cache --project shop              # REDIS_URL, REDIS_HOST, REDIS_PORT, REDIS_PASSWORDshpyrd attach sessions --prefix SESSIONS        # SESSIONS_URL, ... when two stores of the same kind are attachedshpyrd detach db --project shop

Attaching adds a binding to the app and releases it (Attach Postgres db); the variables are read-only on the project's Config page and in shpyrd secrets list, shown with the resource providing them, and they win over a config var of the same name. If the resource is still provisioning, the app waits (phase Pending, "waiting for an attached resource") and releases when it is ready. Detaching removes the variables in a new release, and rollback restores the attachments a release had. The project's Resources page has Attach/Detach buttons and an Add resource menu with the same forms.

Resources live inside the project's network policy: only the project's own processes can reach them, other projects cannot.

On this page

  • PostgreSQL
  • Shared and dedicated
  • Sizes
  • Backups and point-in-time recovery
  • Sleep
  • Redis and Valkey
  • Attaching
Back to top
  • AI Community
  • Vibe Coders
  • Developers
  • Businesses
  • FDEs & Implementation Partners
  • Getting Started
  • Pricing
  • Docs
  • Changelog

© 2026. shpyrd. All rights reserved.LegalTerms of ServicePrivacy Policy