Add services

Platform.sh includes many services, so you don’t have to subscribe to external cache or search engine services. Because the services are included in your project, you can manage them through Git and they’re backed up together with the rest of your project.

Your project defines the services configuration in a file named .platform/services.yaml.

If you don’t need any services (such as for a static website), you don’t need to include this configuration. Read on to see how to add services.

Add a service

Adding a service is a two-step process.

1. Configure the service

All service configuration happens in the .platform/services.yaml file in your Git repository.

Configure your service in the following pattern:

# The name of the service container. Must be unique within a project.
SERVICE_NAME:
  type: <SERVICE_TYPE>:<VERSION>
  # Other options...

An example service configuration for two databases might look like this:

# The name of the service container. Must be unique within a project.
mariadb:
  type: mariadb:11.4
  disk: 2048
# The name of the service container. Must be unique within a project.
postgresql:
  type: postgresql:16
  disk: 1024

This YAML file is a dictionary defining all of the services you want to use. The top-level key is a custom service name (<SERVICE_NAME>: in the example, mariadb and postgresql), which you use to identify the service in step 2.

You can give it any name you want with lowercase alphanumeric characters, hyphens, and underscores.

Service options

The following table presents the keys you can define for each service:

Disk

You configure the disk size in MB. Your actual available disk space is slightly smaller with some space used for formatting and the filesystem journal. When checking available space, note whether it’s reported in MB or MiB.

You can decrease the size of an existing disk for a service. If you do so, be aware that:

• The downsize fails if there’s more data on the disk than the desired size.
• Backups from before the downsize can still be restored.

Size

Resources are distributed across all containers in a project from the total available from your plan size.

By default, Platform.sh allocates CPU and memory resources to each container automatically. Some services are optimized for high CPU load, some for high memory load. If your plan is sufficiently large for bigger containers, you can increase the size of your service container.

Note that service containers in preview environments are always set to size S.

2. Connect the service

Once you have configured a service, you need to create a relationship to connect it to an app. This is done in your app configuration for relationships.

The relationship follows this pattern:

name: myapp

# Other options...

# Relationships enable an app container's access to a service.
# The example below shows simplified configuration leveraging a default service (identified from the relationship name) and a default endpoint.
# See the Application reference for all options for defining relationships and endpoints.
relationships:
  <SERVICE_NAME>:

# Relationships enable access from this app to a given service.
# The example below shows configuration with an explicitly set service name and endpoint.
# See the Application reference for all options for defining relationships and endpoints.
# Note that legacy definition of the relationship is still supported.
# More information: https://docs.platform.sh/create-apps/app-reference/single-runtime-image.html#relationships
relationships:
  <RELATIONSHIP_NAME>:
    service: <SERVICE_NAME>
    endpoint: <ENDPOINT_NAME>

An example relationship to connect to the databases given in the example in step 1:

name: myapp
# Other options...

# Relationships enable an app container's access to a service.
relationships:
  mariadb:
  postgresql:

name: myapp
# Other options...

# Relationships enable access from this app to a given service.
# The example below shows configuration with explicitly set service names and endpoints.
# See the Application reference for all options for defining relationships and endpoints.
# Note that legacy definition of the relationship is still supported.
# More information: https://docs.platform.sh/create-apps/app-reference/single-runtime-image.html#relationships
relationships:
  mariadb:
    service: mariadb
    endpoint: mysql
  postgresql:
    service: postgresql
    endpoint: mysql

mariadb:
  type: mariadb:11.4
  disk: 2048
postgresql:
  type: postgresql:16
  disk: 1024

As with the service name, you can give the relationship any name you want with lowercase alphanumeric characters, hyphens, and underscores. It helps if the service name and relationship name are different, but it isn’t required.

Each service offers one or more endpoints for connections, depending on the service. An endpoint is a named set of credentials to give access to other apps and services in your project. If you don’t specify one in the service configuration, a default endpoint is created. The default endpoint varies by service, generally being its type (such as mysql or solr).

Available services

The following table presents the available service types and their versions. Add them to the type key of the service configuration in the format type:version.

Service versions

These services generally follow semantic versioning conventions. You can select the major version, but the latest compatible minor is applied automatically and can’t be overridden. Patch versions are applied periodically for bug fixes and the like. When you deploy your app, you always get the latest available patches.

Service timezones

All services have their system timezone set to UTC by default. For some services, you can change the timezone for the running service (this doesn’t affect the container itself and so logs are still in UTC).

• MySQL
• PostgreSQL

Connect to a service

For security reasons, you can’t access services directly through HTTP. You can connect through your app or by opening an SSH tunnel to access the service directly.

platform relationships

mariadb:
  -
    username: user
    scheme: mysql
    service: mariadb
    fragment: null
    ip: 198.51.100.37
    hostname: abcdefghijklm1234567890123.mariadb.service._.eu.platformsh.site
    public: false
    cluster: abcdefgh1234567-main-abcd123
    host: mariadb.internal
    rel: mysql
    query:
      is_master: true
    path: main
    password: ''
    type: 'mariadb:10.6'
    port: 3306
    host_mapped: false
    url: 'mysql://user:@mariadb.internal:3306/main'

platform tunnel:single --relationship RELATIONSHIP_NAME

Upgrading services

Platform.sh provides a large number of managed service versions. As new versions are made available, you will inevitably upgrade infrastructure to a more recent (or latest version).

When you do so, we would recommend:

1. Use preview environments. Leverage preview (non-production environments) to perform the upgrade, then merge the upgrade into production (promotion). This will give you an opportunity to test inherited production data in a safe, isolated environment first.
2. Upgrade progressively. For one reason or another, you may be more than a single version behind the upgrade you are trying to perform. To avoid data loss issues caused by large differences in versions, upgrade one version at a time.