This page describes how to integrate Cloud SQL withVertex AI. This integration lets you apply largelanguage models (LLMs), which are hosted in Vertex AI, to aCloud SQL for PostgreSQL database, version 12 and later.

By integrating Cloud SQL with Vertex AI, you can applythe semantic and predictive power of machine learning (ML) models to your data.This integration extends the SQL syntax with two functions for querying models:

• Invoke predictions to calla model using SQL within a transaction.
• Generate embeddings to have anembedding model translate text prompts into numerical vectors. You can thenapply these vector embeddings as inputs tovector functions. This includesmethods to compare and sort samples of text according to their relativesemantic distance.

As a result, you can make real-time predictions and gain valuable insightsdirectly within the database, streamlining your workflows and enhancing yourdecision-making capabilities.

For more information about Vertex AI, seeIntroduction to Vertex AI.

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

1. Enable the necessary Google Cloud APIs.

   Console

   1. Go to theAPIs & Services page.
   2. From the projects list, select your project.
   3. If theAPI Library isn't open, then from the navigation menu, selectLibrary.

   4. Click the APIs that you want to enable. For this procedure, enable theCloud SQL Admin API andVertex AI API.

      Note: If you need help finding these APIs, then use the search field.

   5. After selecting each API, clickEnable.

   gcloud

   1. OpenCloud Shell, which provides command-line access to your Google Cloud resources directly from the browser.
   2. To enable the required APIs, use thegcloud services enable command:

      gcloud services enable sqladmin.googleapis.com \enable aiplatform.googleapis.com

   This command enables the following APIs:
   • Cloud SQL Admin API
   • Vertex AI API

2. Grant the Cloud SQL service account Identity and Access Management (IAM) permissions to access Vertex AI.

   gcloud

   Note: If you're creating an instance withVertex AI enabled, thencreate the instancebefore you complete this step.To add the Vertex AIpermissions to the Cloud SQL service account for the project wherethe Cloud SQL instance is located, use thegcloud projects add-iam-policy-bindingcommand:

   gcloud projects add-iam-policy-bindingPROJECT_ID \  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \  --role="roles/aiplatform.user"

   Make the following replacements:

   • PROJECT_ID: the ID of the project that has the Vertex AI endpoint. Cloud SQL uses this endpoint to access the LLM that's hosted in Vertex AI.

   • SERVICE_ACCOUNT_EMAIL: the email address of the Cloud SQL service account.

     To find this email address, use thegcloud sql instances describeINSTANCE_NAME command and replaceINSTANCE_NAME with the name of the Cloud SQL instance. The value that appears next to theserviceAccountEmailAddress parameter is the email address.

   Note: In general, the policy change takes effect within 2 minutes. However, under certain circumstances, it can take up to 7 minutes for such changes to propagate fully across the system. For more information, seeAccess change propagation.

Enable database integration with Vertex AI

To enable database integration with Vertex AI, complete the following steps:

1. Create or update a Cloud SQL instance so that the instance can integrate with Vertex AI.

   gcloud

   Create the instance

   To create the Cloud SQL instance, use thegcloud sql instances create command.

   gcloudsqlinstancescreateINSTANCE_NAME\--database-version=DATABASE_VERSION\--tier=MACHINE_TYPE\--region=REGION_NAME\--enable-google-ml-integration\--database-flagscloudsql.enable_google_ml_integration=on

   Make the following replacements:

   • INSTANCE_NAME: the name of the instance
   • DATABASE_VERSION: the database version for the instance (for example,POSTGRES_13)
   • MACHINE_TYPE: the machine type for the instance
   • REGION_NAME: the region name for the instance

   Note:For more information about these parameters, seeCreate instances.

   Update the instance

   To update the instance, use thegcloud sql instances patch command.

   gcloudsqlinstancespatchINSTANCE_NAME\--enable-google-ml-integration\--database-flagscloudsql.enable_google_ml_integration=on

   If this update modifies a value that requires a restart, then you see a promptto proceed with the change or cancel.

   Note:For more information about updating an instance, seeEdit instances.

   REST v1

   Create the instance

   Use this example to create the instance. For a complete list of parameters for this call, see theinstances:insert page. For information about instance settings, including valid values for a region, seeInstance settings.

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

   • PROJECT_ID: the ID orproject number of the Google Cloud project that contains the instance
   • INSTANCE_NAME: the name of the instance
   • REGION_NAME: the region name for the instance
   • DATABASE_VERSION: enum string of the database version (for example:POSTGRES_13)
   • PASSWORD: the password for theroot user
   • MACHINE_TYPE: enum string of the machine (tier) type, as:db-custom-[CPUS]-[MEMORY_MBS]
   • EDITION_TYPE: your Cloud SQL edition

   Note:For more information about these parameters, seeCreate instances.

   You must also include theenableGoogleMlIntegration object in the request. Set the following parameters, as required:

   • enableGoogleMlIntegration: when this parameter is set totrue, Cloud SQL instances can connect to Vertex AI to pass requests forreal-time predictions and insights to the AI
   • cloudsql.enable_google_ml_integration: when this parameter is set toon, Cloud SQL can integrate with Vertex AI

   HTTP method and URL:

   POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

   Request JSON body:

   {  "name": "INSTANCE_NAME",  "region": "REGION_NAME",  "databaseVersion": "DATABASE_VERSION",  "rootPassword": "PASSWORD",  "settings": {    "tier": "MACHINE_TYPE",    "edition": "EDITION_TYPE",    "enableGoogleMlIntegration": "true" | "false"    "databaseFlags":      {        "name": "cloudsql.enable_google_ml_integration",        "value": "on" | "off"      }  }}

   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 POST \
        -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"

   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 POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances" | 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": "2019-09-25T22:19:33.735Z",  "operationType": "CREATE",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

   Update the instance

   Use this example to update the instance. For a complete list of parameters for this call, see theinstances.patch page.

   If this update modifies a value that requires a restart, then you see a prompt to proceed with the change or cancel.

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

   • PROJECT_ID: the ID orproject number of the Google Cloud project that contains the instance
   • INSTANCE_NAME: the name of the instance

   HTTP method and URL:

   PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

   Request JSON body:

   {  "settings": {    "enableGoogleMlIntegration": true,    "databaseFlags":      {        "name": "cloudsql.enable_google_ml_integration",        "value": "on"      }   }}

   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_NAME"

   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_NAME" | 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_NAME",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-16T02:32:12.281Z",  "operationType": "UPDATE",  "name": "OPERATION_ID",  "targetId": "INSTANCE_NAME",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

   Note:For more information about updating an instance, seeEdit instances.

   REST v1beta4

   Create the instance

   Use this example to create the instance. For a complete list of parameters for this call, see theinstances:insert page. For information about instance settings, including valid values for a region, seeInstance settings.

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

   • PROJECT_ID: the ID orproject number of the Google Cloud project that contains the instance
   • INSTANCE_NAME: the name of the instance
   • REGION_NAME: the region name for the instance
   • DATABASE_VERSION: enum string of the database version (for example:POSTGRES_13)
   • PASSWORD: the password for theroot user
   • MACHINE_TYPE: enum string of the machine (tier) type, as:db-custom-[CPUS]-[MEMORY_MBS]
   • EDITION_TYPE: your Cloud SQL edition

   Note:For more information about these parameters, seeCreate instances.

   You must also include theenableGoogleMlIntegration object in the request. Set the following parameters, as required:

   • enableGoogleMlIntegration: when this parameter is set totrue, Cloud SQL instances can connect to Vertex AI to pass requests forreal-time predictions and insights to the AI
   • cloudsql.enable_google_ml_integration: when this parameter is set toon, Cloud SQL can integrate with Vertex AI

   HTTP method and URL:

   POST https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances

   Request JSON body:

   {  "name": "INSTANCE_NAME",  "region": "REGION_NAME",  "databaseVersion": "DATABASE_VERSION",  "rootPassword": "PASSWORD",  "settings": {    "tier": "MACHINE_TYPE",    "edition": "EDITION_TYPE",    "enableGoogleMlIntegration": "true" | "false"    "databaseFlags":      {        "name": "cloudsql.enable_google_ml_integration",        "value": "on" | "off"      }  }}

   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 POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances"

   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 POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances" | Select-Object -Expand Content

   You should receive a JSON response similar to the following:

   {  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2019-09-25T22:19:33.735Z",  "operationType": "CREATE",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

   Update the instance

   Use this example to update the instance. For a complete list of parameters for this call, see theinstances.patch page.

   If this update modifies a value that requires a restart, then you see a prompt to proceed with the change or cancel.

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

   • PROJECT_ID: the ID orproject number of the Google Cloud project that contains the instance
   • INSTANCE_NAME: the name of the instance

   HTTP method and URL:

   PATCH https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

   Request JSON body:

   {  "settings": {    "enableGoogleMlIntegration": true,    "databaseFlags":      {        "name": "cloudsql.enable_google_ml_integration",        "value": "on"      }   }}

   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/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME"

   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/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

   You should receive a JSON response similar to the following:

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

   Note:For more information about updating an instance, seeEdit instances.
2. Install thegoogle_ml_integration extension in a database of the primary Cloud SQL instance. This database contains data on which you want to run predictions.Note: You must connect to the primary instance even if you intend to run predictions while connected to aread replica of the instance.
   1. Connect apsql client to the primary instance, as described inConnect using a psql client.
   2. At thepsql command prompt, connect to the database:

      \cDB_NAME

      ReplaceDB_NAME with the name of the database on which you want to install the extension.

   3. Install the extension:

      CREATEEXTENSIONIFNOTEXISTSgoogle_ml_integrationCASCADE;

Troubleshoot

This section contains information about issues associated with integrating Cloud SQL with Vertex AI along with steps for troubleshooting the issues.

What's next

• Build LLM-powered applications using Lang Chain

• Work with vector embeddings

• Invoke online predictions from Cloud SQL instances

• Understand an example of an embedding workflow

• Build LLM-powered applications using LangChain