Use the Cloud SQL Admin API

MySQL   |  PostgreSQL   |  SQL Server

Cloud SQL provides a REST API for administering your instances programmatically. The REST API is defined by BackupRuns, Databases, Instances, Flags, Operations, SslCerts, Tiers, and Users resources. Each resource supports methods for accessing and working with it. For example, the Instances resource supports methods such as get, insert, and list. For details of all the resources and their methods, see the Cloud SQL Admin API Reference.

Important: The Cloud SQL Admin API v1 is now generally available. It is and will continue to be compatible with the v1beta4 version. There is no requirement to migrate from v1beta4 to the v1 Admin API.

When you send requests directly to the Cloud SQL REST API, you must create the correct form of the request, authorize the request as an authenticated user, and process any responses returned. Many of the tasks in this documentation provide API examples using cURL.

For more examples of using the APIs, see the page for the request in the Cloud SQL Admin API Reference. Each page has examples calling the API in several programming languages, as well as a request-specific Explorer to help you see what goes into a well-formed request and what to expect in the response.

You are also using the Cloud SQL Admin API, indirectly, when you use any of the following ways of administering instances:

• gcloud CLI, which contains a command-line interface you can use to work with your instances.

• One of the Client Libraries, such as for Java, Python, or .NET.

• Google Cloud console, a graphical web interface.

The advantage of using these methods, especially the Google Cloud console, is that they can greatly simplify administering your instances (depending on your use case). If you are just starting out with Cloud SQL, we recommend that you start with one of these tools first before working with the REST API directly.

Enable the API

To use the Cloud SQL Admin API, you need to enable it:

Console

1. Enable the API

2. Select your project.
3. Select Continue.

gcloud

1. Enter the following to display the project IDs for your Google Cloud projects:

   gcloud projects list

2. Set your default project:

   gcloud config set project YOUR_PROJECT_ID

3. Enable the Cloud SQL Admin API:

   gcloud services enable sqladmin.googleapis.com

Authorize requests

Your application needs to identify itself every time it sends a request to the Cloud SQL Admin API, by including an API key with each request.

Acquiring and using an API key

To acquire an API key:

1. Open the Credentials page in the Google Cloud console.
2. This API supports two types of credentials. Create whichever credentials are appropriate for your project:

   • OAuth 2.0: Whenever your application requests private user data, it must send an OAuth 2.0 token along with the request. Your application first sends a client ID and, possibly, a client secret to obtain a token. You can generate OAuth 2.0 credentials for web applications, service accounts, or installed applications.

     Note: Since this API doesn't have any methods that require OAuth 2.0 authorization, you might only need to obtain API keys, which are described below. However, if your application calls other APIs that require user authorization, then you still need OAuth 2.0 credentials.

     For more information, see the OAuth 2.0 documentation.

   • API keys: A request that does not provide an OAuth 2.0 token must send an API key. The key identifies your project and provides API access, quota, and reports.

     The API supports several types of restrictions on API keys. If the API key that you need doesn't already exist, then create an API key in the Console by clicking Create credentials  > API key. You can restrict the key before using it in production by clicking Restrict key and selecting one of the Restrictions.

To keep your API keys secure, follow the best practices for securely using API keys.

After you have an API key, your application can append the query parameter key=yourAPIKey to all request URLs.

The API key is safe for embedding in URLs; it doesn't need any encoding.

Note: For more information on authorizing requests, see Authorize Requests.

Permissions

In addition to authorization, the principal must have the required permissions for the API request. For more information, see IAM permissions in Cloud SQL.

API examples

You can see examples of using the API with cURL on the REST v1 and the REST v1beta4 tabs in the How-to Guides for this documentation set.

Provide JSON data from a file

When you use the API with cURL, you provide property values using the command line. If you are working with sensitive values such as passwords or security keys, providing them on the command line poses a security risk. For increased security, you can create a file containing the JSON data for the API call, and provide the path to the file on the command line.

To provide JSON data to your cURL API call from a file:

1. Create a file containing everything enclosed in the single quotes for the --data field.

   Include the curly brackets, but do not include the single quotes.

2. At the command line, provide the path to the file, preceded by the @ character, as the --data parameter:

   --data @<path-to-file>/<filename>
   

   For example, to create a database user, you could create a file named data.json with the following content:

   {"host": "%", "name": "user1", "password": "abc123"}
   

   Then you would use the following cURL command at the command line:

   curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
        --header 'Content-Type: application/json' \
        --data @./data.json \
        -X POST \
        https://www.googleapis.com/sql/v1beta4/projects/myProject/instances/myInstance/users
   

Work with long-running API calls

Some API calls, such as object creation, can take some time to complete. Because the API is asynchronous, the call returns immediately, even if the operation is still in progress. If a subsequent API call uses the newly created object, you must wait for the first operation to complete before proceeding.

You can wait programmatically by using the operation resource, which is returned for all insert calls. Provide the value of the name property to the operation get method and inspect the status of the operation, When the status property changes from PENDING to DONE, you can access the newly created object.

Cloud SQL and Google APIs Discovery Service

Google APIs Discovery Service is a service that you can use to discover Google APIs. For example, when you use the Google APIs Explorer tool, you are using the Discovery Service. In the Discovery Service, Cloud SQL is represented as "sqladmin" (for example: https://www.googleapis.com/discovery/v1/apis/sqladmin/v1beta4/sql.operation). This is different than the base path "sql" that you use in requests to the REST API (for example: https://www.googleapis.com/sql/v1beta4/projects/example-id/instances).

Some client libraries also use the Discovery Service. In the client creation code, be sure to use "sqladmin" to access the correct discovery document. For more information, see Client Libraries.

Use VPC Service Controls with the Cloud SQL Admin API

VPC Service Controls let you create a service perimeter around the Cloud SQL Admin API to help mitigate data exfiltration. The service perimeter allows free communication within the perimeter, but blocks all communication across the perimeter.

Before adding VPC Service Controls, it is recommended that you enable private IP and disable public IP on the Cloud SQL instances that you plan to add to the service perimeter. These requirements also apply to clones, read replicas, and failover replicas.

See Configure VPC Service Controls.