This provisions a new PostgreSQL database in an existing PostgreSQL instance. The instance must be reachable from Humanitec IPs.

Property Description
Resource type postgres
Account type None



Name Type Description
host string The IP Address or hostname that the instance is available on.
port integer The port the instance is listening on.
name string [Optional] The name of the maintenance database to connect to. Defaults to postgres.
append_host_to_user boolean [Optional] Azure Databases for Postgres and MySQL require usernames to have @servername appended to them. Set this to true for the Driver to append this automatically. (See: Azure Database connection strings)
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.


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:


Humanitec has integrated support for both hosted PostgreSQL solutions (like Google CloudSQL, Aiven, Amazon RDS, etc), and self-managed deployments.

To create a fresh PostgreSQL database in an instance available at

curl${HUMANITEC_ORG}/resources/defs \
  -X POST \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-binary '
  "id": "dev-postgres",
  "name": "Dev PostgreSQL",
  "type": "postgres",
  "criteria": [
      "env_type": "development"
  "driver_type": "humanitec/postgres",
  "driver_inputs": {
    "values": {
      "host": "",
      "port": 5432,
      "name": "postgres"
    "secrets": {
      "dbcredentials": {
        "username": "postgres",
        "password": "53cr3t-P455w0rd"

This will create a fresh database called postgres on the instance at using the superuser credentials provided.

Most PostgresSQL implementations use a single shared Driver. For Google CloudSQL implementations, see the Google CloudSQL Driver.


  • You must have a database instance/server running.
  • If you are using a hosted Postgres it is recommended provide a management service account with Database CRUD permissions. You will need to add this account via the Cloud Accounts screen.
  • You must have a user defined on the instance for Workloads to use when connecting to the database.

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 progress.
    1. In the ID field provide a unique ID for the resource.
    2. (If you are using a management account) 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. In the User / Role and Password fields provide the credentials that Workloads should use when connecting to the database.
    5. In the Hostname or IP field provide the Hostname or IP address that the Workloads can access the database on.
    6. In the Port field provide the port number that the database is running 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.