This provisions a new MySQL 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 mysql resource will automatically have the Google Cloud SQL Auth Proxy installed as a sidecar container.

Property Description
Resource type mysql
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 PostgreSQL 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.


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

MySQL does not provide any standard way of duplicating databases. Instead, the suggested approach is to “dump and restore” a database using tools such as 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-mysql-cloudsql.yaml
kind: Definition
  id: dev-mysql-cloudsql
  name: Dev MySQL CloudSQL
  type: mysql
  driver_type: humanitec/mysql-cloudsql
  driver_account: example-gcp-account
        password: 53cr3t-P455w0rd
        username: root
      instance: example-project:europe-west-1:mysql-db
  - 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-mysql-cloudsql.yaml
rm dev-mysql-cloudsql.yaml

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

Google CloudSQL uses a slightly different Humanitec Driver to other MySQL 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 MySQL.
  3. Next, select the mysql-cloudsql Driver.
  4. Finally, provide the following information, then click Add Postgress.
    1. In the ID field provide a unique ID for the resource.
    2. In the Credentials field select the Cloud Account you created earlier.
    3. In the Fully qualified CloudSQL instance name provide the instance name in the format <project-id>:<region>:<id>.
    4. If the maintenance database name is not mysql provide that in the Database name field.
    5. In the User / Role and Password fields provide the credentials that Workloads should use when connecting to the database.

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.
  5. Click Save