WakaStart
FREN
Databases, storage, routing

Databases and storage

PostgreSQL, MongoDB, Valkey, and S3 buckets: your app's persistent dependencies.

Version v1.02 min read

Databases and storage

📍 Where to find this in the UI

  • Definitions: Infra → Architecture tab → Databases / Storage
  • Instances per env: Infra → Environments → {env} → Databases / Storage

An app often needs to store data. Wakastart supports 2 broad categories.

Database

What is it? A system that stores structured data and lets you query it. It's the core of your app's persistence.

Engines available in Wakastart:

EngineTypeTypical use
PostgreSQLRelational (SQL)The default for most apps: transactions, rigid schema
MongoDBDocument (NoSQL)Flexible data, evolving schemas
Valkey (= Redis)In-memory key-valueCache, sessions, queues

2 modes: IN_CLUSTER vs MANAGED

ModeWhere it's hostedFor
IN_CLUSTERIn the Wakastart K8s cluster, like a podDev, prototypes, low volume
MANAGEDOn managed cloud infrastructure (HA, automatic backups, monitoring included)Serious production

→ You choose the mode at the Definition level (e.g. defaultMode: IN_CLUSTER to ease dev) and can override it per Instance (e.g. in prod, set mode: MANAGED).

Typical usage pattern

text
DatabaseDefinition "primary"
├── engineType: POSTGRESQL
├── defaultMode: IN_CLUSTER
├── defaultPlan: "essential"
└── defaultVersion: "15"

Storage (Storage Bucket) — S3

What is an S3 bucket? A storage system for files/objects: images, videos, PDFs, archives, CSV exports… Anything that isn't structured and doesn't need a relational schema.

S3 = "Simple Storage Service" (originally Amazon, adopted by several providers with a compatible API). Wakastart provisions a dedicated bucket for each environment.

Difference from a database:

  • Database = structured, queryable data (SELECT, etc.). Efficient for reading specific fields.
  • S3 = whole files, cheap cold storage. You PUT a file, you GET a file. No querying inside it.

StorageBucketDefinition / StorageBucketInstance

Same pattern as databases: you define it once at the Architecture level, then it's instantiated per environment.

A StorageBucketInstance produces 6 credentials for the application code:

  • S3_URL — S3 API URL
  • S3_ENDPOINT — regional endpoint
  • S3_REGION — physical region
  • S3_BUCKET — bucket name
  • S3_ACCESS_KEY_ID — access key
  • S3_SECRET_ACCESS_KEY — secret key

→ Your service receives them via environment variables (see the Variables and secrets chapter).