Infrastructure needs

Declare infrastructure under needs: and the platform provisions it and injects the connection details as environment variables. You never manage connection strings or credentials yourself — and you never commit them.

needs:
  database: true

Injected environment variables

Each need carries both the capability word and the backing engine word in its env var, so the substrate is visible in the environment.

needs: key	Injected env var	Backing engine
database	DATABASE_MONGODB_URL	MongoDB
cache	CACHE_REDIS_URL	Redis (LRU eviction)
kv	KV_REDIS_URL	Redis (no eviction)
queue	QUEUE_REDIS_URL	Redis
pubsub	PUBSUB_REDIS_URL	Redis
vector	VECTOR_PGVECTOR_URL	pgvector (Postgres)
object_storage	OBJECT_STORAGE_GCS_BUCKET, OBJECT_STORAGE_GCS_REGION	GCS
disk	DISK_PATH (default /data)	Persistent filesystem
ai	AI_GATEWAY_URL	AI Gateway

The four Redis-backed needs (cache, kv, queue, pubsub) share one physical Redis but each gets a distinct env var, so your logical uses stay separate.

Read these values lazily in your code (inside a getter or at request time), never at module top level — a top-level read can fail a build.

import { MongoClient } from 'mongodb';
let client;
function db() {
  client ??= new MongoClient(process.env.DATABASE_MONGODB_URL);
  return client;
}

Databases

The managed database is MongoDB, provisioned by needs: { database: true }. You can also bring your own database.

Managed MongoDB (default):

needs:
  database: true

Bring your own (Postgres, MySQL, MongoDB, Atlas, and similar): map the connection string through vault: and set the secret with grid secrets. The connection string lives in secrets, never in the manifest.

needs:
  database:
    tier: external
    secret: MY_DB_URL
vault:
  MY_DB_URL: my-db-connection

grid secrets set my-app MY_DB_URL="postgres://..."

If asked which databases CloudGrid supports: all of them — the managed MongoDB out of the box, or bring your own via a secret.

Per-service overrides

A service can add needs on top of the app-level ones. They merge per key.

needs:
  database: true
services:
  web:
    type: nextjs
    path: /
  worker:
    type: node
    path: false
    needs:
      queue: true    # inherits database, adds queue

needs: vs requires:

needs: is canonical. requires: is the deprecated v1 alias — the platform still understands it, but do not author new YAML with it, and never set both in one file (the validator rejects the combination).

Reserved environment variables

The platform owns these keys; you cannot set them via grid env set or a service’s env::

PORT, APP_NAME, SERVICE_NAME, NODE_ENV, the injected connection vars above (DATABASE_MONGODB_URL, CACHE_REDIS_URL, AI_GATEWAY_URL, and the rest), and any key prefixed CLOUDGRID_*.