Platform.sh is now Upsun. Click here to learn more
Upsun User Documentation

relationships

Try Upsun for 15 days
After that, enjoy the same game-changing Upsun features for less with the First Project Incentive!¹ A monthly $19 perk!
Activate your 15-day trial
¹Terms and conditions apply

A dictionary of relationships that defines the connections to other services and apps.

Optional in single-runtime and composable images.

To allow containers in your project to communicate with one another, you need to define relationships between them. You can define a relationship between an app and a service, or between two apps.

The quickest way to define a relationship between your app and a service is to use the service’s default endpoint.
However, some services allow you to define multiple databases, cores, and/or permissions. In these cases, you can’t rely on default endpoints. Instead, you can explicitly define multiple endpoints when setting up your relationships.

To define a relationship between your app and a service:

Use the following configuration:

.upsun/config.yaml 
applications:
  APP_NAME:
    # ...
    relationships:
      SERVICE_NAME:

The SERVICE_NAME is the name of the service as defined in its configuration. It is used as the relationship name, and associated with a null value. This instructs Upsun to use the service’s default endpoint to connect your app to the service.

For example, if you define the following configuration:

.upsun/config.yaml 
applications:
  APP_NAME:
    # ...
    relationships:
      mariadb:

Upsun looks for a service named mariadb in your .upsun/config.yaml file, and connects your app to it through the service’s default endpoint.

For reference, the equivalent configuration using explicit endpoints would be the following:

.upsun/config.yaml 
applications:
  APP_NAME:
    # ...
    relationships:
      mariadb:
        service: mariadb
        endpoint: mysql

You can define any number of relationships in this way:

.upsun/config.yaml 
applications:
  APP_NAME:
    # ...
    relationships:
      mariadb:
      redis:
      elasticsearch:

Use the following configuration:

.upsun/config.yaml 
applications:
  APP_NAME:
    # ...
    relationships:
      RELATIONSHIP_NAME:
        service: SERVICE_NAME
        endpoint: ENDPOINT_NAME
  • RELATIONSHIP_NAME is the name you want to give to the relationship.
  • SERVICE_NAME is the name of the service as defined in its configuration.
  • ENDPOINT_NAME is the endpoint your app will use to connect to the service (refer to the service reference to know which value to use).

For example, to define a relationship named database that connects your app to a service called mariadb through the db1 endpoint, use the following configuration:

.upsun/config.yaml 
applications:
  APP_NAME:
    # ...
    relationships:
      database: # The name of the relationship.
        service: mariadb
        endpoint: db1

For more information on how to handle multiple databases, multiple cores, and/or different permissions with services that support such features, see each service’s dedicated page:

You can add as many relationships as you want to your app configuration, using both default and explicit endpoints according to your needs:

.upsun/config.yaml 
applications:
  APP_NAME:
    # ...
    relationships:
      database1:
        service: mariadb
        endpoint: admin
      database2:
        service: mariadb
        endpoint: legacy
      cache:
        service: redis
      search:
        service: elasticsearch