Creating instances

Console

1. In the Google Cloud Console, go to the Cloud SQL Instances page.

   Go to Cloud SQL Instances

2. Click Create instance.
3. On the Choose your database engine panel of the Create an instance page, click Choose PostgreSQL and click Next.
4. In the Instance ID field of the Instance info pane, enter an ID for your instance.
   

   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. Select the database version for your instance: PostgreSQL 14, PostgreSQL 13 (default), PostgreSQL 12, PostgreSQL 11, PostgreSQL 10, or PostgreSQL 9.6.
   

   The database version cannot be edited after the instance has been created.

7. In the Choose region and zonal availability section, 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.

   If you are configuring your instance for high availability, you can select both a primary and secondary zone.

   The following conditions apply when the secondary zone is used during instance creation:

   • The zones default to Any for the primary zone and Any (different from primary) for the secondary zone.
   • If both the primary and secondary zones are specified, they must be distinct zones.
8. In the Customize your instance section, update settings for your instance. Begin by clicking SHOW CONFIGURATION OPTIONS to display the groups of settings. Then, expand desired groups to review and customize settings. A Summary of all the options you select is shown on the right. Customizing these instance settings is optional. Defaults are assigned in every case where no customizations are made.

   The following table is a quick reference to instance settings. For more details about each setting, see the instance settings page.

   Setting	Notes
   Machine type
   Machine type	Select from Shared core, Lightweight, Standard (Most common), or High memory.
   Custom	Select this button to create an instance with a flexible configuration. When you select this option, you need to select the number of cores and amount of memory for your instance. Learn more.
   Cores	The number of vCPUs for your instance. Learn more.
   Memory	The amount of memory for your instance, in GBs. Learn more.
   Storage
   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.
   Enable automatic storage increases	Determines whether Cloud SQL automatically provides more storage for your instance when free space runs low. Learn more.
   Encryption
   Google-managed encryption	The default option.
   Customer key-managed encryption key (CMEK)	Select to use your key with Google Cloud Key Management Service. Learn more.
   Connectivity
   Private IP	Adds a private IP address for your instance. To enable connecting to the instance, additional configuration is required. Optionally, you can specify an allocated IP range for your instances to use for connections. Expand Show allocated IP range option. Select an IP range from the drop-down menu. Your instance can have both a public and a private IP address. Learn more about using private IP. Learn more about allocated IP address ranges.
   Public IP	Adds a public IP address for your instance. You can then add authorized networks to connect to the instance. Your instance can have both a public and a private IP address. Learn more about using public IP.
   Authorized networks	Add the name for the new network and the Network address. Learn more.
   Backups
   Automate backups	The window of time when you would like backups to start. Learn more.
   Choose where to store your backups	Select Multi-region for most use cases. If you need to store backups in a specific region, for example, if there are regulatory reasons to do so, select Region and select your region from the Location drop-down menu.
   Choose how many automated backups to store	The number of automated backups you would like to retain (from 1 to 365 days). Learn more.
   Enable point-in-time recovery	Enables point-in-time recovery and write-ahead logging. Learn more.
   Choose how many days of logs to retain	Configure write-ahead log retention from 1 to 7 days. The default setting is 7 days. Learn more.
   Maintenance
   Preferred 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.
   Order of updates	Your preferred timing for instance updates, relative to other instances in the same project. Learn more.
   Flags
   ADD FLAG	You can use database flags to control settings and parameters for your instance. Learn more.
   Labels
   ADD LABEL	Add a key and value for each label that you add. You use labels to help organize your instances.

9. Click Create Instance.

   Note: It might take a few minutes to create your instance. However, you can view information about the instance while it's being created.

gcloud

For information about installing and getting started with the gcloud, see Installing gcloud CLI. 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, you can use the --tier flag if you choose db-f1-micro or db-g1-small as the machine type:

   gcloud sql instances create INSTANCE_NAME \
   --tier=API_TIER_STRING \
   --region=REGION
   

   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
   

   See Custom instance configuration for more information about how to size --cpu and --memory.

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

   If you are creating an instance for high availability, you can specify both the primary and secondary zones, using the --zone and --secondary-zone parameters. The following conditions apply when the secondary zone is used during instance creation or edit:

   • The zones must be valid zones.
   • If the secondary zone is specified, the primary must also be specified.
   • If the primary and secondary zones are specified, they must be distinct zones.
   • If the primary and secondary zones are specified, they must belong to the same region.

   You can add more parameters to determine other instance settings:

   Setting	Parameter	Notes
   Required parameters
   Database version	--database-version	POSTGRES_14, POSTGRES_13 (default), POSTGRES_12, POSTGRES_11, POSTGRES_10, or POSTGRES_9_6
   Region	--region	See valid values.
   Connectivity
   Private IP	--network --no-assign-ip (optional) --allocated-ip-range-name (optional)	--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). --no-assign-ip: Instance will only have a private IP address. --allocated-ip-range-name: If specified, sets a range name for which an IP range is allocated. For example, google-managed-services-default. The range name should comply with RFC-1035 and be within 1-63 characters. (gcloud alpha sql instances create). Learn more about configuring private IP.
   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). For a custom instance configuration, use the --cpu or --memory parameters instead. See Custom instance configuration.
   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.
   Secondary zone	--secondary-zone	If you are creating an instance for high availability, you can specify both the primary and secondary zones using the >--zone and --secondary-zone parameters. The following restrictions apply when the secondary zone is used during instance creation or edit: The zones must be valid zones. If the secondary zone is specified, the primary must also be specified. If the primary and secondary zones are specified, they must be distinct zones. If the primary and secondary zones are specified, they must belong to the same region.
   Automatic backups	--backup-start-time	The window of time when you would like backups to start. Learn more.
   Retention settings for automated backups	--retained-backups-count	The number of automated backups to retain. Learn more.
   Point-in-time recovery	--enable-point-in-time recovery	Enables point-in-time recovery and write-ahead logging. Learn more.
   Retention settings for binary logging	--retained-transaction-log-days	The number of days to retain write-ahead logs for point-in-time recovery.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 Auth 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 v1

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, 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, make the following replacements:

• project-id: Your project ID
• instance-id: The desired instance ID
• region: The desired region
• database-version: Enum string of the database version. For example: POSTGRES_13
• password: The password for the root user
• machine-type: Enum string of the machine (tier) type, as: db-custom-[CPUS]-[MEMORY_MBS]

HTTP method and URL:

POST https://sqladmin.googleapis.com/v1/projects/project-id/instances

Request JSON body:

{
  "name": "instance-id",
  "region": "region",
  "databaseVersion": "database-version",
  "rootPassword": "password",
  "settings": {
    "tier": "machine-type",
    "backupConfiguration": {
      "enabled": true
    }
  }
}

To send your request, expand one of these options:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://sqladmin.googleapis.com/v1/projects/project-id/instances"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://sqladmin.googleapis.com/v1/projects/project-id/instances" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/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://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

The response is a long-running operation, which might 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, make the following replacements:

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

HTTP method and URL:

GET https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

To send your request, expand one of these options:

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth print-access-token) \
"https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method GET `
  -Headers $headers `
  -Uri "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "kind": "sql#instance",
  "state": "RUNNABLE",
  "databaseVersion": "MYSQL_8_0_18",
  "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://sqladmin.googleapis.com/v1/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.

REST v1beta4

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, 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, make the following replacements:

• project-id: Your project ID
• instance-id: The desired instance ID
• region: The desired region
• database-version: Enum string of the database version. For example: POSTGRES_12
• password: The password for the root user
• machine-type: Enum string of the machine (tier) type, as: db-custom-[CPUS]-[MEMORY_MBS]

HTTP method and URL:

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

Request JSON body:

{
  "name": "instance-id",
  "region": "region",
  "databaseVersion": "database-version",
  "rootPassword": "password",
  "settings": {
    "tier": "machine-type",
    "backupConfiguration": {
      "enabled": true
    }
  }
}

To send your request, expand one of these options:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-01T19:13:21.834Z",
  "operationType": "CREATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

The response is a long-running operation, which might 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, make the following replacements:

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

HTTP method and URL:

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

To send your request, expand one of these options:

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth print-access-token) \
"https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method GET `
  -Headers $headers `
  -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "kind": "sql#instance",
  "state": "RUNNABLE",
  "databaseVersion": "MYSQL_8_0_18",
  "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://sqladmin.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.