Skip to main content

instances

Creates, updates, deletes, gets or lists an instances resource.

Overview​

Nameinstances
TypeResource
Idgoogle.sqladmin.instances

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
namestringName of the Cloud SQL instance. This does not include the project ID.
availableMaintenanceVersionsarrayOutput only. List all maintenance versions applicable on the instance
backendTypestringThe backend type. SECOND_GEN: Cloud SQL database 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.
connectionNamestringConnection name of the Cloud SQL instance used in connection strings.
createTimestring (google-datetime)Output only. The time when the instance was created in RFC 3339 format, for example 2012-11-15T16:19:00.094Z.
currentDiskSizestring (int64)The current disk usage of the instance in bytes. This property has been deprecated. Use the "cloudsql.googleapis.com/database/disk/bytes_used" metric in Cloud Monitoring API instead. Please see this announcement for details.
databaseInstalledVersionstringOutput only. Stores the current database version running on the instance including minor version such as MYSQL_8_0_18.
databaseVersionstringThe database engine type and version. The databaseVersion field cannot be changed after instance creation.
diskEncryptionConfigurationobjectDisk encryption configuration specific to an instance. (id: DiskEncryptionConfiguration)
diskEncryptionStatusobjectDisk encryption status specific to an instance. (id: DiskEncryptionStatus)
dnsNamestringOutput only. The dns name of the instance.
dnsNamesarrayOutput only. The list of DNS names used by this instance.
etagstringThis field is deprecated and will be removed from a future version of the API. Use the settings.settingsVersion field instead.
failoverReplicaobjectThe name and status of the failover replica.
gceZonestringThe 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. WARNING: Changing this might restart the instance.
geminiConfigobjectGemini instance configuration. (id: GeminiInstanceConfig)
includeReplicasForMajorVersionUpgradebooleanInput only. Determines whether an in-place major version upgrade of replicas happens when an in-place major version upgrade of a primary instance is initiated.
instanceTypestringThe instance type.
ipAddressesarrayThe assigned IP addresses for the instance.
ipv6AddressstringThe IPv6 address assigned to the instance. (Deprecated) This property was applicable only to First Generation instances.
kindstringThis is always sql#instance.
maintenanceVersionstringThe current software version on the instance.
masterInstanceNamestringThe name of the instance which will act as primary in the replication setup.
maxDiskSizestring (int64)The maximum disk size of the instance in bytes.
nodeCountinteger (int32)The number of read pool nodes in a read pool.
nodesarrayOutput only. Entries containing information about each read pool node of the read pool.
onPremisesConfigurationobjectConfiguration specific to on-premises instances. (id: OnPremisesConfiguration)
outOfDiskReportobjectThis field represents the report generated by the proactive database wellness job for OutOfDisk issues. * Writers: * the proactive database wellness job for OOD. * Readers: * the proactive database wellness job (id: SqlOutOfDiskReport)
primaryDnsNamestringOutput only. DEPRECATED: please use write_endpoint instead.
projectstringThe project ID of the project containing the Cloud SQL instance. The Google apps domain is prefixed if applicable.
pscServiceAttachmentLinkstringOutput only. The link to service attachment of PSC instance.
regionstringThe geographical region of the Cloud SQL instance. It can be one of the regions where Cloud SQL operates: For example, asia-east1, europe-west1, and us-central1. The default value is us-central1.
replicaConfigurationobjectConfiguration specific to failover replicas and read replicas. (id: ReplicaConfiguration)
replicaNamesarrayThe replicas of the instance.
replicationClusterobjectOptional. A primary instance and disaster recovery (DR) replica pair. A DR replica is a cross-region replica that you designate for failover in the event that the primary instance experiences regional failure. Applicable to MySQL and PostgreSQL. (id: ReplicationCluster)
rootPasswordstringInitial root password. Use only on creation. You must set root passwords before you can connect to PostgreSQL instances.
satisfiesPzibooleanOutput only. This status indicates whether the instance satisfies PZI. The status is reserved for future use.
satisfiesPzsbooleanThis status indicates whether the instance satisfies PZS. The status is reserved for future use.
scheduledMaintenanceobjectThe start time of any upcoming scheduled maintenance for this instance. (id: SqlScheduledMaintenance)
secondaryGceZonestringThe Compute Engine zone that the failover instance is currently serving from for a regional instance. 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/failover zone.
selfLinkstringThe URI of this resource.
serverCaCertobjectSSL configuration. (id: SslCert)
serviceAccountEmailAddressstringThe service account email address assigned to the instance.\This property is read-only.
settingsobjectThe user settings. (id: Settings)
sqlNetworkArchitecturestring
statestringThe current serving state of the Cloud SQL instance.
suspensionReasonarrayIf the instance state is SUSPENDED, the reason for the suspension.
switchTransactionLogsToCloudStorageEnabledbooleanInput only. Whether Cloud SQL is enabled to switch storing point-in-time recovery log files from a data disk to Cloud Storage.
tagsobjectOptional. Input only. Immutable. Tag keys and tag values that are bound to this instance. You must represent each item in the map as: "" : "". For example, a single resource can have the following tags: "123/environment": "production", "123/costCenter": "marketing", For more information on tag creation and management, see https://cloud.google.com/resource-manager/docs/tags/tags-overview.
upgradableDatabaseVersionsarrayOutput only. All database versions that are available for upgrade.
writeEndpointstringOutput only. The dns name of the primary instance in a replication group.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectproject, instanceRetrieves a resource containing information about a Cloud SQL instance.
listselectprojectfilter, maxResults, pageTokenLists instances under a given project.
insertinsertprojectCreates a new Cloud SQL instance.
patchupdateproject, instancePartially updates settings of a Cloud SQL instance by merging the request with the current configuration. This method supports patch semantics.
updatereplaceproject, instanceUpdates settings of a Cloud SQL instance. Using this operation might cause your instance to restart.
deletedeleteproject, instanceenableFinalBackup, finalBackupDescription, finalBackupTtlDays, finalBackupExpiryTimeDeletes a Cloud SQL instance.
pre_check_major_version_upgradeexecproject, instanceExecute MVU Pre-checks
execute_sqlexecproject, instanceExecute SQL statements.
list_entra_id_certificatesexecproject, instanceLists all versions of EntraID certificates for the specified instance. There can be up to three sets of certificates listed: the certificate that is currently in use, a future that has been added but not yet used to sign a certificate, and a certificate that has been rotated out.
rotate_server_caexecproject, instanceRotates the server certificate to one signed by the Certificate Authority (CA) version previously added with the addServerCA method. For instances that have enabled Certificate Authority Service (CAS) based server CA, use RotateServerCertificate to rotate the server certificate.
reencryptexecproject, instanceReencrypt CMEK instance with latest key version.
cloneexecproject, instanceCreates a Cloud SQL instance as a clone of the source instance. Using this operation might cause your instance to restart.
exportexecproject, instanceExports data from a Cloud SQL instance to a Cloud Storage bucket as a SQL dump or CSV file.
list_server_certificatesexecproject, instanceLists all versions of server certificates and certificate authorities (CAs) for the specified instance. There can be up to three sets of certs listed: the certificate that is currently in use, a future that has been added but not yet used to sign a certificate, and a certificate that has been rotated out. For instances not using Certificate Authority Service (CAS) server CA, use ListServerCas instead.
point_in_time_restoreexecprojectsIdPoint in time restore for an instance managed by Google Cloud Backup and Disaster Recovery.
acquire_ssrs_leaseexecproject, instanceAcquire a lease for the setup of SQL Server Reporting Services (SSRS).
failoverexecproject, instanceInitiates a manual failover of a high availability (HA) primary instance to a standby instance, which becomes the primary instance. Users are then rerouted to the new primary. For more information, see the Overview of high availability page in the Cloud SQL documentation. If using Legacy HA (MySQL only), this causes the instance to failover to its failover replica instance.
reset_ssl_configexecproject, instancemodeDeletes all client certificates and generates a new server SSL certificate for the instance.
promote_replicaexecproject, instancefailoverPromotes the read replica instance to be an independent Cloud SQL primary instance. Using this operation might cause your instance to restart.
restartexecproject, instanceRestarts a Cloud SQL instance.
stop_replicaexecproject, instanceStops the replication in the read replica instance.
demote_masterexecproject, instanceDemotes the stand-alone instance to be a Cloud SQL read replica for an external database server.
switchoverexecproject, instancedbTimeoutSwitches over from the primary instance to the DR replica instance.
truncate_logexecproject, instanceTruncate MySQL general and slow query log tables MySQL only.
demoteexecproject, instanceDemotes an existing standalone instance to be a Cloud SQL read replica for an external database server.
restore_backupexecproject, instanceRestores a backup of a Cloud SQL instance. Using this operation might cause your instance to restart.
start_replicaexecproject, instanceStarts the replication in the read replica instance.
rotate_server_certificateexecproject, instanceRotates the server certificate version to one previously added with the addServerCertificate method. For instances not using Certificate Authority Service (CAS) server CA, use RotateServerCa instead.
rotate_entra_id_certificateexecproject, instanceRotates the server certificate version to one previously added with the addEntraIdCertificate method.
release_ssrs_leaseexecproject, instanceRelease a lease for the setup of SQL Server Reporting Services (SSRS).
importexecproject, instanceImports data into a Cloud SQL instance from a SQL dump or CSV file in Cloud Storage.
start_external_syncexecproject, instanceStart External primary instance migration.
reset_replica_sizeexecproject, instanceReset Replica Size to primary instance disk size.
reschedule_maintenanceexecproject, instanceReschedules the maintenance on the given instance.
verify_external_sync_settingsexecproject, instanceVerify External primary instance external sync settings.
perform_disk_shrinkexecproject, instancePerform Disk Shrink on primary instance.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
instancestring
projectstring
projectsIdstring
dbTimeoutstring (google-duration)
enableFinalBackupboolean
failoverboolean
filterstring
finalBackupDescriptionstring
finalBackupExpiryTimestring (google-datetime)
finalBackupTtlDaysstring (int64)
maxResultsinteger (uint32)
modestring
pageTokenstring

SELECT examples​

Retrieves a resource containing information about a Cloud SQL instance.

SELECT
name,
availableMaintenanceVersions,
backendType,
connectionName,
createTime,
currentDiskSize,
databaseInstalledVersion,
databaseVersion,
diskEncryptionConfiguration,
diskEncryptionStatus,
dnsName,
dnsNames,
etag,
failoverReplica,
gceZone,
geminiConfig,
includeReplicasForMajorVersionUpgrade,
instanceType,
ipAddresses,
ipv6Address,
kind,
maintenanceVersion,
masterInstanceName,
maxDiskSize,
nodeCount,
nodes,
onPremisesConfiguration,
outOfDiskReport,
primaryDnsName,
project,
pscServiceAttachmentLink,
region,
replicaConfiguration,
replicaNames,
replicationCluster,
rootPassword,
satisfiesPzi,
satisfiesPzs,
scheduledMaintenance,
secondaryGceZone,
selfLink,
serverCaCert,
serviceAccountEmailAddress,
settings,
sqlNetworkArchitecture,
state,
suspensionReason,
switchTransactionLogsToCloudStorageEnabled,
tags,
upgradableDatabaseVersions,
writeEndpoint
FROM google.sqladmin.instances
WHERE project = '{{ project }}' -- required
AND instance = '{{ instance }}' -- required
;

INSERT examples​

Creates a new Cloud SQL instance.

INSERT INTO google.sqladmin.instances (
data__settings,
data__masterInstanceName,
data__replicaConfiguration,
data__region,
data__satisfiesPzs,
data__includeReplicasForMajorVersionUpgrade,
data__replicationCluster,
data__connectionName,
data__etag,
data__instanceType,
data__ipv6Address,
data__selfLink,
data__rootPassword,
data__databaseVersion,
data__maintenanceVersion,
data__nodeCount,
data__project,
data__maxDiskSize,
data__state,
data__currentDiskSize,
data__tags,
data__geminiConfig,
data__diskEncryptionStatus,
data__switchTransactionLogsToCloudStorageEnabled,
data__kind,
data__suspensionReason,
data__replicaNames,
data__sqlNetworkArchitecture,
data__serverCaCert,
data__outOfDiskReport,
data__diskEncryptionConfiguration,
data__ipAddresses,
data__gceZone,
data__scheduledMaintenance,
data__failoverReplica,
data__onPremisesConfiguration,
data__backendType,
data__serviceAccountEmailAddress,
data__name,
data__secondaryGceZone,
project
)
SELECT 
'{{ settings }}',
'{{ masterInstanceName }}',
'{{ replicaConfiguration }}',
'{{ region }}',
{{ satisfiesPzs }},
{{ includeReplicasForMajorVersionUpgrade }},
'{{ replicationCluster }}',
'{{ connectionName }}',
'{{ etag }}',
'{{ instanceType }}',
'{{ ipv6Address }}',
'{{ selfLink }}',
'{{ rootPassword }}',
'{{ databaseVersion }}',
'{{ maintenanceVersion }}',
{{ nodeCount }},
'{{ project }}',
'{{ maxDiskSize }}',
'{{ state }}',
'{{ currentDiskSize }}',
'{{ tags }}',
'{{ geminiConfig }}',
'{{ diskEncryptionStatus }}',
{{ switchTransactionLogsToCloudStorageEnabled }},
'{{ kind }}',
'{{ suspensionReason }}',
'{{ replicaNames }}',
'{{ sqlNetworkArchitecture }}',
'{{ serverCaCert }}',
'{{ outOfDiskReport }}',
'{{ diskEncryptionConfiguration }}',
'{{ ipAddresses }}',
'{{ gceZone }}',
'{{ scheduledMaintenance }}',
'{{ failoverReplica }}',
'{{ onPremisesConfiguration }}',
'{{ backendType }}',
'{{ serviceAccountEmailAddress }}',
'{{ name }}',
'{{ secondaryGceZone }}',
'{{ project }}'
RETURNING
name,
acquireSsrsLeaseContext,
apiWarning,
backupContext,
endTime,
error,
exportContext,
importContext,
insertTime,
kind,
operationType,
preCheckMajorVersionUpgradeContext,
selfLink,
startTime,
status,
subOperationType,
targetId,
targetLink,
targetProject,
user
;

UPDATE examples​

Partially updates settings of a Cloud SQL instance by merging the request with the current configuration. This method supports patch semantics.

UPDATE google.sqladmin.instances
SET 
data__settings = '{{ settings }}',
data__masterInstanceName = '{{ masterInstanceName }}',
data__replicaConfiguration = '{{ replicaConfiguration }}',
data__region = '{{ region }}',
data__satisfiesPzs = {{ satisfiesPzs }},
data__includeReplicasForMajorVersionUpgrade = {{ includeReplicasForMajorVersionUpgrade }},
data__replicationCluster = '{{ replicationCluster }}',
data__connectionName = '{{ connectionName }}',
data__etag = '{{ etag }}',
data__instanceType = '{{ instanceType }}',
data__ipv6Address = '{{ ipv6Address }}',
data__selfLink = '{{ selfLink }}',
data__rootPassword = '{{ rootPassword }}',
data__databaseVersion = '{{ databaseVersion }}',
data__maintenanceVersion = '{{ maintenanceVersion }}',
data__nodeCount = {{ nodeCount }},
data__project = '{{ project }}',
data__maxDiskSize = '{{ maxDiskSize }}',
data__state = '{{ state }}',
data__currentDiskSize = '{{ currentDiskSize }}',
data__tags = '{{ tags }}',
data__geminiConfig = '{{ geminiConfig }}',
data__diskEncryptionStatus = '{{ diskEncryptionStatus }}',
data__switchTransactionLogsToCloudStorageEnabled = {{ switchTransactionLogsToCloudStorageEnabled }},
data__kind = '{{ kind }}',
data__suspensionReason = '{{ suspensionReason }}',
data__replicaNames = '{{ replicaNames }}',
data__sqlNetworkArchitecture = '{{ sqlNetworkArchitecture }}',
data__serverCaCert = '{{ serverCaCert }}',
data__outOfDiskReport = '{{ outOfDiskReport }}',
data__diskEncryptionConfiguration = '{{ diskEncryptionConfiguration }}',
data__ipAddresses = '{{ ipAddresses }}',
data__gceZone = '{{ gceZone }}',
data__scheduledMaintenance = '{{ scheduledMaintenance }}',
data__failoverReplica = '{{ failoverReplica }}',
data__onPremisesConfiguration = '{{ onPremisesConfiguration }}',
data__backendType = '{{ backendType }}',
data__serviceAccountEmailAddress = '{{ serviceAccountEmailAddress }}',
data__name = '{{ name }}',
data__secondaryGceZone = '{{ secondaryGceZone }}'
WHERE 
project = '{{ project }}' --required
AND instance = '{{ instance }}' --required
RETURNING
name,
acquireSsrsLeaseContext,
apiWarning,
backupContext,
endTime,
error,
exportContext,
importContext,
insertTime,
kind,
operationType,
preCheckMajorVersionUpgradeContext,
selfLink,
startTime,
status,
subOperationType,
targetId,
targetLink,
targetProject,
user;

REPLACE examples​

Updates settings of a Cloud SQL instance. Using this operation might cause your instance to restart.

REPLACE google.sqladmin.instances
SET 
data__settings = '{{ settings }}',
data__masterInstanceName = '{{ masterInstanceName }}',
data__replicaConfiguration = '{{ replicaConfiguration }}',
data__region = '{{ region }}',
data__satisfiesPzs = {{ satisfiesPzs }},
data__includeReplicasForMajorVersionUpgrade = {{ includeReplicasForMajorVersionUpgrade }},
data__replicationCluster = '{{ replicationCluster }}',
data__connectionName = '{{ connectionName }}',
data__etag = '{{ etag }}',
data__instanceType = '{{ instanceType }}',
data__ipv6Address = '{{ ipv6Address }}',
data__selfLink = '{{ selfLink }}',
data__rootPassword = '{{ rootPassword }}',
data__databaseVersion = '{{ databaseVersion }}',
data__maintenanceVersion = '{{ maintenanceVersion }}',
data__nodeCount = {{ nodeCount }},
data__project = '{{ project }}',
data__maxDiskSize = '{{ maxDiskSize }}',
data__state = '{{ state }}',
data__currentDiskSize = '{{ currentDiskSize }}',
data__tags = '{{ tags }}',
data__geminiConfig = '{{ geminiConfig }}',
data__diskEncryptionStatus = '{{ diskEncryptionStatus }}',
data__switchTransactionLogsToCloudStorageEnabled = {{ switchTransactionLogsToCloudStorageEnabled }},
data__kind = '{{ kind }}',
data__suspensionReason = '{{ suspensionReason }}',
data__replicaNames = '{{ replicaNames }}',
data__sqlNetworkArchitecture = '{{ sqlNetworkArchitecture }}',
data__serverCaCert = '{{ serverCaCert }}',
data__outOfDiskReport = '{{ outOfDiskReport }}',
data__diskEncryptionConfiguration = '{{ diskEncryptionConfiguration }}',
data__ipAddresses = '{{ ipAddresses }}',
data__gceZone = '{{ gceZone }}',
data__scheduledMaintenance = '{{ scheduledMaintenance }}',
data__failoverReplica = '{{ failoverReplica }}',
data__onPremisesConfiguration = '{{ onPremisesConfiguration }}',
data__backendType = '{{ backendType }}',
data__serviceAccountEmailAddress = '{{ serviceAccountEmailAddress }}',
data__name = '{{ name }}',
data__secondaryGceZone = '{{ secondaryGceZone }}'
WHERE 
project = '{{ project }}' --required
AND instance = '{{ instance }}' --required
RETURNING
name,
acquireSsrsLeaseContext,
apiWarning,
backupContext,
endTime,
error,
exportContext,
importContext,
insertTime,
kind,
operationType,
preCheckMajorVersionUpgradeContext,
selfLink,
startTime,
status,
subOperationType,
targetId,
targetLink,
targetProject,
user;

DELETE examples​

Deletes a Cloud SQL instance.

DELETE FROM google.sqladmin.instances
WHERE project = '{{ project }}' --required
AND instance = '{{ instance }}' --required
AND enableFinalBackup = '{{ enableFinalBackup }}'
AND finalBackupDescription = '{{ finalBackupDescription }}'
AND finalBackupTtlDays = '{{ finalBackupTtlDays }}'
AND finalBackupExpiryTime = '{{ finalBackupExpiryTime }}'
;

Lifecycle Methods​

Execute MVU Pre-checks

EXEC google.sqladmin.instances.pre_check_major_version_upgrade 
@project='{{ project }}' --required, 
@instance='{{ instance }}' --required 
@@json=
'{
"preCheckMajorVersionUpgradeContext": "{{ preCheckMajorVersionUpgradeContext }}"
}'
;