PostgreSQL Cloud SQL

This provisions a new PostgreSQL database in an existing Google Cloud SQL Postgres 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 postgres resource will automatically have the Google Cloud SQL Auth Proxy installed as a sidecar container.

Property Description
Resource type postgres
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>.
name string [Optional] The name of the maintenance database to connect to. Defaults to postgres.
template_name string [Optional] If provided, the Driver will use this database name as a template. See CREATE DATABASE.


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

PostgreSQL supports creating databases based on templates. (See CREATE DATABASE) This functionality can be used to effectively pre-populate a database as it is provisioned.

It is important to be familiar with the constraints of template databases in PostgreSQL. The documentation states:


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 PostgreSQL database in an instance example-project:europe-west-1:postgres-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-postgres-cloudsql.yaml
kind: Definition
  id: dev-postgres-cloudsql
  driver_type: humanitec/postgres-cloudsql
  name: Dev PostgreSQL CloudSQL
  type: postgres
  driver_account: example-gcp-account
        username: root
        password: 53cr3t-P455w0rd
      instance: example-project:europe-west-1:postgres-db
      name: postgres
  - 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-postgres-cloudsql.yaml
rm dev-postgres-cloudsql.yaml

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

Google CloudSQL uses a slightly different Humanitec Driver to other Postgres 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 Postgres.
  3. Next, select the postgres-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 postgres 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:
    • Environment Type: development.
  5. Click Save.