Skip to main content

Configure Connections

The connections block in your config.cap.yaml is a list of services your application needs to connect to. When you define a connection, CAP injects the environment variables your application needs to reach that service.

connections:
  - service: main-db
  - shared: project-search
  - external: mysql
    host: external-db.example.com
    database: billing
    username: billing_user
    password:
      gitlab: EXTERNAL_DB_PASSWORD

Each entry is one of three kinds, decided by the key you open it with: service for a service you declared yourself, shared for one provisioned for your whole project, or external for a service running outside CAP. The remaining keys depend on that choice.

Options

Property Type Description Default
service string The name of a service declared under services. See Deployed services. None
shared string The name of a service provisioned for your project. See Shared services. None
external string The kind of service running outside CAP: mysql, mariadb, postgresql or cockroachdb. See External services. None
name string An alias for the connection, folded into the environment variable names. See Naming and environment variables. default
database string or integer The database to connect to. On service and shared, an existing database instead of one created for you; on Dragonfly, the database index, and values below 0 are rejected; on external, the database to open, and required. See Existing databases and vhosts. One created for you, 0 on Dragonfly
vhost string On service and shared connections to RabbitMQ, an existing vhost to connect to instead of one created for you. See Existing databases and vhosts. One created for you
host string On external connections, where to reach the service. Required. None
port integer On external connections, the port it listens on. Per kind, listed below
username string On external connections, the user to authenticate as. Required. None
password.gitlab string On external connections, the name of the GitLab CI/CD variable holding that user's password. Required. See GitLab CI/CD secrets. None
version string On external mysql, mariadb and postgresql connections, the version the server runs. Read by symfony applications only. None

The default port follows the kind of external service: 3306 for mysql and mariadb, 5432 for postgresql, and 26257 for cockroachdb.

Deployed services

This is the most common type of connection. It connects your application to a service that is defined in the services block of your config.cap.yaml.

services:
  main-db:
    type: mariadb

  main-queue:
    type: rabbitmq

connections:
  - service: main-db
  - service: main-queue
    name: queue

Naming a service that is not declared under services is rejected.

Shared services

A shared service is provisioned for your whole project rather than for one application, so several applications can connect to the same one. You do not declare it under services; connect to it by the name it was provisioned under.

connections:
  - shared: project-db

External services

An external connection points at a service running outside CAP, such as a database managed by a cloud provider. Unlike the other two kinds, you supply the address and credentials yourself.

connections:
  - external: mysql
    name: billing_db
    host: external-db.example.com
    port: 3306
    database: billing
    username: billing_user
    password:
      gitlab: EXTERNAL_DB_PASSWORD

The password is never written in your configuration. Give the name of a GitLab CI/CD variable under password.gitlab and the value is read from there.

Existing databases and vhosts

By default a connection to a database or to RabbitMQ gets its own database or vhost, created and named for you. Set database or vhost to connect to one that already exists instead.

connections:
  - service: main-db
    database: legacy_reporting
  - service: main-queue
    vhost: shared-events

Naming an existing database or vhost also stops CAP from creating it. It has to already be defined by another connection or another application, or there is nothing to connect to.

Naming and environment variables

Connecting a service adds environment variables to your application. Which variables you get depends on the service and on your application type; each service documents its own set under Services.

The connection name decides whether those variables are prefixed. An unnamed connection is called default and contributes nothing to the name:

connections:
  - service: db          # DATABASE_URL
  - service: reporting
    name: reporting      # DATABASE_REPORTING_URL

The name is folded in after the prefix and before the rest of the variable, upper-cased. So on Laravel, where a database connection is DB_*, a connection named reporting gives DB_REPORTING_HOST rather than DB_HOST.

Avoid naming a connection after the service it points at. A connection named db to a database produces DB_DB_HOST, which reads badly. Leave it unnamed when you only have one connection of a kind, and name the extras after what they are for.

Templating connection values

Anywhere you can set an environment variable, you can reference a connection's own values instead of hardcoding them. The syntax is {{ path.to.value }}.

variables:
  DATABASE_URL:
    value: "mariadb://{{ svc.db.conn.default.username }}:{{ svc.db.conn.default.password }}@{{ svc.db.conn.default.hostname }}:{{ svc.db.conn.default.port }}/{{ svc.db.conn.default.database }}"

Service values live under svc.<service>.conn.<connection>. An unnamed connection is default.

Application values

Value Description
cap.application The name of the application.
cap.environment The environment, such as production.
cap.instance The instance name.
cap.cluster The cluster, such as production or shared.
cap.hostname The application's primary hostname.

Internal address

Every group with internal enabled has a private address of its own, named after the group; see HTTP. Replace <group> with the group's name, or default for the servers configured directly under http. For a group where internal is disabled these values are left as you wrote them, since there is no private address to point at.

Value Description
http.groups.<group>.internal.scheme The scheme to reach that group on, http.
http.groups.<group>.internal.host The private address of that group.
http.groups.<group>.internal.port The port it listens on.
http.groups.<group>.internal.url Scheme and address combined, ready to use as a base URL.

MariaDB and PostgreSQL

Value Description
hostname Where to reach the database.
port The port it listens on.
username The user created for this connection.
password That user's password.
database The database name.
version The version the service runs.

CockroachDB

CockroachDB connects without a password, so it exposes no credentials.

Value Description
hostname Where to reach the database.
port The port it listens on.
database The database name.
version The version the service runs.

RabbitMQ

Value Description
hostname Where to reach the broker.
port The port it listens on.
username The user created for this connection.
password That user's password.
vhost The vhost for this connection.
version The version the service runs.

Dragonfly

Value Description
hostname Where to reach the cache.
port The port it listens on.
database The database index.
version The version the service runs.

OpenSearch

Value Description
hostname Where to reach OpenSearch.
port The port it listens on.
username The user created for this connection.
password That user's password.
indexPrefix Prefix your indexes with this.
version The version the service runs.

Mercure

Value Description
url Where your application publishes.
publicUrl Where browsers subscribe.
hostname The hub's hostname.
port The port it listens on.
publisherKey Key to sign publisher tokens with.
subscriberKey Key to sign subscriber tokens with.
version The version the service runs.

password, publisherKey and subscriberKey are secrets. They are never written into your configuration: CAP substitutes a reference that resolves when your application starts, so the value is only usable from within a running application.

Two things follow from that. The value cannot be read anywhere outside your running application, so it is no use in a build step. And concatenating it still works, because the reference is expanded in place:

variables:
  AUTHORIZATION: "Bearer {{ svc.hub.conn.default.publisherKey }}"
Back to top