Explain that if you allow access to multiple DBs in a single endpoint, only the default is exposed in RELATIONSHIPS

Where on docs.platform.sh should be changed?

https://docs.platform.sh/add-services/mysql.html#multiple-databases

What exactly should be updated?

In a mariadb or postegreSQL services, users can define multiple schemas. In a defined endpoint, that endpoint can have access to one or more of those schemas. Example:

db:
    type: mariadb:10.6
    disk: 2048
    configuration:
      schemas:
        - main
        - canyouseeme
      endpoints:
        mymysql:
          default_schema: main
          privileges:
            main: admin
            canyouseeme: admin

If you then create a relationship to the mymysql endpoint in the app container:

relationships:
    mydatabase: "db:mymysql"

In the exposed PLATFORM_RELATIONSHIPS information, only the default_schema (as path) will be exposed:

  "database": [
    {
      "username": "mymysql",
      "fragment": null,
      "ip": "169.254.254.139",
      "cluster": "xxl7bdoxp5nb4-main-bvxea6i",
      "host": "database.internal",
      "path": "main",
      "query": {
        "is_master": true
      },
      "password": "XXXXXXXXXXXXXXXXXXXXXXX",
      "port": 3306,
      "host_mapped": false,
      "service": "db",
      "hostname": "khiouy6nl7ytgnmxm6zfxr7xfm.db.service._.eu-3.platformsh.site",
      "epoch": 0,
      "instance_ips": [
        "247.120.32.58"
      ],
      "rel": "mymysql",
      "scheme": "mysql",
      "type": "mariadb:10.6",
      "public": false
    }
  ]

We need to add a note or a warning that the relationship will not expose any information about any other schemas the endpoint's user has access to beyond the default_schema

Additional context

The PostgreSQL documentation has this section:

endpoints: This is a nested YAML object defining different credentials. Each endpoint may have access to one or more schemas (databases), and may have different levels of permission for each. The valid permission levels are:

We might consider adding this explanation to the Mariadb docs as well, and then adding the note that even though an endpoint's user may have access to more than one schema, only the default_schema will be displayed in PLATFORM_RELATIONSHIPS

Adding more. This section https://docs.platform.sh/add-services/mysql.html#define-permissions

default_schema - Which of the defined schemas to default to. If not specified, the path property of the relationship is null and so tools such as the Platform.sh CLI can’t access the relationship.

If an endpoint only has permissions to a single schema, then default_schema is not required and will default to the single schema. If the endpoint has permissions to more than one schema and default_schema is not included, the system will default to none. The cli can still access the relationship and will prompt the user for the schema to use, or if in non-interactive mode, will default to none.

platformsh / platformsh-docs