# `relationships`


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

Optional in [single-runtime](https://fixed.docs.upsun.com/create-apps/app-reference/single-runtime-image.md#top-level-properties) and [composable](https://fixed.docs.upsun.com/create-apps/app-reference/composable-image.md#top-level-properties) 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](https://fixed.docs.upsun.com/create-apps/multi-app/relationships.md).

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.

**Note**: 

App containers don’t have a default endpoint like services.
To connect your app to another app in your project,
you need to explicitly define the ``http`` endpoint as the endpoint to connect both apps. 
For more information, see how to [define relationships between your apps](https://fixed.docs.upsun.com/create-apps/multi-app/relationships.md).

**Availability**: 

New syntax (default and explicit endpoints) described below is supported by most, but not all, image types
(``Relationship 'SERVICE_NAME' of application 'myapp' ... targets a service without a valid default endpoint configuration.``).
This syntax is currently being rolled out for all images.
If you encounter this error, use the “legacy” Upsun Fixed configuration noted at the bottom of this section.

To define a relationship between your app and a service:

```yaml {}
relationships:
  <SERVICE_NAME>:
```

The ``SERVICE_NAME`` is the name of the service as defined in its [configuration](https://fixed.docs.upsun.com/add-services.md).
It is used as the relationship name, and associated with a ``null`` value.
This instructs Upsun Fixed to use the service’s default endpoint to connect your app to the service.
For example, if you define the following configuration:

    .platform.app.yaml

```yaml {}
relationships:
  mariadb:
```

Upsun Fixed looks for a service named ``mariadb`` in your ``.platform/services.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:

    .platform.app.yaml

```yaml {}
relationships:
  mariadb:
    service: mariadb
    endpoint: mysql
```

You can define any number of relationships in this way:

    .platform.app.yaml

```yaml {}
relationships:
  mariadb:
  redis:
  elasticsearch:
```

**Tip**: 

An even quicker way to define many relationships is to use the following single-line configuration:

    .platform.app.yaml

```yaml {}
relationships: {<SERVICE_NAME_A>, <SERVICE_NAME_B>, <SERVICE_NAME_C>}
```

where

    .platform/services.yaml

```yaml {}
<SERVICE_NAME_A>:
  type: mariadb:11.8
  disk: 256
<SERVICE_NAME_B>:
  type: redis:8.0
  disk: 256
<SERVICE_NAME_C>:
  type: elasticsearch:8.5
  disk: 256
```

Use the following configuration:

    .platform.app.yaml

```yaml {}
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](https://fixed.docs.upsun.com/add-services.md).
 - ``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:

    .platform.app.yaml

```yaml {}
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:

 - [MariaDB/MySQL](https://fixed.docs.upsun.com/add-services/mysql.md#multiple-databases) (multiple databases and permissions)
 - [PostgreSQL](https://fixed.docs.upsun.com/add-services/postgresql.md#multiple-databases) (multiple databases and permissions)
 - [Redis](https://fixed.docs.upsun.com/add-services/redis.md#multiple-databases) (multiple databases)
 - [Solr](https://fixed.docs.upsun.com/add-services/solr.md#solr-6-and-later) (multiple cores)
 - [Vault KMS](https://fixed.docs.upsun.com/add-services/vault.md#multiple-endpoints-configuration) (multiple permissions)

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

    .platform.app.yaml

```yaml {}
relationships:
  database1:
    service: mariadb
    endpoint: admin
  database2:
    service: mariadb
    endpoint: legacy
  cache:
    service: redis
  search:
    service: elasticsearch
```

**Legacy**: 

The following legacy syntax for specifying relationships is still supported by Upsun Fixed:

    .platform.app.yaml

```yaml {}
relationships:
  <RELATIONSHIP_NAME>: "<SERVICE_NAME>:<ENDPOINT_NAME>"
```

For example:

    .platform.app.yaml

```yaml {}
relationships:
  database: "mariadb:mysql"
```

Feel free to use this until the default and explicit endpoint syntax is supported on all images.


