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 it's provisioned for you when you deploy.

The requires field declares: "My app needs this resource — provision it and give me connection details." The database creation, user setup, and credential injection are handled for you at deploy time.

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. $url resolves to 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 your app's health can be verified after it starts. An HTTP GET /health is expected to return a 2xx response.

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 resolve to real values 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/LaunchfileView 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
  BASE_URL:
    default: $app.url
    description: "Public-facing URL; miniflux uses it for absolute links and feed URLs"
health: /healthcheck
restart: always

requires:: Declares a Postgres dependency — provisioned automatically when the app deploys.
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: This endpoint is checked 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] declare?

Key takeaways

requires declares resource dependencies — they're provisioned 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 your app's readiness can be verified after deployment.