---
name: cloud-databases-terra-postgres-tutorial
title: Provision a Databases for PostgreSQL instance with Terraform
description: In this tutorial, you learn how to use Terraform to provision a Databases for PostgreSQL instance.
last-updated: 2026-03-10
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/cloud-databases?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Provision a Databases for PostgreSQL instance with Terraform
{: #tutorial-provision-postgres-tf}
{: toc-content-type="tutorial"}
{: toc-completion-time="1h"}

In this tutorial, you learn how to use Terraform to provision a Databases for PostgreSQL instance.
{: shortdesc}

## Overview of the available tools
{: #tutorial-provision-postgres-tf-prereqs}

Before beginning the process of provisioning a database with Terraform, [you need to have an IBM Cloud account.](https://cloud.ibm.com/registration)

In this tutorial, you provision your database by using Terraform, which enables you to safely and predictably create, change, and improve infrastructure. It is an open source tool that codifies APIs into declarative configuration files that can be shared among team members, which are treated as code, edited, reviewed, and versioned. It is infrastructure as code. You write down what your infrastructure should look like and Terraform will create, update, and remove cloud resources as needed. For more information, see [Understand the basics of Terraform.](https://www.terraform.io/intro){: external}

To support a multi-cloud approach, Terraform works with providers. A provider is responsible for understanding API interactions and exposing resources. IBM Cloud® has its provider for Terraform, enabling users of IBM Cloud® to manage resources with Terraform. Although Terraform is categorized as infrastructure as code, it is not limited to Infrastructure-As-A-Service resources. For more information, see [ibm_database](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/database).

## Install Terraform
{: #tutorial-provision-postgres-install-cli}
{: step}

1. Follow the steps at [Install Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli?in=terraform/docker-get-started){: external} to install Terraform.

## Configure the IBM Cloud® Provider plug-in
{: #tutorial-provision-postgres-config-provider}
{: step}

1. [Create or retrieve an IBM Cloud® API key.](https://cloud.ibm.com/docs/account?topic=account-userapikey&format=markdown#create_user_key) The API key is used to authenticate with the IBM Cloud® platform and to determine your permissions for IBM Cloud® services.

1. Create a Terraform on IBM Cloud Databases project directory. The directory holds all your configuration files that you create as part of this tutorial. The directory in this tutorial is named `tf-postgres`, but you can use any name for the directory.

   ```terraform
   mkdir tf-postgres && cd tf-postgres
   ```
   {: codeblock}

1. In your project directory, create a variable definition file that is named `terraform.tfvars` and specify the IBM Cloud API key that you retrieved. In addition, you specify the region where you want your IBM Cloud resources to be created. If no region is specified, the IBM Cloud® Provider plug-in automatically creates your resources in the us-south region. Variables that are defined in the `terraform.tfvars` file are automatically loaded by Terraform when the IBM Cloud Provider plug-in is initialized and you can reference them in every Terraform configuration file that you use.

   Because the variable definitions file contains confidential information, do not push this file to a version control system. This file is meant to be on your local system only.{: .important}

   **Example of `terraform.tfvars` file**

   ```terraform
     ibmcloud_api_key = "<IBMCLOUD_API_KEY>"
     region = "us-east"
   ```
   {: codeblock}

   The `us-east` region is provided as an example, not a requirement. Use the region that works best for your instance deployment.{: .note}

1. Create a provider configuration file that is named `provider.tf`. Use this file to configure the IBM Cloud Provider plug-in with the IBM Cloud API key from your `terraform.tfvars` file. The plug-in uses this key to access IBM Cloud and to work with your IBM Cloud service. To access a variable value from the `terraform.tfvars` file, you must first declare the variable in the `provider.tf` file and then reference the variable by using the `var.<variable_name>` syntax.

    **Example `provider.tf` file**

    ```terraform
    terraform {
      required_providers {
        ibm = {
          source  = "IBM-Cloud/ibm"
          version = ">= 1.28.0"
        }
      }
    }

    variable "ibmcloud_api_key" {}
    variable "region" {}

    provider "ibm" {
      ibmcloud_api_key = var.ibmcloud_api_key
      region           = var.region
    }
    ```
    {: codeblock}

## Provision a Databases for PostgreSQL instance
{: #tutorial-provision-postgres-provision-instance}
{: step}

Create a Terraform configuration file that is named `postgres.tf`.

   **Example of `postgres.tf` file**

    ```terraform
    resource "ibm_resource_group" "resource_group" {
      name = "tutorialRG"
    }

    resource "ibm_database" "postgresql_db" {
      resource_group_id = ibm_resource_group.resource_group.id
      name              = "terraform_postgres"
      service           = "databases-for-postgresql"
      plan              = "standard"
      location          = "us-east"
      service_endpoints = "public"
      adminpassword     = "password123456789"

      group {
        group_id = "member"
        host_flavor {
          id = "multitenant"
        }
        cpu {
          allocation_count = 2
        }
        memory {
          allocation_mb = 4096
        }
        disk {
          allocation_mb = 5120
        }
      }
    }

    data "ibm_database_connection" "icd_conn" {
      deployment_id = ibm_database.postgresql_db.id
      user_type     = "database"
      user_id       = "admin"
      endpoint_type = "public"
    }

    output "Postgresql" {
      value = data.ibm_database_connection.icd_conn
    }
    ```
    {: codeblock}

   - **resource_group_id** - The Resource Group value you declare.
   - **name** - The service name can be any string and is the name that is used on the web and in the CLI to identify the new deployment.
   - **service** - For Databases for PostgreSQL, the service ID is `databases-for-postgresql`. Choose the correct Service ID for your deployment.
   - **plan** - This tutorial uses a Standard plan. For more information, see [IBM Cloud&reg; Pricing](https://www.ibm.com/cloud/pricing).
   - **location** - Choose a suitable region for your deployment instance.
   - **service_endpoint** - The service endpoints of your deployment. `public` is used in the tutorial, however it is recommended that only `private` endpoints are used in production.
   - **adminpassword** - The Databases for PostgreSQL service is provisioned with an admin user, so you can manage PostgreSQL by using its command-line tool, `psql`. For more information, see [Setting the Admin password](https://cloud.ibm.com/docs/databases-for-postgresql?topic=databases-for-postgresql-user-management&interface=ui&format=markdown#user-management-set-admin-password-ui).
   - **group** - Scaling groups represent the various resources that are allocated to a deployment. To see an example for configuring and deploying a database that uses `group` attributes, see [Sample database instance by using group attributes.](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/database#sample-database-instance-by-using-group-attributes){: external}
   - **group values** - Memory, disk, and CPU values are all based on minimum requirements for provisioning a Databases for PostgreSQL shared compute instance.
   - **output** - When the terraform process finished the connection information for the new database will be shown in the terminal.

Alternatively, you can use [Terraform IBM Modules (TIM) for Databases for PostgreSQL](https://registry.terraform.io/modules/terraform-ibm-modules/icd-postgresql/ibm/latest){: external}, which is the recommended approach for production environments. Unlike the raw resource, this module provides the following capabilities:

- Comprehensive documentation with README files and examples
- Multiple deployment scenarios using different examples
- Controlled versioning for safe updates and easier dependency management
- Enterprise-ready configurations that are secure, scalable, and compliant

To create a Terraform configuration file that is named `postgres.tf`:

### Example of `postgres.tf` file
{: #tutorial-provision-postgres-file}

```terraform
resource "ibm_resource_group" "resource_group" {
      name = "Default"
}

module "postgresql_db" {
  source            = "terraform-ibm-modules/icd-postgresql/ibm"
  version           = "latest" # Replace "latest" with a release version to lock into a specific release
  resource_group_id = ibm_resource_group.resource_group.id
  name              = "my-instance"
  region            = "us-south"
}
```
{: codeblock}

## Test your configuration
{: #tutorial-provision-postgres-test}
{: step}

Now that you configured the IBM Cloud&reg; Provider plug-in for your resource, you can use Terraform on IBM Cloud&reg; to initialize, run, plan, and apply commands to provision the resource. You need the following commands:

| Command Description | Command |
| -------------- | -------------- |
| [`terraform init`](https://www.terraform.io/cli/commands/init){: external} | The `terraform init` command is used to initialize a working directory containing Terraform configuration files. |
| [`terraform fmt`](https://www.terraform.io/cli/commands/fmt){: external} | The `terraform fmt` command is used to rewrite Terraform configuration files to a canonical format and style. |
| [`terraform validate`](https://www.terraform.io/cli/commands/validate){: external} | The `terraform validate` command validates the configuration files in a directory  |
| [`terraform apply`](https://www.terraform.io/cli/commands/apply){: external} | The `terraform apply` command runs the actions that are proposed in a Terraform plan. |
{: caption="Terrarform provisioning commands" caption-side="bottom"}

 For more information, see [Provisioning IBM Cloud&reg; resources](https://cloud.ibm.com/docs/ibm-cloud-provider-for-terraform?topic=ibm-cloud-provider-for-terraform-manage_resources&format=markdown#provision_resources).

 To view sample Terraform templates with the complete Terraform configuration files to test, refer to [Sample templates](https://cloud.ibm.com/docs/ibm-cloud-provider-for-terraform?topic=ibm-cloud-provider-for-terraform-provider-template&format=markdown#sample-templates).

For an overview of the Terraform resources and data sources that you can use, see the [Index of Terraform on IBM Cloud&reg; resources and data sources](https://cloud.ibm.com/docs/ibm-cloud-provider-for-terraform?topic=ibm-cloud-provider-for-terraform-resources-datasource-list&format=markdown).