MariaDB Cloud SQL

This provisions a functionally equivalent MariaDB database in an existing Google Cloud SQL MySQL instance.

The instance must be reachable from Humanitec IPs and be configured to accept connections via the Google Cloud SQL Auth Proxy. Any workload that has a dependency on this mariadb resource will automatically have the Google Cloud SQL Auth Proxy installed as a sidecar container.

Property Description
Resource type mariadb
Account type gcp



Name Type Description
instance string The fully qualified instance ID of the Cloud SQL instance. Must be of the form <project-id>:<region>:<id>.
copy_from_name string [Optional] If provided, specifies the database in the same instance to copy data from.


Name Type Description
dbcredentials object An object holding username and password properties for the MariaDB superuser.
account object [Optional] Only required if not using a Google Cloud Platform Cloud Account configured in the Platform Orchestrator.
An object holding the properties of service account credentials, as generated by the gcloud iam service-accounts keys create command.


Google Cloud SQL does not natively support MariaDB.

This Driver is designed to be functionally equivalent to the MySQL Cloud SQL but with MariaDB semantics.

It’s intended for scenarios where the application requires a resource of type mariadb but can utilize Cloud SQL MySQL to provide that. Essentially, to the application, it appears to be a MariaDB connection, but in the backend, it’s a MySQL connection.

Service Account for Cloud SQL Auth Proxy

Before the Driver can be used, a GCP Service Account must be added as a Humanitec Cloud Account.

This GCP Service Account requires at least the Cloud SQL Client (roles/cloudsql.client) role.

The ID of this account must be used for the Driver Account that will be used both by the Driver and by the subsequent sidecar proxy that is installed. Alternatively, place the credentials in a secret store and provide a secret reference for the Driver Cloud Account.

Automatic population of database

MariaDB does not provide any standard way of duplicating databases. Instead, the suggested approach is to “dump and restore” a database using tools such as mariadb-dump/mysqldump.

This Driver emulates a dump and restore of the database: for example, it serially copies data from the source database to the target database. It therefore suffers from limitations of dumping and restoring a database. The main issue is that if the source database is being written to, there are no guarantees about the data integrity in the resulting database. Consider a source database with 2 tables A and B:

  1. Table A is copied to the target database.
  2. New data is then written to Table A and Table B in the source database.
  3. Table B is copied from the source database to the target database.

The target database will now have the updated to table B but not table A.

This capability should not be used for production databases or where data integrity must be guaranteed.


Set the following environment variables for the CLI and API commands:

Variable Example Description
HUMANITEC_TOKEN my-token The authentication token for accessing the Humanitec API.
HUMANITEC_ORG my-org-id The unique identifier for the organization in Humanitec.

Use the command below for the interface of your choice to create a fresh MySQL database in an instance example-project:europe-west-1:mysql-db using a Cloud Account pre-configured in Humanitec called example-gcp-account.

To use your own secret store for providing the Cloud Account credentials, omit the driver_account and provide a secret reference as shown here.

  1. Create a file defining the Resource Definition you want to create:
cat << EOF > dev-mariadb-cloudsql.yaml
kind: Definition
  id: dev-mariadb-cloudsql
  driver_type: humanitec/mariadb-cloudsql
  name: Dev MariaDB CloudSQL
  type: mariadb
  driver_account: example-gcp-account
        username: root
        password: 53cr3t-P455w0rd
      instance: example-project:europe-west-1:maria-db
      name: mariadb
  - env_type: development
  1. Use the humctl create command to create the Resource Definition in the Organization defined by your configured context:
humctl create -f dev-mariadb-cloudsql.yaml
rm dev-mariadb-cloudsql.yaml

curl${HUMANITEC_ORG}/resources/defs \
  -X POST \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-binary '
  "id": "dev-mariadb-cloudsql",
  "name": "Dev MariaDB CloudSQL",
  "type": "mariadb",
  "criteria": [
      "env_type": "development"
  "driver_account": "example-gcp-account",
  "driver_type": "humanitec/mariadb-cloudsql",
  "driver_inputs": {
    "values": {
      "instance": "example-project:europe-west-1:maria-db",
      "name": "mariadb"
    "secrets": {
      "dbcredentials": {
        "username": "root",
        "password": "53cr3t-P455w0rd"

Google CloudSQL uses a slightly different Humanitec Driver to other MariaDB providers, but this is transparent outside the resource definitions.


  • You must have a CloudSQL instance running.
  • You must have a Service Account with the Cloud SQL Client role.
  • You must create a key for this service account in JSON format. See Google’s account keys documentation for more information. The access key must use the GCP Console/gcloud format (i.e., the first example in the linked documentation).
  • You must have the CloudSQL Admin API enabled for your project.
  • You must have a user defined on the instance for Workloads to use when connecting to the database.

Add a GCP Account

To integrate a CloudSQL account you need to add a Cloud Account (if you haven’t already).

  1. From the Cloud Accounts screen, click Google Cloud Platform in the Add accounts section.
  2. In the modal dialog provide a unique name for the account in the Account name field.
  3. In the Service account access key(JSON) field paste the account key for the service account that you wish to use.
  4. Click Authorize.

Add a Resource Definition

  1. From the Resource Management screen, click Add resource definition.
  2. In the modal dialog click MariaDB.
  3. Next, select the mariadb-cloudsql Driver.
  4. Finally, provide the following information, then click Add MariaDB.
    1. In the ID field provide a unique ID for the resource.
    2. In the Credentials field select the Cloud Account associated with the database instance.
    3. In the User / Role and Password fields provide the credentials that Workloads should use when connecting to the database.
    4. In the field, enter the IP address or hostname that the instance is available on.
    5. In the values.port filed, enter the port on the instance that the database is available on.

Resource Matching

Now that the resource is defined you will need to add matching criteria.

  1. Click on the relevant row in the Resource Definition table.
  2. Then switch to the Matching Criteria tab.
  3. Click + Add new Criteria.
  4. Configure the matching rules as needed:
    • Environment Type: development.
  5. Click Save.