Operator guide for Valet Dedicated 0.10.1

App database

An app can keep its data in a PostgreSQL database that Valet creates for it. The database lives on a second RDS instance, the app database. It is off until you turn it on.

Turn it on

Set app_database.enabled in the module and apply it. Then run valet-dedicated upgrade <tag> so api and worker read the new settings.

module "valet" {
  # ...
  app_database = {
    enabled        = true
    instance_class = "db.t4g.small"
    allocated_gb   = 20
  }
}

Run valet-dedicated check. This line says the instance is ready:

✓ app database kernel-1-appdb is available

If the app database is off, check prints ✓ app database is off.

What it creates

  • An RDS PostgreSQL 17 instance named <name>-appdb, encrypted, in the database's subnets. It accepts TLS only and has no public address.
  • A security group <name>-appdb. The platform and runtime groups reach it on port 5432. Nothing else does.
  • The secret <name>/resource_rds, which holds the admin user and password. The module fills it. valet-dedicated check never reads it.
  • Three CloudWatch alarms, when you set alerts_topic_arn. See Observe.

The platform's own database is a separate instance. An app's data and load never reach it.

Size it

instance_class defaults to db.t4g.small and allocated_gb to 20. Every app database shares the one instance, so size it for the sum of your apps. Each database's plan sets its storage and connection limits, from 2 GiB and 20 connections on economy-1x to 32 GiB and 320 on economy-16x. Valet refuses a new database, or a larger plan, once the plans' connections would pass the instance's max_connections or their storage would pass 80% of allocated_gb. Raise instance_class for more CPU, memory, and connections, and allocated_gb for storage. RDS can grow storage but not shrink it.

Watch <name>-appdb-cpu, -storage, and -connections. To resize, change the inputs and apply the module.

Backups

With protection and backup.enabled, AWS Backup copies the app database every day with the file system and the database. See the backup input in the reference. RDS also keeps 7 days of automated backups. With protection on, the instance takes a final snapshot when you destroy it and refuses deletion until you turn protection off. To restore it, see Restore.

Turning app_database.enabled off later destroys the instance and every app's data on it. Back up first.

Give an app a database

Create a resource from the valet-postgresql provider on a plan, and attach it to the app:

valet resources create valet-postgresql:economy-1x checkout-db --app checkout

The command waits for the database, attaches it, and redeploys the app. The app then reads DATABASE_URL, DATABASE_POOLED_URL, DATABASE_HOST, DATABASE_PORT, DATABASE_NAME, DATABASE_USER, DATABASE_PASSWORD, PGSSLROOTCERT, and NODE_EXTRA_CA_CERTS.

To create the database first and attach it later:

valet resources create valet-postgresql:economy-1x checkout-db
valet resources attach checkout-db --app checkout

Each resource gets its own role and database on the instance. Run valet resources catalog to see the provider and plan. Keep certificate checks on in the app: the server accepts TLS only.