Resource Uses

Declare what the app uses of a required resource — two named databases and pub/sub — the platform satisfies exactly that, and each use registers its own $resource.use.property fields.

What this demonstrates

`requires: redis` says the app needs Redis; `uses:` says what it needs *of* it — here two logical databases and pub/sub channels
Undeclared means what the entry always meant: an instance address for redis, one database for postgres. Nothing existing changes
Each use registers its own fields: `$redis.db.url` is the Redis URL with the database selected by path (`redis://host:6379/3`), `$redis.db.index` that integer; `pubsub` and `server` are addressed through the instance's own `$url`
A repeatable use is named to occur more than once: `- db: queue` and `- db: sessions` each get their own database, addressed as `$redis.db.queue.url` and `$redis.db.sessions.url` — never the same index. One database keeps the bare `db` and `$redis.db.url`; naming `pubsub` or `server` is a validation error
A platform may satisfy the entry from a shared instance only when every declared use fits — pub/sub ignores database numbers, so isolated channels need an instance the app does not share
A provider covers every declared use or refuses the component before launch, naming the entry and the use; a token it does not recognise is refused too — a typo fails the deployment rather than being ignored
`$redis.db.url` beside an entry that does not declare `db` is an error at wiring time, never a quiet fallback to the instance URL

When to use this: Apps that run a queue, a cache or sessions in Redis and also fan out over pub/sub — and any app a platform might want to serve from a pooled instance.

Resource uses Resource Use Vocabulary Expressions

resource-uses.yamlView on GitHub

# yaml-language-server: $schema=../schema/launchfile.schema.json
#
# Example: declaring what an app uses of a required resource (`uses`).
#
# `requires: redis` says the app needs Redis. It does not say what the app
# needs *of* it — one keyspace, pub/sub channels, or the whole server — and
# that is the app's fact to state, not the platform's to guess. `uses` states
# it. Undeclared means what the property vocabulary already promises (an
# instance address for redis, one database for postgres); declared uses
# narrow the need and register their own `$<resource>.<use>.<property>`
# fields.
#
# A platform may satisfy the entry from a shared unit only when every declared
# use fits in it; otherwise it provisions, or refuses. A use a provider cannot
# cover — including a token it does not recognise — refuses the component
# before launch, naming the entry and the use; it never hands over less than
# the file declares.
#
# A repeatable use (`db` on redis, `database` on postgres and mysql) may occur
# more than once on one entry, each occurrence named — `- db: cache` — and
# addressed as `$<resource>.<use>.<name>.<property>`. An entry that needs one
# database declares the bare token and addresses it as `$redis.db.url`.
#
# See also: spec/SPEC.md § Resource uses and § Resource Use Vocabulary.

version: launch/v1
name: board

image: ghcr.io/example/board:latest

provides:
  - port: 3000
    protocol: http
    exposed: true

requires:
  - type: postgres
    set_env:
      DATABASE_URL: $url

  # Two isolated logical databases — one for the job queue, one for the
  # session cache — plus pub/sub for the websocket fan-out between replicas.
  # `db` is repeatable, so each occurrence carries a name. Pub/sub ignores
  # database numbers, so a platform can only satisfy this from an instance
  # whose channels the app does not share.
  - type: redis
    uses:
      - db: queue
      - db: sessions
      - pubsub
    set_env:
      # The standard Redis URL with the database selected by path,
      # e.g. redis://redis:6379/3 — the queue's own keyspace.
      QUEUE_URL: $redis.db.queue.url
      # The same database as an integer, for clients that take it separately.
      QUEUE_DB: $redis.db.queue.index
      # A different database: the platform never hands two names one index.
      SESSION_URL: $redis.db.sessions.url
      # The instance address, unchanged by `uses` — pub/sub connects here.
      PUBSUB_URL: $url

env:
  PORT: "3000"

health: /healthz

Key lines explained

- db: queue: The app's fact, not the platform's strategy: a named keyspace of its own. db is repeatable, so each occurrence carries a name. Leave uses off and the entry means what it always did.
QUEUE_URL: $redis.db.queue.url: Registered by the named db use — the standard Redis URL with the database allocated to queue selected by path.
SESSION_URL: $redis.db.sessions.url: A different database: two names never share an index.
PUBSUB_URL: $url: The instance address, unchanged by uses. pubsub registers nothing of its own.

See this pattern in real apps — Redis-backed apps like Outline, Docmost, and Paperless use one keyspace for their queues and pub/sub for their websockets — the shape this example declares.