Creating instances

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 Cloud IAM page

  6. Enable the Cloud Key Management Service API.

    Enable the API

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).

    Note: You cannot reuse an instance name for up to a week after you have deleted the instance.

  5. Enter a password for the postgres user.
  6. Set the region for your instance.

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

  7. Under Configuration options, update any other settings you need for your instance:
    Setting Notes
    Database version
    Database version PostgreSQL 12 (Beta), PostgreSQL 11 (default), PostgreSQL 10, and PostgreSQL 9.6
    Connectivity
    Private IP Configures private IP connectivity for your instance. Learn more.
    Public IP Adds a public IPv4 address for your instance. Learn more.
    Machine type and storage
    Cores The number of vCPUs for your instance. Learn more.
    Memory The amount of memory for your instance, in GiBs. 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.
    Authorize networks
    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.
  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_11 \
           --cpu=[NUMBER_CPUS] --memory=[MEMORY_SIZE] \
           --region=[REGION] | --gce-zone=[GCE_ZONE] | --zone=[ZONE]
    

    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).

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

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

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

     gcloud sql instances create myinstance --database-version=POSTGRES_11 --cpu=2 \
            --memory=7680MiB --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.

    You can add more parameters to determine other instance settings:

    Setting Parameter Notes
    Required parameters
    Database version --database-version POSTGRES_12 (Beta), POSTGRES_11 (default), 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.
    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 64.
  • Memory must be:
    • 0.9 to 6.5 GiB per vCPU
    • A multiple of 256 MiB
    • At least 3.75 GiB (3840 MiB)

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

Predefined machine type vCPUs Memory (MiBs) 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

What's next