REST Resource: instances

Resource: DatabaseInstance

A Cloud SQL instance resource.

JSON representation
{
  "kind": string,
  "state": enum (SqlInstanceState),
  "databaseVersion": enum (SqlDatabaseVersion),
  "settings": {
    object (Settings)
  },
  "etag": string,
  "failoverReplica": {
    "name": string,
    "available": boolean
  },
  "masterInstanceName": string,
  "replicaNames": [
    string
  ],
  "maxDiskSize": string,
  "currentDiskSize": string,
  "ipAddresses": [
    {
      object (IpMapping)
    }
  ],
  "serverCaCert": {
    object (SslCert)
  },
  "instanceType": enum (SqlInstanceType),
  "project": string,
  "ipv6Address": string,
  "serviceAccountEmailAddress": string,
  "onPremisesConfiguration": {
    object (OnPremisesConfiguration)
  },
  "replicaConfiguration": {
    object (ReplicaConfiguration)
  },
  "backendType": enum (SqlBackendType),
  "selfLink": string,
  "suspensionReason": [
    enum (SqlSuspensionReason)
  ],
  "connectionName": string,
  "name": string,
  "region": string,
  "gceZone": string,
  "diskEncryptionConfiguration": {
    object (DiskEncryptionConfiguration)
  },
  "diskEncryptionStatus": {
    object (DiskEncryptionStatus)
  },
  "rootPassword": string,
  "scheduledMaintenance": {
    object (SqlScheduledMaintenance)
  }
}
Fields
kind

string

This is always

sql#instance

.

state

enum (SqlInstanceState)

The current serving state of the Cloud SQL instance. This can be one of the following.

RUNNABLE

: The instance is running, or is ready to run when accessed.

SUSPENDED

: The instance is not available, for example due to problems with billing.

PENDING_CREATE

: The instance is being created.

MAINTENANCE

: The instance is down for maintenance.

FAILED

: The instance creation failed.

UNKNOWN_STATE

: The state of the instance is unknown.

databaseVersion

enum (SqlDatabaseVersion)

The database engine type and version. The

databaseVersion

field can not be changed after instance creation. MySQL Second Generation instances:

MYSQL_5_7

(default) or

MYSQL_5_6

. PostgreSQL instances:

POSTGRES_9_6

(default) or

POSTGRES_11 Beta

MySQL First Generation instances:

MYSQL_5_6

(default) or

MYSQL_5_5

settings

object (Settings)

The user settings.

etag

string

This field is deprecated and will be removed from a future version of the API. Use the

settings.settingsVersion

field instead.

failoverReplica

object

The name and status of the failover replica. This property is applicable only to Second Generation instances.

failoverReplica.name

string

The name of the failover replica. If specified at instance creation, a failover replica is created for the instance. The name doesn't include the project ID. This property is applicable only to Second Generation instances.

failoverReplica.available

boolean

The availability status of the failover replica. A false status indicates that the failover replica is out of sync. The master can only failover to the failover replica when the status is true.

masterInstanceName

string

The name of the instance which will act as master in the replication setup.

replicaNames[]

string

The replicas of the instance.

maxDiskSize

string (Int64Value format)

The maximum disk size of the instance in bytes.

currentDiskSize

string (Int64Value format)

The current disk usage of the instance in bytes. This property has been deprecated. Users should use the "cloudsql.googleapis.com/database/disk/bytes_used" metric in Cloud Monitoring API instead. Please see this announcement for details.

ipAddresses[]

object (IpMapping)

The assigned IP addresses for the instance.

serverCaCert

object (SslCert)

SSL configuration.

instanceType

enum (SqlInstanceType)

The instance type. This can be one of the following.

CLOUD_SQL_INSTANCE

: A Cloud SQL instance that is not replicating from a master.

ON_PREMISES_INSTANCE

: An instance running on the customer's premises.

READ_REPLICA_INSTANCE

: A Cloud SQL instance configured as a read-replica.

project

string

The project ID of the project containing the Cloud SQL instance. The Google apps domain is prefixed if applicable.

ipv6Address

string

The IPv6 address assigned to the instance. This property is applicable only to First Generation instances.

serviceAccountEmailAddress

string

The service account email address assigned to the instance. This property is applicable only to Second Generation instances.

onPremisesConfiguration

object (OnPremisesConfiguration)

Configuration specific to on-premises instances.

replicaConfiguration

object (ReplicaConfiguration)

Configuration specific to failover replicas and read replicas.

backendType

enum (SqlBackendType)

FIRST_GEN

: First Generation instance. MySQL only.

SECOND_GEN

: Second Generation instance or PostgreSQL instance.

EXTERNAL

: A database server that is not managed by Google.
This property is read-only; use the

tier

property in the

settings

object to determine the database type and Second or First Generation.

suspensionReason[]

enum (SqlSuspensionReason)

If the instance state is SUSPENDED, the reason for the suspension.

connectionName

string

Connection name of the Cloud SQL instance used in connection strings.

name

string

Name of the Cloud SQL instance. This does not include the project ID.

region

string

The geographical region. Can be

us-central

(

FIRST_GEN

instances only),

us-central1

(

SECOND_GEN

instances only),

asia-east1

or

europe-west1

. Defaults to

us-central

or

us-central1

depending on the instance type (First Generation or Second Generation). The region can not be changed after instance creation.

gceZone

string

The Compute Engine zone that the instance is currently serving from. This value could be different from the zone that was specified when the instance was created if the instance has failed over to its secondary zone.

diskEncryptionConfiguration

object (DiskEncryptionConfiguration)

Disk encryption configuration specific to an instance. Applies only to Second Generation instances.

diskEncryptionStatus

object (DiskEncryptionStatus)

Disk encryption status specific to an instance. Applies only to Second Generation instances.

rootPassword

string

Initial root password. Use only on creation.

scheduledMaintenance

object (SqlScheduledMaintenance)

The start time of any upcoming scheduled maintenance for this instance.

SqlInstanceState

The current serving state of the database instance.

Enums
SQL_INSTANCE_STATE_UNSPECIFIED The state of the instance is unknown.
RUNNABLE The instance is running.
SUSPENDED The instance is currently offline, but it may run again in the future.
PENDING_DELETE The instance is being deleted.
PENDING_CREATE The instance is being created.
MAINTENANCE The instance is down for maintenance.
FAILED The instance failed to be created.

Settings

Database instance settings.

JSON representation
{
  "settingsVersion": string,
  "authorizedGaeApplications": [
    string
  ],
  "tier": string,
  "kind": string,
  "userLabels": {
    string: string,
    ...
  },
  "availabilityType": enum (SqlAvailabilityType),
  "pricingPlan": enum (SqlPricingPlan),
  "replicationType": enum (SqlReplicationType),
  "storageAutoResizeLimit": string,
  "activationPolicy": enum (SqlActivationPolicy),
  "ipConfiguration": {
    object (IpConfiguration)
  },
  "storageAutoResize": boolean,
  "locationPreference": {
    object (LocationPreference)
  },
  "databaseFlags": [
    {
      object (DatabaseFlags)
    }
  ],
  "dataDiskType": enum (SqlDataDiskType),
  "maintenanceWindow": {
    object (MaintenanceWindow)
  },
  "backupConfiguration": {
    object (BackupConfiguration)
  },
  "databaseReplicationEnabled": boolean,
  "crashSafeReplicationEnabled": boolean,
  "dataDiskSizeGb": string
}
Fields
settingsVersion

string (Int64Value format)

The version of instance settings. This is a required field for update method to make sure concurrent updates are handled properly. During update, use the most recent settingsVersion value for this instance and do not try to update this value.

authorizedGaeApplications[]

string

The App Engine app IDs that can access this instance. First Generation instances only.

tier

string

The tier (or machine type) for this instance, for example

db-n1-standard-1

(MySQL instances) or

db-custom-1-3840

(PostgreSQL instances). For MySQL instances, this property determines whether the instance is First or Second Generation. For more information, see Instance Settings.

kind

string

This is always

sql#settings

.

userLabels

map (key: string, value: string)

User-provided labels, represented as a dictionary where each label is a single key value pair.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

availabilityType

enum (SqlAvailabilityType)

Availability type (PostgreSQL instances only). Potential values:

ZONAL

: The instance serves data from only one zone. Outages in that zone affect data accessibility.

REGIONAL

: The instance can serve data from more than one zone in a region (it is highly available).
For more information, see Overview of the High Availability Configuration.

pricingPlan

enum (SqlPricingPlan)

The pricing plan for this instance. This can be either

PER_USE

or

PACKAGE

. Only

PER_USE

is supported for Second Generation instances.

replicationType

enum (SqlReplicationType)

The type of replication this instance uses. This can be either

ASYNCHRONOUS

or

SYNCHRONOUS

. This property is only applicable to First Generation instances.

storageAutoResizeLimit

string (Int64Value format)

The maximum size to which storage capacity can be automatically increased. The default value is 0, which specifies that there is no limit. Not used for First Generation instances.

activationPolicy

enum (SqlActivationPolicy)

The activation policy specifies when the instance is activated; it is applicable only when the instance state is

RUNNABLE

. Valid values:

ALWAYS

: The instance is on, and remains so even in the absence of connection requests.

NEVER

: The instance is off; it is not activated, even if a connection request arrives.

ON_DEMAND

: First Generation instances only. The instance responds to incoming requests, and turns itself off when not in use. Instances with

PER_USE

pricing turn off after 15 minutes of inactivity. Instances with

PER_PACKAGE

pricing turn off after 12 hours of inactivity.

ipConfiguration

object (IpConfiguration)

The settings for IP Management. This allows to enable or disable the instance IP and manage which external networks can connect to the instance. The IPv4 address cannot be disabled for Second Generation instances.

storageAutoResize

boolean

Configuration to increase storage size automatically. The default value is true. Not used for First Generation instances.

locationPreference

object (LocationPreference)

The location preference settings. This allows the instance to be located as near as possible to either an App Engine app or Compute Engine zone for better performance. App Engine co-location is only applicable to First Generation instances.

databaseFlags[]

object (DatabaseFlags)

The database flags passed to the instance at startup.

dataDiskType

enum (SqlDataDiskType)

The type of data disk:

PD_SSD

(default) or

PD_HDD

. Not used for First Generation instances.

maintenanceWindow

object (MaintenanceWindow)

The maintenance window for this instance. This specifies when the instance can be restarted for maintenance purposes. Not used for First Generation instances.

backupConfiguration

object (BackupConfiguration)

The daily backup configuration for the instance.

databaseReplicationEnabled

boolean

Configuration specific to read replica instances. Indicates whether replication is enabled or not.

crashSafeReplicationEnabled

boolean

Configuration specific to read replica instances. Indicates whether database flags for crash-safe replication are enabled. This property is only applicable to First Generation instances.

dataDiskSizeGb

string (Int64Value format)

The size of data disk, in GB. The data disk size minimum is 10GB. Not used for First Generation instances.

SqlAvailabilityType

The availability type of the given Cloud SQL instance.

Enums
SQL_AVAILABILITY_TYPE_UNSPECIFIED This is an unknown Availability type.
ZONAL Zonal available instance.
REGIONAL Regional available instance.

SqlPricingPlan

The pricing plan for this instance.

Enums
SQL_PRICING_PLAN_UNSPECIFIED This is an unknown pricing plan for this instance.
PACKAGE The instance is billed at a monthly flat rate.
PER_USE The instance is billed per usage.

SqlReplicationType

Enums
SQL_REPLICATION_TYPE_UNSPECIFIED This is an unknown replication type for a Cloud SQL instance.
SYNCHRONOUS The synchronous replication mode for First Generation instances. It is the default value.
ASYNCHRONOUS The asynchronous replication mode for First Generation instances. It provides a slight performance gain, but if an outage occurs while this option is set to asynchronous, you can lose up to a few seconds of updates to your data.

SqlActivationPolicy

Specifies when the instance should be activated.

Enums
SQL_ACTIVATION_POLICY_UNSPECIFIED Unknown activation plan.
ALWAYS The instance is always up and running.
NEVER The instance should never spin up.
ON_DEMAND The instance spins up upon receiving requests.

IpConfiguration

IP Management configuration.

JSON representation
{
  "ipv4Enabled": boolean,
  "privateNetwork": string,
  "requireSsl": boolean,
  "authorizedNetworks": [
    {
      object (AclEntry)
    }
  ]
}
Fields
ipv4Enabled

boolean

Whether the instance should be assigned an IP address or not.

privateNetwork

string

The resource link for the VPC network from which the Cloud SQL instance is accessible for private IP. For example,

/projects/myProject/global/networks/default

. This setting can be updated, but it cannot be removed after it is set.

requireSsl

boolean

Whether SSL connections over IP should be enforced or not.

authorizedNetworks[]

object (AclEntry)

The list of external networks that are allowed to connect to the instance using the IP. In CIDR notation, also known as 'slash' notation (e.g.

192.168.100.0/24

).

AclEntry

An entry for an Access Control list.

JSON representation
{
  "value": string,
  "expirationTime": string,
  "name": string,
  "kind": string
}
Fields
value

string

The whitelisted value for the access control list.

expirationTime

string (Timestamp format)

The time when this access control entry expires in RFC 3339 format, for example

2012-11-15T16:19:00.094Z

.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

name

string

Optional. A label to identify this entry.

kind

string

This is always

sql#aclEntry

.

LocationPreference

Preferred location. This specifies where a Cloud SQL instance should preferably be located, either in a specific Compute Engine zone, or co-located with an App Engine application. Note that if the preferred location is not available, the instance will be located as close as possible within the region. Only one location may be specified.

JSON representation
{
  "followGaeApplication": string,
  "zone": string,
  "kind": string
}
Fields
followGaeApplication

string

The App Engine application to follow, it must be in the same region as the Cloud SQL instance.

zone

string

The preferred Compute Engine zone (e.g. us-central1-a, us-central1-b, etc.).

kind

string

This is always

sql#locationPreference

.

DatabaseFlags

Database flags for Cloud SQL instances.

JSON representation
{
  "name": string,
  "value": string
}
Fields
name

string

The name of the flag. These flags are passed at instance startup, so include both server options and system variables for MySQL. Flags should be specified with underscores, not hyphens. For more information, see Configuring Database Flags in the Cloud SQL documentation.

value

string

The value of the flag. Booleans should be set to

on

for true and

off

for false. This field must be omitted if the flag doesn't take a value.

SqlDataDiskType

The type of disk that is used for a v2 instance to use.

Enums
SQL_DATA_DISK_TYPE_UNSPECIFIED This is an unknown data disk type.
PD_SSD An SSD data disk.
PD_HDD An HDD data disk.
OBSOLETE_LOCAL_SSD

This field is deprecated and will be removed from a future version of the API.

MaintenanceWindow

Maintenance window. This specifies when a v2 Cloud SQL instance should preferably be restarted for system maintenance purposes.

JSON representation
{
  "hour": integer,
  "day": integer,
  "updateTrack": enum (SqlUpdateTrack),
  "kind": string
}
Fields
hour

integer

hour of day - 0 to 23.

day

integer

day of week (1-7), starting on Monday.

updateTrack

enum (SqlUpdateTrack)

Maintenance timing setting:

canary

(Earlier) or

stable

(Later).
Learn more.

kind

string

This is always

sql#maintenanceWindow

.

SqlUpdateTrack

Enums
SQL_UPDATE_TRACK_UNSPECIFIED This is an unknown maintenance timing preference.
canary For instance update that requires a restart, this update track indicates your instance prefer to restart for new version early in maintenance window.
stable For instance update that requires a restart, this update track indicates your instance prefer to let Cloud SQL choose the timing of restart (within its Maintenance window, if applicable).

BackupConfiguration

Database instance backup configuration.

JSON representation
{
  "startTime": string,
  "enabled": boolean,
  "kind": string,
  "binaryLogEnabled": boolean,
  "replicationLogArchivingEnabled": boolean,
  "location": string
}
Fields
startTime

string

Start time for the daily backup configuration in UTC timezone in the 24 hour format -

HH:MM

.

enabled

boolean

Whether this configuration is enabled.

kind

string

This is always

sql#backupConfiguration

.

binaryLogEnabled

boolean

Whether binary log is enabled. If backup configuration is disabled, binary log must be disabled as well.

replicationLogArchivingEnabled

boolean

Reserved for future use.

location

string

Location of the backup

IpMapping

Database instance IP Mapping.

JSON representation
{
  "type": enum (SqlIpAddressType),
  "ipAddress": string,
  "timeToRetire": string
}
Fields
type

enum (SqlIpAddressType)

The type of this IP address. A

PRIMARY

address is a public address that can accept incoming connections. A

PRIVATE

address is a private address that can accept incoming connections. An

OUTGOING

address is the source address of connections originating from the instance, if supported.

ipAddress

string

The IP address assigned.

timeToRetire

string (Timestamp format)

The due time for this IP to be retired in RFC 3339 format, for example

2012-11-15T16:19:00.094Z

. This field is only available when the IP is scheduled to be retired.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

SqlIpAddressType

Enums
SQL_IP_ADDRESS_TYPE_UNSPECIFIED This is an unknown IP address type.
PRIMARY IP address the customer is supposed to connect to. Usually this is the load balancer's IP address
OUTGOING Source IP address of the connection a read replica establishes to its external master. This IP address can be whitelisted by the customer in case it has a firewall that filters incoming connection to its on premises master.
PRIVATE Private IP used when using private IPs and network peering.
MIGRATED_1ST_GEN V1 IP of a migrated instance. We want the user to decommission this IP as soon as the migration is complete. Note: V1 instances with V1 ip addresses will be counted as PRIMARY.

SqlInstanceType

Enums
SQL_INSTANCE_TYPE_UNSPECIFIED This is an unknown Cloud SQL instance type.
CLOUD_SQL_INSTANCE A regular Cloud SQL instance.
ON_PREMISES_INSTANCE An instance running on the customer's premises that is not managed by Cloud SQL.
READ_REPLICA_INSTANCE A Cloud SQL instance acting as a read-replica.

OnPremisesConfiguration

On-premises instance configuration.

JSON representation
{
  "hostPort": string,
  "kind": string,
  "caCertificate": string,
  "clientCertificate": string,
  "clientKey": string
}
Fields
hostPort

string

The host and port of the on-premises instance in host:port format

kind

string

This is always

sql#onPremisesConfiguration

.

caCertificate

string

PEM representation of the trusted CA's x509 certificate.

clientCertificate

string

PEM representation of the slave's x509 certificate.

clientKey

string

PEM representation of the slave's private key. The corresponsing public key is encoded in the client's certificate.

ReplicaConfiguration

Read-replica configuration for connecting to the master.

JSON representation
{
  "kind": string,
  "mysqlReplicaConfiguration": {
    object (MySqlReplicaConfiguration)
  },
  "failoverTarget": boolean
}
Fields
kind

string

This is always

sql#replicaConfiguration

.

mysqlReplicaConfiguration

object (MySqlReplicaConfiguration)

MySQL specific configuration when replicating from a MySQL on-premises master. Replication configuration information such as the username, password, certificates, and keys are not stored in the instance metadata. The configuration information is used only to set up the replication connection and is stored by MySQL in a file named

master.info

in the data directory.

failoverTarget

boolean

Specifies if the replica is the failover target. If the field is set to

true

the replica will be designated as a failover replica. In case the master instance fails, the replica instance will be promoted as the new master instance.

Only one replica can be specified as failover target, and the replica has to be in different zone with the master instance.

MySqlReplicaConfiguration

Read-replica configuration specific to MySQL databases.

JSON representation
{
  "dumpFilePath": string,
  "username": string,
  "password": string,
  "connectRetryInterval": integer,
  "masterHeartbeatPeriod": string,
  "caCertificate": string,
  "clientCertificate": string,
  "clientKey": string,
  "sslCipher": string,
  "verifyServerCertificate": boolean,
  "kind": string
}
Fields
dumpFilePath

string

Path to a SQL dump file in Google Cloud Storage from which the slave instance is to be created. The URI is in the form gs: //bucketName/fileName. Compressed gzip files (.gz) are also supported. // Dumps should have the binlog co-ordinates from which replication should // begin. This can be accomplished by setting --master-data to 1 when using // mysqldump.

username

string

The username for the replication connection.

password

string

The password for the replication connection.

connectRetryInterval

integer

Seconds to wait between connect retries. MySQL's default is 60 seconds.

masterHeartbeatPeriod

string (Int64Value format)

Interval in milliseconds between replication heartbeats.

caCertificate

string

PEM representation of the trusted CA's x509 certificate.

clientCertificate

string

PEM representation of the slave's x509 certificate.

clientKey

string

PEM representation of the slave's private key. The corresponsing public key is encoded in the client's certificate.

sslCipher

string

A list of permissible ciphers to use for SSL encryption.

verifyServerCertificate

boolean

Whether or not to check the master's Common Name value in the certificate that it sends during the SSL handshake.

kind

string

This is always

sql#mysqlReplicaConfiguration

.

SqlBackendType

Enums
SQL_BACKEND_TYPE_UNSPECIFIED This is an unknown backend type for instance.
FIRST_GEN V1 speckle instance.
SECOND_GEN V2 speckle instance.
EXTERNAL On premises instance.

SqlSuspensionReason

The suspension reason of the database instance if the state is SUSPENDED.

Enums
SQL_SUSPENSION_REASON_UNSPECIFIED This is an unknown suspension reason.
BILLING_ISSUE The instance is suspended due to billing issues (e.g., GCP account issue)
LEGAL_ISSUE The instance is suspended due to illegal content (e.g., child pornography, copyrighted material, etc.).
OPERATIONAL_ISSUE The instance is causing operational issues (e.g., causing the database to crash).
KMS_KEY_ISSUE The KMS key used by the instance is either revoked or denied access to

SqlScheduledMaintenance

Any scheduled maintenancce for this instance.

JSON representation
{
  "startTime": string,
  "canDefer": boolean,
  "canReschedule": boolean
}
Fields
startTime

string (Timestamp format)

The start time of any upcoming scheduled maintenance for this instance.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

canDefer
(deprecated)

boolean

canReschedule

boolean

If the scheduled maintenance can be rescheduled.

Methods

addServerCa

Add a new trusted Certificate Authority (CA) version for the specified instance.

clone

Creates a Cloud SQL instance as a clone of the source instance.

delete

Deletes a Cloud SQL instance.

demoteMaster

Demotes the stand-alone instance to be a Cloud SQL read replica for an external database server.

export

Exports data from a Cloud SQL instance to a Cloud Storage bucket as a SQL dump or CSV file.

failover

Failover the instance to its failover replica instance.

get

Retrieves a resource containing information about a Cloud SQL instance.

import

Imports data into a Cloud SQL instance from a SQL dump or CSV file in Cloud Storage.

insert

Creates a new Cloud SQL instance.

list

Lists instances under a given project.

listServerCas

Lists all of the trusted Certificate Authorities (CAs) for the specified instance.

patch

Updates settings of a Cloud SQL instance.

promoteReplica

Promotes the read replica instance to be a stand-alone Cloud SQL instance.

resetSslConfig

Deletes all client certificates and generates a new server SSL certificate for the instance.

restart

Restarts a Cloud SQL instance.

restoreBackup

Restores a backup of a Cloud SQL instance.

rotateServerCa

Rotates the server certificate to one signed by the Certificate Authority (CA) version previously added with the addServerCA method.

startReplica

Starts the replication in the read replica instance.

stopReplica

Stops the replication in the read replica instance.

truncateLog

Truncate MySQL general and slow query log tables

update

Updates settings of a Cloud SQL instance.
Was this page helpful? Let us know how we did:

Send feedback about...

Cloud SQL for MySQL
Need help? Visit our support page.