Initiates the creation of a Cloud SQL instance.

• The tool returns a long-running operation. Use theget_operation tool to poll its status until the operation completes.
• The instance creation operation can take several minutes. Use a command line tool to pause for 30 seconds before rechecking the status.
• After you use thecreate_instance tool to create an instance, you can use thecreate_user tool to create an IAM user account for the user currently logged in to the project.

• The value ofdata_api_access is set toALLOW_DATA_API by default. This setting lets you execute SQL statements using theexecute_sql tool and theexecuteSql API.

Unless otherwise specified, a newly created instance uses the default instance configuration of a development environment.

The following is the default configuration for an instance in a development environment:

{  "tier": "db-perf-optimized-N-2",  "data_disk_size_gb": 100,  "region": "us-central1",  "database_version": "POSTGRES_18",  "edition": "ENTERPRISE_PLUS",  "availability_type": "ZONAL",  "tags": [{"environment": "dev"}]}

The following configuration is recommended for an instance in a production environment:

{  "tier": "db-perf-optimized-N-8",  "data_disk_size_gb": 250,  "region": "us-central1",  "database_version": "POSTGRES_18",  "edition": "ENTERPRISE_PLUS",  "availability_type": "REGIONAL",  "tags": [{"environment": "prod"}]}

The following instance configuration is recommended for SQL Server:

{  "tier": "db-perf-optimized-N-8",  "data_disk_size_gb": 250,  "region": "us-central1",  "database_version": "SQLSERVER_2022_STANDARD",  "edition": "ENTERPRISE_PLUS",  "availability_type": "REGIONAL",  "tags": [{"environment": "prod"}]}

Execute any valid SQL statement, including data definition language (DDL), data control language (DCL), data query language (DQL), or data manipulation language (DML) statements, on a Cloud SQL instance.

To support theexecute_sql tool, a Cloud SQL instance must meet the following requirements:

• The value ofdata_api_access must be set toALLOW_DATA_API.
• For a MySQL instance, the database flagcloudsql_iam_authentication must be set toon. For a PostgreSQL instance, the database flagcloudsql.iam_authentication must be set toon.
• An IAM user account or IAM service account (CLOUD_IAM_USER orCLOUD_IAM_SERVICE_ACCOUNT) is required to call theexecute_sql tool. The tool executes the SQL statements using the privileges of the database user logged with IAM database authentication.

After you use thecreate_instance tool to create an instance, you can use thecreate_user tool to create an IAM user account for the user currently logged in to the project.

Theexecute_sql tool has the following limitations:

• If a SQL statement returns a response larger than 10 MB, then the response will be truncated.
• Theexecute_sql tool has a default timeout of 30 seconds. If a query runs longer than 30 seconds, then the tool returns aDEADLINE_EXCEEDED error.
• Theexecute_sql tool isn't supported for SQL Server.

If you receive errors similar to "IAM authentication is not enabled for the instance", then you can use theget_instance tool to check the value of the IAM database authentication flag for the instance.

If you receive errors like "The instance doesn't allow using executeSql to access this instance", then you can useget_instance tool to check thedata_api_access setting.

When you receive authentication errors:

1. Check if the currently logged-in user account exists as an IAM user on the instance using thelist_users tool.
2. If the IAM user account doesn't exist, then use thecreate_user tool to create the IAM user account for the logged-in user.
3. If the currently logged in user doesn't have the proper database user roles, then you can useupdate_user tool to grant database roles to the user. For example,cloudsqlsuperuser role can provide an IAM user with many required permissions.

4. Check if the currently logged in user has the correct IAM permissions assigned for the project. You can usegcloud projects get-iam-policy [PROJECT_ID] command to check if the user has the proper IAM roles or permissions assigned for the project.

   • The user must havecloudsql.instance.login permission to do automatic IAM database authentication.
   • The user must havecloudsql.instances.executeSql permission to execute SQL statements using theexecute_sql tool orexecuteSql API.
   • Common IAM roles that contain the required permissions: Cloud SQL Instance User (roles/cloudsql.instanceUser) or Cloud SQL Admin (roles/cloudsql.admin)

When receiving anExecuteSqlResponse, always check themessage andstatus fields within the response body. A successful HTTP status code doesn't guarantee full success of all SQL statements. Themessage andstatus fields will indicate if there were any partial errors or warnings during SQL statement execution.

Create a database user for a Cloud SQL instance.

• This tool returns a long-running operation. Use theget_operation tool to poll its status until the operation completes.
• When you use thecreate_user tool, specify the type of user:CLOUD_IAM_USER orCLOUD_IAM_SERVICE_ACCOUNT.
• By default the newly created user is assigned thecloudsqlsuperuser role, unless you specify other database roles explicitly in the request.
• You can use a newly created user with theexecute_sql tool if the user is a currently logged in IAM user. Theexecute_sql tool executes the SQL statements using the privileges of the database user logged in using IAM database authentication.

Thecreate_user tool has the following limitations:

• You can't create a built-in user with a password.
• Thecreate_user tool doesn't support creating a user for SQL Server.

To create an IAM user in PostgreSQL:

• The database username must be the IAM user's email address and all lowercase. For example, to create user for PostgreSQL IAM userexample-user@example.com, you can use the following request:

{  "name": "example-user@example.com",  "type": "CLOUD_IAM_USER",  "instance":"test-instance",  "project": "test-project"}

The created database username for the IAM user isexample-user@example.com.

To create an IAM service account in PostgreSQL:

• The database username must be created without the.gserviceaccount.com suffix even though the full email address for the account isservice-account-name@project-id.iam.gserviceaccount.com. For example, to create an IAM service account for PostgreSQL you can use the following request format:

{   "name": "test@test-project.iam",   "type": "CLOUD_IAM_SERVICE_ACCOUNT",   "instance": "test-instance",   "project": "test-project"}

The created database username for the IAM service account istest@test-project.iam.

To create an IAM user or IAM service account in MySQL:

• When Cloud SQL for MySQL stores a username, it truncates the @ and the domain name from the user or service account's email address. For example,example-user@example.com becomesexample-user.
• For this reason, you can't add two IAM users or service accounts with the same username but different domain names to the same Cloud SQL instance.
• For example, to create user for the MySQL IAM userexample-user@example.com, use the following request:

{   "name": "example-user@example.com",   "type": "CLOUD_IAM_USER",   "instance": "test-instance",   "project": "test-project"}

The created database username for the IAM user isexample-user.

• For example, to create the MySQL IAM service accountservice-account-name@project-id.iam.gserviceaccount.com, use the following request:

{   "name": "service-account-name@project-id.iam.gserviceaccount.com",   "type": "CLOUD_IAM_SERVICE_ACCOUNT",   "instance": "test-instance",   "project": "test-project"}

The created database username for the IAM service account isservice-account-name.

Update a database user for a Cloud SQL instance. A common use case for theupdate_user is to grant a user thecloudsqlsuperuser role, which can provide a user with many required permissions.

This tool only supports updating users to assign database roles.

• This tool returns a long-running operation. Use theget_operation tool to poll its status until the operation completes.
• Before calling theupdate_user tool, always check the existing configuration of the user such as the user type withlist_users tool.
• As a special case for MySQL, if thelist_users tool returns a full email address for theiamEmail field, for example{name=test-account, iamEmail=test-account@project-id.iam.gserviceaccount.com}, then in yourupdate_user request, use the full email address in theiamEmail field in thename field of your toolrequest. For example,name=test-account@project-id.iam.gserviceaccount.com.

Key parameters for updating user roles:

• database_roles: A list of database roles to be assigned to the user.
• revokeExistingRoles: A boolean field (default: false) that controls how existing roles are handled.

How role updates work:

1. IfrevokeExistingRoles is true:

   • Any existing roles granted to the user but NOT in the provideddatabase_roles list will be REVOKED.
   • Revoking only applies to non-system roles. System roles likecloudsqliamuser etc won't be revoked.
   • Any roles in thedatabase_roles list that the user does NOT already have will be GRANTED.
   • Ifdatabase_roles is empty, then ALL existing non-system roles are revoked.

2. IfrevokeExistingRoles is false (default):

   • Any roles in thedatabase_roles list that the user does NOT already have will be GRANTED.
   • Existing roles NOT in thedatabase_roles list are KEPT.
   • Ifdatabase_roles is empty, then there is no change to the user's roles.

Examples:

• Existing Roles:[roleA, roleB]

  • Request:database_roles: [roleB, roleC], revokeExistingRoles: true
  • Result: RevokesroleA, GrantsroleC. User roles become[roleB, roleC].
  • Request:database_roles: [roleB, roleC], revokeExistingRoles: false
  • Result: GrantsroleC. User roles become[roleA, roleB, roleC].
  • Request:database_roles: [], revokeExistingRoles: true
  • Result: RevokesroleA, RevokesroleB. User roles become[].
  • Request:database_roles: [], revokeExistingRoles: false
  • Result: No change. User roles remain[roleA, roleB].

Create a Cloud SQL instance as a clone of a source instance.

• This tool returns a long-running operation. Use theget_operation tool to poll its status until the operation completes.
• The clone operation can take several minutes. Use a command line tool to pause for 30 seconds before rechecking the status.

Partially updates the configuration settings of a Cloud SQL instance.

• This tool returns a long-running operation. Use theget_operation tool to poll its status until the operation completes.

Import data into a Cloud SQL instance.

If the file doesn't start withgs://, then the assumption is that the file is stored locally. If the file is local, then the file must be uploaded to Cloud Storage before you can make the actualimport_data call. To upload the file to Cloud Storage, you can use thegcloud orgsutil commands.

Before you upload the file to Cloud Storage, consider whether you want to use an existing bucket or create a new bucket in the provided project.

After the file is uploaded to Cloud Storage, the instance service account must have sufficient permissions to read the uploaded file from the Cloud Storage bucket.

This can be accomplished as follows:

1. Use theget_instance tool to get the email address of the instance service account. From the output of the tool, get the value of theserviceAccountEmailAddress field.
2. Grant the instance service account thestorage.objectAdmin role on the provided Cloud Storage bucket. Use a command likegcloud storage buckets add-iam-policy-binding or a request to the Cloud Storage API. It can take from two to up to seven minutes or more for the role to be granted and the permissions to be propagated to the service account in Cloud Storage. If you encounter a permissions error after updatingthe IAM policy, then wait a few minutes and try again.

After permissions are granted, you can import the data. We recommend that you leave optional parameters empty and use the system defaults. The file type can typically be determined by the file extension. For example, if the file is a SQL file,.sql or.csv for CSV file.

The following is a sample SQLimportContext for MySQL.

{  "uri": "gs://sample-gcs-bucket/sample-file.sql",  "kind": "sql#importContext",  "fileType": "SQL"}

There is nodatabase parameter present for MySQL since the database name is expected to be present in the SQL file. Specify only one URI. No other fields are required outside ofimportContext.

For PostgreSQL, thedatabase field is required. The following is a sample PostgreSQLimportContext with thedatabase field specified.

{  "uri": "gs://sample-gcs-bucket/sample-file.sql",  "kind": "sql#importContext",  "fileType": "SQL",  "database": "sample-db"}

Theimport_data tool returns a long-running operation. Use theget_operation tool to poll its status until the operation completes.