Creating instances

This page describes how to create a Cloud SQL for a PostgreSQL instance.

For detailed information about all instance settings, see Instance Settings.

After creating a Cloud SQL instance, you add databases to it by creating or importing them.

Before you begin

  1. Sign in to your Google Account.

    If you don't already have one, sign up for a new account.

  2. In the Cloud Console, on the project selector page, select or create a Cloud project.

    Go to the project selector page

  3. Make sure that billing is enabled for your Google Cloud project. Learn how to confirm billing is enabled for your project.

  4. Install and initialize the Cloud SDK.
  5. Make sure you have the Cloud SQL Admin and Compute Viewer roles on your user account.

    Go to the IAM page

    Learn more about roles and permissions.

Creating a PostgreSQL instance

To create a PostgreSQL instance:

Console

  1. Go to the Cloud SQL Instances page in the Google Cloud Console.

    Go to the Cloud SQL Instances page

  2. Click Create instance.
  3. Select PostgreSQL and click Next.
  4. Enter a name.

    Do not include sensitive or personally identifiable information in your instance name; it is externally visible.

    You do not need to include the project ID in the instance name. This is done automatically where appropriate (for example, in the log files).

  5. Enter a password for the postgres user.
  6. Under Location, select the region and zone for your instance.

    Place your instance in the same region as the resources that access it. The region you select can't be modified in the future. In most cases, you don't need to specify a zone.

  7. Under Configuration options, update settings for your instance:
    Setting Notes
    Database version
    Database version PostgreSQL 12 (default), PostgreSQL 11, PostgreSQL 10, and PostgreSQL 9.6
    Connectivity
    Private IP Adds a private IP address for your instance. To enable connecting to the instance, additional configuration is required. .
    Public IP Adds a public IP address for your instance. To enable connecting to the instance, additional configuration is required.
    Machine type and storage
    Cores The number of vCPUs for your instance. Learn more.
    Memory The amount of memory for your instance, in GBs. Learn more.
    Storage type Determines whether your instance uses SSD or HDD storage. Learn more.
    Storage capacity The amount of storage provisioned for the instance. Learn more.
    Automatic storage increase Determines whether Cloud SQL automatically provides more storage for your instance when free space runs low. Learn more.
    High availability If you need your instance to be configured for high availability, you must select the High availability (regional) checkbox. Learn more.
    Automatic backups The window of time when you would like backups to start. Learn more.
    Point-in-time recovery Enables point-in-time recovery and write-ahead logging. Learn more.
    Add database flags
    Database flags You can use database flags to control settings and parameters for your instance. Learn more.
    Maintenance schedule
    Maintenance window Determines a one-hour window when Cloud SQL can perform disruptive maintenance on your instance. If you do not set the window, then disruptive maintenance can be done at any time. Learn more.
    Maintenance timing Your preferred timing for instance updates, relative to other instances in the same project. Learn more.

    Learn more about instance settings.

  8. Click Create.

gcloud

For information about installing and getting started with the gcloud command-line tool, see Installing Cloud SDK. For information about starting Cloud Shell, see the Cloud Shell documentation.

  1. Create the instance: 
    gcloud sql instances create [INSTANCE_NAME] --database-version=POSTGRES_12 \
       --cpu=[NUMBER_CPUS] --memory=[MEMORY_SIZE] \
       --region=[REGION] | --gce-zone=[GCE_ZONE] | --zone=[ZONE]

or, alternatively:

gcloud sql instances create instance --tier=[API_TIER_STRING] --region=[REGION]

    The values for [API_TIER_STRING] are custom machine types, defined here. These names include the vCPU and Memory values. For example, the db-custom-2-7680 machine type contains 2 vCPUs and 7680 Memory (MBs).

    There are restrictions on the values for vCPUs and memory size:

    • vCPUs must be either 1 or an even number between 2 and 96.
    • Memory must be:
      • 0.9 to 6.5 GB per vCPU
      • A multiple of 256 MB
      • At least 3.75 GB (3840 MB)

    For example, the following string creates an instance with two vCPUs and 7,680 MB of memory: 

     gcloud sql instances create myinstance --database-version=POSTGRES_12 --cpu=2 \
        --memory=7680MB --region="us-central"

    For some sample values, see Sample machine types.

    You can also create a shared-core instance by using --tier db-f1-micro or --tier db-g1-small and dropping the --cpu and --memory parameters.

    The default value for [REGION] is us-central.

    Do not include sensitive or personally identifiable information in your instance name; it is externally visible.
    You do not need to include the project ID in the instance name. This is done automatically where appropriate (for example, in the log files).

    You can add more parameters to determine other instance settings:

    Setting Parameter Notes
    Required parameters
    Database version --database-version POSTGRES_12 (default), POSTGRES_11, POSTGRES_10, or POSTGRES_9_6
    Region --region See valid values.
    Connectivity
    Private IP --network Specifies the name of the VPC network you want to use for this instance. Private services access must already be configured for the network. Available only for the beta command (gcloud beta sql instances create). Learn more.
    Public IP --authorized-networks For public IP connections, only connections from authorized networks can connect to your instance. Learn more.
    Machine type and storage
    Machine type --tier Used to specify a shared-core instance (db-f1-micro or db-g1-small). You cannot specify the --cpu or --memory parameters if you use this parameter.
    Storage type --storage-type Determines whether your instance uses SSD or HDD storage. Learn more.
    Storage capacity --storage-size The amount of storage provisioned for the instance, in GB. Learn more.
    Automatic storage increase --storage-auto-increase Determines whether Cloud SQL automatically provides more storage for your instance when free space runs low. Learn more.
    Automatic storage increase limit --storage-auto-increase-limit Determines how large Cloud SQL can automatically grow storage. Available only for the beta command (gcloud beta sql instances create). Learn more.
    Automatic backups and high availability
    High availability --availability-type For a highly-available instance, set to REGIONAL. Learn more.
    Automatic backups --backup-start-time The window of time when you would like backups to start. Learn more.
    Point-in-time recovery --enable-point-in-time recovery Enables point-in-time recovery and write-ahead logging. Learn more.
    Add database flags
    Database flags --database-flags You can use database flags to control settings and parameters for your instance. Learn more about database flags.
    Maintenance schedule
    Maintenance window --maintenance-window-day,
    --maintenance-window-hour    		 Determines a one-hour window when Cloud SQL can perform disruptive maintenance on your instance. If you do not set the window, then disruptive maintenance can be done at any time. Learn more.
    Maintenance timing --maintenance-release-channel Your preferred timing for instance updates, relative to other instances in the same project. Use preview for earlier updates, and production for later updates. Learn more.
  2. Note the automatically assigned IP address.

    If you are not using the Cloud SQL Proxy, you will use this address as the host address that your applications or tools use to connect to the instance.

  3. Set the password for the postgres user: 
    gcloud sql users set-password postgres --instance=[INSTANCE_NAME] \
       --password=[PASSWORD]

REST

Create the instance

This example creates an instance with backups and binary logging enabled. These settings are optional. For a complete list of parameters for this call, see the Instances:insert page. For information about instance settings, including valid values for region and machine type, see Instance Settings.

Do not include sensitive or personally identifiable information in your instance ID; it is externally visible.
You do not need to include the project ID in the instance name. This is done automatically where appropriate (for example, in the log files).

Before using any of the request data below, make the following replacements:

  • project-id: your project ID
  • instance-id: desired instance ID
  • region: desired region
  • machine-type: desired machine type

HTTP method and URL: 

POST https://www.googleapis.com/sql/v1beta4/projects/project-id/instances

Request JSON body: 

{
  "name": "instance-id",
  "region": "region",
  "settings": {
    "tier": "machine-type",
    "backupConfiguration": {
      "binaryLogEnabled": true,
      "enabled": true
    }
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "kind": "sql#operation",
  "targetLink": "https://www.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2019-09-25T22:19:33.735Z",
  "operationType": "CREATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://www.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

The response is a long-running operation, which may take a few minutes to complete.

Retrieve the IPv4 address

Retrieve the automatically assigned IPv4 address for the new instance:

Before using any of the request data below, make the following replacements:

  • project-id: your project ID
  • instance-id: instance ID created in prior step

HTTP method and URL: 

GET https://www.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "kind": "sql#instance",
  "state": "RUNNABLE",
  "databaseVersion": "MYSQL_5_7",
  "settings": {
    "authorizedGaeApplications": [],
    "tier": "db-f1-micro",
    "kind": "sql#settings",
    "pricingPlan": "PER_USE",
    "replicationType": "SYNCHRONOUS",
    "activationPolicy": "ALWAYS",
    "ipConfiguration": {
      "authorizedNetworks": [],
      "ipv4Enabled": true
    },
    "locationPreference": {
      "zone": "us-west1-a",
      "kind": "sql#locationPreference"
    },
    "dataDiskType": "PD_SSD",
    "backupConfiguration": {
      "startTime": "18:00",
      "kind": "sql#backupConfiguration",
      "enabled": true,
      "binaryLogEnabled": true
    },
    "settingsVersion": "1",
    "storageAutoResizeLimit": "0",
    "storageAutoResize": true,
    "dataDiskSizeGb": "10"
  },
  "etag": "--redacted--",
  "ipAddresses": [
    {
      "type": "PRIMARY",
      "ipAddress": "10.0.0.1"
    }
  ],
  "serverCaCert": {
    ...
  },
  "instanceType": "CLOUD_SQL_INSTANCE",
  "project": "project-id",
  "serviceAccountEmailAddress": "redacted@gcp-sa-cloud-sql.iam.gserviceaccount.com",
  "backendType": "SECOND_GEN",
  "selfLink": "https://www.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "connectionName": "project-id:region:instance-id",
  "name": "instance-id",
  "region": "us-west1",
  "gceZone": "us-west1-a"
}

Look for the ipAddress field in the response.

To see how the underlying REST API request is constructed for this task, see the APIs Explorer on the instances:insert page.

Sample machine types

With custom machine types, you can configure your instance with the amount of memory and CPUs that it needs. However, there are some restrictions on these values:

  • vCPUs must be either 1 or an even number between 2 and 96.
  • Memory must be:
    • 0.9 to 6.5 GB per vCPU
    • A multiple of 256 MB
    • At least 3.75 GB (3840 MB)

Here are some sample machine type values, based on the predefined machine types available for PostgreSQL instances:

Predefined machine type vCPUs Memory (MBs) API tier string
db-n1-standard-1 1 3840 db-custom-1-3840
db-n1-standard-2 2 7680 db-custom-2-7680
db-n1-standard-4 4 15360 db-custom-4-15360
db-n1-standard-8 8 30720 db-custom-8-30720
db-n1-standard-16 16 61440 db-custom-16-61440
db-n1-standard-32 32 122880 db-custom-32-122880
db-n1-standard-64 64 245760 db-custom-64-245760
db-n1-standard-96 96 368640 db-custom-96-368640
db-n1-highmem-2 2 13312 db-custom-2-13312
db-n1-highmem-4 4 26624 db-custom-4-26624
db-n1-highmem-8 8 53248 db-custom-8-53248
db-n1-highmem-16 16 106496 db-custom-16-106496
db-n1-highmem-32 32 212992 db-custom-32-212992
db-n1-highmem-64 64 425984 db-custom-64-425984
db-n1-highmem-96 96 638976 db-custom-96-638976

Troubleshooting

Click the links in the table for details:

For this problem... The issue might be... Try this...
Internal error. Missing service networking service account. Disable and re-enable the Service Networking API.
Terraform instance creation fails. Terraform configuration error. Inspect and repair the Terraform configuration file.
HTTP Error 409 in Terraform script. Another operation is already in progress. Fix the Terraform script to wait for each operation to finish.
Unknown error Trying to create an instance with the same name as one recently deleted. Or trying to create multiple instances simultaneously with a new private IP range being used. Use a different name for the instance or wait until it's been a week since the instance was deleted. Recreate failed instances consecutively using different names.

Internal error

You see the error message {"ResourceType":"sqladmin.v1beta4.instance", "ResourceErrorCode":"INTERNAL_ERROR","ResourceErrorMessage":null}.

The issue might be

The service project is likely missing the service networking service account required for this feature.

Things to try

To repair service permissions, disable the Service Networking API , wait five minutes and then re-enable it.

Terraform instance creation fails

Terraform instance creation fails.

The issue might be

This is usually an issue within the Terraform script itself.

Things to try

Inspect and repair the Terraform configuration file.

409 error in Terraform script

You see the error message HTTP Error 409 in Terraform scripts.

The issue might be

Operation failed because another operation was already in progress

Things to try

Revise the script to halt execution until each instance operation is completed. Have the script poll and wait until a 200 is returned for the previous operation ID before continuing to the next step.

Unknown error

When trying to create an instance, you see an error message like Cloud SQL creation failed, error UNKNOWN.

The issue might be

Most likely you are trying to re-use the name of an instance you recently deleted. Instance names cannot be re-used for one week after deletion. Or you are trying to create multiple instances simultaneously using a new private IP range when only the first instance is created and others fail with Unknown error.

Things to try

Either use a different name for the instance, or wait one week to create a new one using that name. Create multiple instances consecutively instead of simultaneously.

What's next