Adding a Database — Learn Launchfile

The requires field

Most real apps need a database. Traditionally, you'd provision one manually, copy the connection string into an env var, and hope nobody forgets a step. With a Launchfile, you declare what you need and the provider creates it for you.

The requires field tells the provider: "My app needs this resource. Provision it and give me connection details." The provider handles the actual database creation, user setup, and credential injection.

Build it up

Start from where we left off in Lesson 1. Add requires: [postgres] — the shorthand syntax for declaring a database dependency.

version: launch/v1
name: my-app
runtime: node
commands:
  start: "node server.js"
requires: [postgres]

The shorthand is convenient, but expands to the full form behind the scenes. Both are valid.

requires: [postgres]

# is equivalent to:

requires:
  - type: postgres

Use set_env to wire the database connection into your app. The provider fills in $url with the actual connection string at deploy time.

version: launch/v1
name: my-app
runtime: node
commands:
  start: "node server.js"
requires:
  - type: postgres
    set_env:
      DATABASE_URL: $url

Add a health check endpoint so the provider knows your app is running correctly. It will hit GET /health periodically.

version: launch/v1
name: my-app
runtime: node
commands:
  start: "node server.js"
requires:
  - type: postgres
    set_env:
      DATABASE_URL: $url
health: /health

Shorthand

requires: [postgres]

Expanded

requires:
  - type: postgres

How expressions work

Resource expressions

Inside set_env, you can reference properties of the provisioned resource using $ expressions:

$url — Full connection URL (e.g. postgres://user:pass@host:5432/dbname)
$host — Database hostname
$port — Port number
$user — Username
$password — Password
$name — Database name

These are expressions that the provider resolves at deploy time. Use $url when your framework expects a single connection string, or individual fields when it expects them separately.

In the wild

Miniflux is a minimalist feed reader that needs Postgres. Notice how it uses set_env to wire the database, declares env vars with defaults, and even generates a secret for the admin password.

miniflux/Launchfile View on GitHub

version: launch/v1
name: miniflux
description: "Minimalist and opinionated feed reader"
repository: https://github.com/miniflux/v2
logo: https://raw.githubusercontent.com/miniflux/v2/main/internal/ui/static/bin/icon-512.png

image: miniflux/miniflux:latest
provides:
  - protocol: http
    port: 8080
    exposed: true
requires:
  - type: postgres
    set_env:
      DATABASE_URL: $url
env:
  RUN_MIGRATIONS:
    default: "1"
    description: "Run database migrations on startup"
  CREATE_ADMIN:
    default: "1"
    description: "Create admin user on first run"
  ADMIN_USERNAME:
    default: "admin"
    description: "Admin username"
  ADMIN_PASSWORD:
    required: true
    sensitive: true
    description: "Admin password"
    generator: secret
health: /healthcheck
restart: always

requires:: Declares a Postgres dependency — the provider provisions Postgres however its platform chooses.
set_env:: Injects the connection URL into the DATABASE_URL environment variable.
generator: secret: Auto-generates a secure admin password at deploy time — no manual setup needed.
health: /healthcheck: The provider pings this endpoint to verify the app is alive.

Try it: npx launchfile up miniflux to launch this app locally. View in catalog

Check your understanding

What does requires: [postgres] tell the provider?

Key takeaways

requires declares resource dependencies — the provider provisions them automatically.
Use set_env with $url, $host, $port, etc. to wire connection details into your app.
Shorthand ([postgres]) and expanded syntax (- type: postgres) are equivalent.
Add health so the provider can verify your app is running correctly after deployment.