| list_instances |
List all Cloud SQL instances in the project.
|
| get_instance |
Get the details of a Cloud SQL instance.
|
| create_instance |
Initiates the creation of a Cloud SQL instance.
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_sql |
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 the execute_sql tool, a Cloud SQL instance must meet the following requirements:
- The value of
data_api_access must be set to ALLOW_DATA_API.
- For a MySQL instance, the database flag
cloudsql_iam_authentication must be set to on. For a PostgreSQL instance, the database flag cloudsql.iam_authentication must be set to on.
- An IAM user account or IAM service account (
CLOUD_IAM_USER or CLOUD_IAM_SERVICE_ACCOUNT) is required to call the execute_sql tool. The tool executes the SQL statements using the privileges of the database user logged with IAM database authentication.
After you use the create_instance tool to create an instance, you can use the create_user tool to create an IAM user account for the user currently logged in to the project. The execute_sql tool has the following limitations:
- If a SQL statement returns a response larger than 10 MB, then the response will be truncated.
- The
execute_sql tool has a default timeout of 30 seconds. If a query runs longer than 30 seconds, then the tool returns a DEADLINE_EXCEEDED error.
- The
execute_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 the get_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 use get_instance tool to check the data_api_access setting. When you receive authentication errors:
- Check if the currently logged-in user account exists as an IAM user on the instance using the
list_users tool.
- If the IAM user account doesn't exist, then use the
create_user tool to create the IAM user account for the logged-in user.
- If the currently logged in user doesn't have the proper database user roles, then you can use
update_user tool to grant database roles to the user. For example, cloudsqlsuperuser role can provide an IAM user with many required permissions.
Check if the currently logged in user has the correct IAM permissions assigned for the project. You can use gcloud 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 have
cloudsql.instance.login permission to do automatic IAM database authentication.
- The user must have
cloudsql.instances.executeSql permission to execute SQL statements using the execute_sql tool or executeSql 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 an ExecuteSqlResponse, always check the message and status fields within the response body. A successful HTTP status code doesn't guarantee full success of all SQL statements. The message and status fields will indicate if there were any partial errors or warnings during SQL statement execution.
|
| get_operation |
Get the status of a long-running operation. A long-running operation can take several minutes to complete. If an operation takes an extended amount of time, then use a command line tool to pause for 30 seconds before rechecking the status of the operation.
|
| create_user |
Create a database user for a Cloud SQL instance.
- This tool returns a long-running operation. Use the
get_operation tool to poll its status until the operation completes.
- When you use the
create_user tool, specify the type of user: CLOUD_IAM_USER or CLOUD_IAM_SERVICE_ACCOUNT.
- By default the newly created user is assigned the
cloudsqlsuperuser role, unless you specify other database roles explicitly in the request.
- You can use a newly created user with the
execute_sql tool if the user is a currently logged in IAM user. The execute_sql tool executes the SQL statements using the privileges of the database user logged in using IAM database authentication.
The create_user tool has the following limitations:
- You can't create a built-in user with a password.
- The
create_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 user
example-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 is example-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 is test@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 becomes example-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 user
example-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 is example-user.
- For example, to create the MySQL IAM service account
service-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 is service-account-name.
|
| update_user |
Update a database user for a Cloud SQL instance. A common use case for the update_user is to grant a user the cloudsqlsuperuser 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 the
get_operation tool to poll its status until the operation completes.
- Before calling the
update_user tool, always check the existing configuration of the user such as the user type with list_users tool.
- As a special case for MySQL, if the
list_users tool returns a full email address for the iamEmail field, for example {name=test-account,
iamEmail=test-account@project-id.iam.gserviceaccount.com}, then in your update_user request, use the full email address in the iamEmail field in the name 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:
If revokeExistingRoles is true:
- Any existing roles granted to the user but NOT in the provided
database_roles list will be REVOKED.
- Revoking only applies to non-system roles. System roles like
cloudsqliamuser etc won't be revoked.
- Any roles in the
database_roles list that the user does NOT already have will be GRANTED.
- If
database_roles is empty, then ALL existing non-system roles are revoked.
If revokeExistingRoles is false (default):
- Any roles in the
database_roles list that the user does NOT already have will be GRANTED.
- Existing roles NOT in the
database_roles list are KEPT.
- If
database_roles is empty, then there is no change to the user's roles.
Examples:
|
| clone_instance |
Create a Cloud SQL instance as a clone of a source instance.
- This tool returns a long-running operation. Use the
get_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.
|
| update_instance |
Partially updates the configuration settings of a Cloud SQL instance.
- This tool returns a long-running operation. Use the
get_operation tool to poll its status until the operation completes.
|
| list_users |
List all database users for a Cloud SQL instance.
|
| import_data |
Import data into a Cloud SQL instance. If the file doesn't start with gs://, 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 actual import_data call. To upload the file to Cloud Storage, you can use the gcloud or gsutil 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:
- Use the
get_instance tool to get the email address of the instance service account. From the output of the tool, get the value of the serviceAccountEmailAddress field.
- Grant the instance service account the
storage.objectAdmin role on the provided Cloud Storage bucket. Use a command like gcloud 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 SQL importContext for MySQL.
{
"uri": "gs://sample-gcs-bucket/sample-file.sql",
"kind": "sql#importContext",
"fileType": "SQL"
}
There is no database 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 of importContext. For PostgreSQL, the database field is required. The following is a sample PostgreSQL importContext with the database field specified.
{
"uri": "gs://sample-gcs-bucket/sample-file.sql",
"kind": "sql#importContext",
"fileType": "SQL",
"database": "sample-db"
}
The import_data tool returns a long-running operation. Use the get_operation tool to poll its status until the operation completes.
|
