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 automatically injects the necessary environment variables into your application's container, allowing it to communicate with the specified service.

Connecting to a Deployed Service (service-connection)

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.

Property	Type	Description
service	string	The name of the service to connect to (must match a name in the services block).
name	string (Optional)	An alias for the connection. This is used to prefix environment variables and allows multiple connections to the same service type.
database	string (Optional)	For database services, connect to a specific, pre-existing database.
vhost	string (Optional)	For RabbitMQ services, connect to a specific, pre-existing virtual host (vhost).

Note

Defining database or vhost will also stop CAP from generating the resource. The database or vhost needs to be already defined by another connection or application.

Example

services:
  main-db:
    type: mariadb

  main-queue:
    type: rabbitmq

connections:
  - service: "main-db" # Connects to the main-db service

  - service: "main-queue"
    name: "queue"      # Defining the name for a connection modifies the environment variables that are generated

Connecting to a Shared Service (shared-connection)

This allows your application to connect to a shared service that has been provisioned at the project level.

Property	Type	Description
shared	string	The name of the shared service to connect to (must match a service defined in the project-level configuration).
name	string (Optional)	An alias for the connection.
database	string (Optional)	For database services, connect to a specific, pre-existing database within the shared service.
vhost	string (Optional)	For RabbitMQ services, connect to a specific, pre-existing virtual host (vhost) within the shared service.

Example

# Assumes 'project-db' is defined in the project-level configuration
connections:
  - shared: "project-db"

Connecting to an External Service (external-connection)

This allows your application to connect to a service hosted outside of CAP's environment, such as an existing database managed by a cloud provider.

Property	Type	Description
external	string	The type of external service (mysql, mariadb, postgresql, cockroachdb).
host	string	The hostname or IP address of the external service.
port	integer	The port number of the external service.
database	string	The name of the database to connect to.
username	string	The username for authentication.
password	object	The password for authentication, defined as a gitlabEnv object. See the YAML Schema Reference for details.
name	string (Optional)	An alias for the connection.
version	string (Optional)	The version of the external server. This is only applicable for symfony application types.

Example

connections:
  - external: "mysql"
    name: "billing_db"
    host: "external-db.example.com"
    port: 3306
    database: "billing"
    username: "billing_user"
    password:
      gitlab: "EXTERNAL_DB_PASSWORD" # References a secret in GitLab CI/CD variables

Connection Naming and Environment Variables

The name property is crucial when you have multiple connections, especially of the same type. For many application types, CAP inserts the name into the middle of the environment variable it creates. For example, a default database environment variable DB_HOST would become DB_MY_NAME_HOST if the connection name is MY_NAME. If the connection name is db, it would be DB_DB_HOST, which is redundant. Therefore, it is recommended to choose unique and descriptive names for your connections.

If you only have one connection of a given type (e.g., one database), you can often omit the name, and CAP will use a default name.

Note

Refer to the Application Types documentation to see how each type handles connection environment variables.