Label instances

MySQL  |  PostgreSQL  |  SQL Server

This page explains labels. It describes how to create an instance with labels;how to add, update, and remove labels; and how to use labels in searches.

Labels are a lightweight way to group together instances that are related orassociated with each other. For example, you could label your instancesaccording to whether you are using them as test or production, or you couldadd your own billing code to an instance. You can use the labels to searchfor instances or to track instance charges.

You always add labels as key/value pairs:

{"userLabels":{"track":"production","location":"western-division""billing-code":"34802",...}

Modifying labels has no impact on Cloud SQL instance performance.

For more information, seeWhat are labels?andRequirements for labels.

Restrictions

  • You can assign up to 64 labels to each instance.

  • Label keys and values must conform to the following restrictions:

    • Keys and values cannot be longer than 63 characters each.
    • Keys and values can only contain lowercase letters, numeric characters,underscores, and dashes. International characters are allowed.
    • Label keys must start with a lowercase letter.
    • Label keys cannot be empty.

Create instances with labels

When creating a new instance using thegcloud CLI or theAPI, you can apply labels to the instance.

gcloud

When creating your instance, include the `--labels` flag, followed by a comma-separated list of key value pairs of labels. You must use the beta version of the create command to include labels.

For example:

gcloudbetasqlinstancescreate...--labelstrack=production,billing-code=34802

Terraform

When creating an instance with a label, use aTerraform resource:

resource "google_sql_database_instance" "postgres_instance_labels" {  name             = "postgres-instance-labels"  region           = "us-central1"  database_version = "POSTGRES_14"  settings {    tier = "db-custom-2-7680"    user_labels = {      track        = "production"      billing-code = 34802    }  }  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.  deletion_protection = false}

Apply the changes

To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.

Prepare Cloud Shell

  1. LaunchCloud Shell.

  2. Set the default Google Cloud project where you want to apply your Terraform configurations.

    You only need to run this command once per project, and you can run it in any directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (alsocalled aroot module).

  1. InCloud Shell, create a directory and a new file within that directory. The filename must have the.tf extension—for examplemain.tf. In this tutorial, the file is referred to asmain.tf.
    mkdirDIRECTORY && cdDIRECTORY && touch main.tf

  2. If you are following a tutorial, you can copy the sample code in each section or step.

    Copy the sample code into the newly createdmain.tf.

    Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

  3. Review and modify the sample parameters to apply to your environment.
  4. Save your changes.
  5. Initialize Terraform. You only need to do this once per directory.
    terraform init

    Optionally, to use the latest Google provider version, include the-upgrade option:

    terraform init -upgrade

Apply the changes

  1. Review the configuration and verify that the resources that Terraform is going to create or update match your expectations:
    terraform plan

    Make corrections to the configuration as necessary.

  2. Apply the Terraform configuration by running the following command and enteringyes at the prompt:
    terraform apply

    Wait until Terraform displays the "Apply complete!" message.

  3. Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.
Note: Terraform samples typically assume that the required APIs are enabled in your Google Cloud project.

Delete the changes

To delete your changes, do the following:

  1. To disable deletion protection, in your Terraform configuration file set thedeletion_protection argument tofalse.
    deletion_protection =  "false"
  2. Apply the updated Terraform configuration by running the following command and enteringyes at the prompt:
    terraform apply

  1. Remove resources previously applied with your Terraform configuration by running the following command and enteringyes at the prompt:

    terraform destroy

curl

In the API, during the `POST` request to add a new instance, add the `userLabels` property in the request body to apply labels to the new instance. For example, your request body for creating an instance has the following labels:

          "settings": {"tier":"db-custom-2-7680",                       "userLabels": {"track": "production",                                      "location": "western-division",                                      "billing-code": "34802"},

Add or update labels on an existing instance

console

  1. Go to the Cloud SQL Instances page in the Google Cloud console.

    Go to the Cloud SQL Instances page

  2. Select the checkboxes next to the resources you want to label.

  3. ClickShow Info Panel in the upper righthand corner to expand thelabels column.

  4. Update or add new labels as desired.

  5. Save your changes.

gcloud

Use thepatch subcommand (beta version) to update or add labels onan existing instance:

gcloudbetasqlinstancespatch[INSTANCE_NAME]--update-labels [KEY1]=[VALUE1]...

For example:

gcloudbetasqlinstancespatchmy-instance--update-labels track=production,billing-code=34802

If you provide a label key that already exists, the tool updates theexisting key with the new label value. If you provide a new key, the tooladds the new key to the list of labels. Only the labels you specify areaffected; existing labels not included in the command remain unchanged.

rest v1

To add or update labels, use thePATCH method:

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • instance-id: The instance ID
  • label-name-1: A label name
  • value-1: The value of label-name-1
  • label-name-2: A label name
  • value-2: The value of label-name-2

HTTP method and URL:

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

Request JSON body:

{  "settings" :    {        "userLabels" :         {            "label-name-1" : "value-1",            "label-name-2" : "value-2"         }    }}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

Save the request body in a file namedrequest.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

Save the request body in a file namedrequest.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-16T02:32:12.281Z",  "operationType": "UPDATE",  "name": "operation-id",  "targetId": "instance-id",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",  "targetProject": "project-id"}

If you provide a label key that already exists, the tool updates theexisting key with the new label value. If you provide a new key, the tooladds the new key to the list of labels. Only the labels you specify areaffected; existing labels not included in the request remain unchanged.

rest v1beta4

To add or update labels, use thePATCH method:

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • instance-id: The instance ID
  • label-name-1: A label name
  • value-1: The value of label-name-1
  • label-name-2: A label name
  • value-2: The value of label-name-2

HTTP method and URL:

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

Request JSON body:

{  "settings" :    {        "userLabels" :         {            "label-name-1" : "value-1",            "label-name-2" : "value-2"         }    }}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

Save the request body in a file namedrequest.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

Save the request body in a file namedrequest.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-16T02:32:12.281Z",  "operationType": "UPDATE",  "name": "operation-id",  "targetId": "instance-id",  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",  "targetProject": "project-id"}

If you provide a label key that already exists, the tool updates theexisting key with the new label value. If you provide a new key, the tooladds the new key to the list of labels. Only the labels you specify areaffected; existing labels not included in the request remain unchanged.

Remove a label

console

  1. Go to the Cloud SQL Instances page in the Google Cloud console.

    Go to the Cloud SQL Instances page

  2. Select the checkboxes next to the resources for which you want to removelabels.

  3. ClickShow info panel to expand the labels column.

  4. Click theX next to all the labels you want to remove.

  5. Save your changes.

gcloud

Using thegcloud CLI, run thepatch subcommand (betaversion) with the--remove-labels flag:

gcloudbetasqlinstancespatch[INSTANCE_NAME]--remove-labels [LABEL1],[LABEL2]

If you provide a label name that does not exist, no error is returned.

rest v1

You remove a label using the API by setting its value tonull:

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • instance-id: The instance ID
  • label-name: The label name

HTTP method and URL:

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

Request JSON body:

{  "settings" :    {        "userLabels" :         {            "label-name" : null,         }    }}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

Save the request body in a file namedrequest.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

Save the request body in a file namedrequest.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-16T02:32:12.281Z",  "operationType": "UPDATE",  "name": "operation-id",  "targetId": "instance-id",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",  "targetProject": "project-id"}

rest v1beta4

You remove a label using the API by setting its value tonull:

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • instance-id: The instance ID
  • label-name: The label name

HTTP method and URL:

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

Request JSON body:

{  "settings" :    {        "userLabels" :         {            "label-name" : null,         }    }}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

Save the request body in a file namedrequest.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

Save the request body in a file namedrequest.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-16T02:32:12.281Z",  "operationType": "UPDATE",  "name": "operation-id",  "targetId": "instance-id",  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",  "targetProject": "project-id"}

Filter instance searches using labels

You can filter your instance list results by labels using thegcloud CLI or the API.

gcloud

Ingcloud, make alist request and use the--filter flag.To filter on labels, use the syntaxlabels.[KEY]:[VALUE]. For example, if youwanted to filter on a labelbilling-code with a value of34802,you can run this command:

gcloudbetasqlinstanceslist--filter='labels.billing-code:34802'

If you want to filter on whether a label exists, regardless of its value:

gcloudbetasqlinstanceslist--filter='labels:billing-code'

For complete documentation about the filter syntax in the gcloud CLI,see thegcloud topic filters documentation.

curl

In the API, make a list request with a URL encodedfilter query parameter:

gcloud auth loginACCESS_TOKEN="$(gcloud auth print-access-token)"curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \     -X GET \     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.[KEY1_NAME]:[KEY1_VALUE]%20userLabels.[KEY2_NAME]:[KEY2_VALUE]

For example:

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \     -X GET \     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.track:production%20userLabels.billing-code:34802

When two label values are included with an (encoded) space between them,they both must be true for an instance to be returned (anAND operation).You can also explicitly provideAND,OR, andNOT operators. Forexample:

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \     -X GET \     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.track:production%20OR%20userLabels.billing-code:34802

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-07-16 UTC.