במאמר הזה מוסבר איך לחבר את מופע AlloyDB לסוכנים שונים שתומכים ב-Model Context Protocol (MCP).
מומלץ להשתמש בתוסף הייעודי של AlloyDB ל-Gemini CLI. Gemini CLI משלב את שרת ה-MCP הבסיסי ישירות בתוסף, כך שלא צריך להגדיר שרת נפרד. אתם יכולים להגדיר את Gemini Code Assist כך שישתמש ב-Gemini CLI, וליהנות מיתרונות דומים בהגדרה בסביבת הפיתוח המשולבת (IDE).
לחלופין, אפשר לחבר סוכנים וסביבות פיתוח משולבות אחרות שתומכות ב-MCP באמצעות MCP Toolbox for Databases. Toolbox הוא שרת MCP בקוד פתוח שנועד לחבר סוכני AI לנתונים שלכם. הוא מטפל במשימות כמו אימות ואיגום חיבורים, ומאפשר לכם ליצור אינטראקציה עם הנתונים באמצעות שפה טבעית ישירות מ-IDE.
לפני שמתחילים
כדי להתחבר למופע AlloyDB ולהשתמש בכלים הזמינים, אתם צריכים להיות בעלי אחד מהתפקידים הבאים בניהול הזהויות והרשאות הגישה (IAM), או תפקיד בהתאמה אישית עם הרשאות שוות ערך:
| משימה | שם התפקיד | התפקיד שנדרש בניהול זהויות והרשאות גישה (IAM) |
|---|---|---|
| שימוש בכלים לקריאה בלבד כדי להציג רשימה של משאבי AlloyDB ולקבל אותם | AlloyDB Viewer | roles/alloydb.viewer |
| התחברות למופע והרצת שאילתות | Cloud AlloyDB Client | roles/alloydb.client |
| Service Usage Consumer | roles/serviceusage.serviceUsageConsumer |
|
| ביצוע משימות ניהול (כמו יצירה או ניהול של אשכולות, מופעים ומשתמשים) | AlloyDB Admin | roles/alloydb.admin |
| שימוש בתוסף observability | כלי לצפייה בניטור | roles/monitoring.viewer |
לפני שמתחברים למכונת AlloyDB, צריך להגדיר את הפרויקט ואת מסד הנתונים.
- נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify 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.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
מפעילים את Cloud APIs שנדרשים כדי ליצור חיבור ל-AlloyDB.
בשלב אישור הפרויקט, לוחצים על הבא כדי לאשר את שם הפרויקט שרוצים לבצע בו שינויים.
בשלב Enable APIs (הפעלת ממשקי API), לוחצים על Enable (הפעלה) כדי להפעיל את ממשקי ה-API הבאים:
- AlloyDB API
- Compute Engine API
- Cloud Resource Manager API
- Service Networking API
אם אתם מתכננים להגדיר קישוריות לרשת ב-AlloyDB באמצעות רשת VPC שנמצאת באותו פרויקט Google Cloud כמו AlloyDB, אתם צריכים להשתמש ב-Service Networking API.
אם אתם מתכננים להגדיר קישוריות לרשת ל-AlloyDB באמצעות רשת VPC שנמצאת בפרויקט אחר Google Cloud , תצטרכו להשתמש ב-Compute Engine API וב-Cloud Resource Manager API.
- יוצרים אשכול או בוחרים אשכול ואת המופע הראשי שלו.
- מגדירים Application Default Credentials (ADC) לסביבה שלכם.
- יוצרים משתמש במסד נתונים או משתמשים בקיים. צריך להיות מוכנים להזין את שם המשתמש והסיסמה.
שימוש בתוספים ל-Gemini CLI ל-AlloyDB
Gemini CLI הוא סוכן AI בקוד פתוח שנועד לעזור בתהליכי פיתוח, למשל בכתיבת קוד, בניפוי באגים, בחיפוש נתונים וביצירת תוכן. המטרה שלו היא לספק ממשק סוכני לביצוע אינטראקציה עם שירותי Data Cloud ומסדי נתונים פופולריים בקוד פתוח.
השילוב עם Gemini CLI מתבצע באמצעות תוספים ייעודיים שמציעים יכולות נוספות בהשוואה לחיבור רגיל של MCP Toolbox. בקטעים הבאים מוסבר על התוספים alloydb ו-alloydb-observability, שמציעים תהליך התקנה וערכת כלים. התוספים בקוד פתוח מכילים מידע מפורט על התקנה, הגדרה ודוגמאות לשימוש. מידע נוסף זמין במאמר תוסף ל-Gemini CLI - AlloyDB ל-PostgreSQL.
תוסף AlloyDB
התוסף alloydb כולל כלים לשליחת שאילתות למסד הנתונים, לניהול משאבי AlloyDB ולמעקב אחרי תקינות מסד הנתונים.
בדוגמאות הבאות אנחנו משתמשים במסד נתונים לדוגמה ecommerce עם הטבלאות הבאות:
-
products: מכיל פרטי המוצר, כוללproduct_id,product_name,categoryו-price. -
customers: מאחסן נתוני לקוחות, כמוcustomer_id,first_name,last_nameו-email. -
orders: מכיל פרטי הזמנה, כוללorder_id,customer_idו-order_date.
| קטגוריה | כלים | דוגמה להנחיה בשפה טבעית |
|---|---|---|
| פעולות במסד נתונים |
database_overview |
תן לי סקירה כללית של מסד הנתונים הנוכחי. |
list_tables |
תציג לי את כל הטבלאות במסד הנתונים הנוכחי. | |
execute_sql |
תראה לי את 10 המוצרים הכי יקרים בקטגוריה 'מחשבים ניידים'. | |
list_active_queries |
אילו שאילתות מורצות במסד הנתונים? | |
get_query_plan |
תסביר את תוכנית השאילתות לשאילתה שמאתרת את כל הלקוחות שלא ביצעו הזמנה ב-6 החודשים האחרונים. | |
list_available_extensions |
אילו תוספים זמינים להתקנה? | |
list_installed_extensions |
מציינים את כל התוספים המותקנים. | |
list_indexes |
תציג את כל האינדקסים בטבלה products. |
|
list_locks |
הצגת כל הנעילות הפעילות במסד הנתונים. | |
list_schemas |
הצגת רשימה של כל הסכימות במסד הנתונים. | |
list_sequences |
הצגת כל הרצפים בסכימה הנוכחית. | |
list_triggers |
הצגת כל הטריגרים של הטבלה orders. |
|
list_views |
תציג לי את כל התצוגות בסכימה sales. |
|
| ניהול משאבים אשכולות, מופעים, משתמשים |
create_cluster |
יוצרים אשכול AlloyDB בשם sales-quarterly-db באזור us-east1. |
get_cluster |
מקבלים את הפרטים של אשכול sales-quarterly-db. |
|
list_clusters |
תציג לי את כל אשכולות ה-AlloyDB שלי. | |
create_instance |
יוצרים מכונת קריאה חדשה באשכול sales-quarterly-db. |
|
get_instance |
תציג לי את המידע על המופע sales-quarterly-db-rp. |
|
list_instances |
הצגת רשימה של כל המופעים באשכול sales-quarterly-db. |
|
create_user |
יצירת משתמש חדש במסד הנתונים בשם reporting_user עם הסיסמה report_password.יוצרים משתמש חדש במסד הנתונים של IAM עבור reporting_user@example.com. |
|
get_user |
קבלת המידע של המשתמש reporting_user. |
|
list_users |
מציגים רשימה של כל משתמשי מסד הנתונים. | |
wait_for_operation |
מה סטטוס הפעולה operation-163562789? |
|
| תקינות ותחזוקה של מסד הנתונים | list_autovacuum_configurations |
תראה לי את ההגדרה הנוכחית של autovacuum. |
list_memory_configurations |
מהן הגדרות הזיכרון הנוכחיות של המופע הראשי? | |
list_top_bloated_tables |
תציג את חמש הטבלאות הכי גדולות. | |
list_replication_slots |
הצגת כל משבצות השכפול הפעילות. | |
replication_stats |
הצגת הנתונים הסטטיסטיים הנוכחיים של השכפול. | |
list_invalid_indexes |
בודקים אם יש אינדקסים לא תקינים במסד הנתונים ecommerce. |
|
long_running_transactions |
האם יש עסקאות שפועלות במשך זמן רב? |
תוסף הניראות של AlloyDB
התוסף alloydb-observability מספק ממשק מאוחד לניהול ולמעקב אחרי הביצועים והתקינות של מסד הנתונים ישירות מ-Gemini CLI.
| קטגוריה | כלים | דוגמה להנחיה בשפה טבעית |
|---|---|---|
| ניראות (observability) | get_system_metrics |
מהם מדדי המערכת, כמו השימוש במעבד (CPU), בשעה האחרונה? |
get_query_metrics |
תראה לי את מדדי הביצועים של השאילתות מ-15 הדקות האחרונות. |
יש שתי דרכים להשתמש בתוסף ל-Gemini CLI ל-AlloyDB:
- כלי שורת פקודה עצמאי
- שילוב בסביבת הפיתוח המשולבת (IDE) באמצעות Gemini Code Assist
Gemini CLI
- מתקינים את Gemini CLI.
- מתקינים את התוסף AlloyDB ל-Gemini CLI ממאגר GitHub באמצעות הפקודה הבאה:
gemini extensions install https://github.com/gemini-cli-extensions/alloydb
- מגדירים משתני סביבה כדי להתחבר למופע AlloyDB:
export ALLOYDB_POSTGRES_PROJECT="PROJECT_ID" export ALLOYDB_POSTGRES_REGION="REGION" export ALLOYDB_POSTGRES_CLUSTER="CLUSTER_NAME" export ALLOYDB_POSTGRES_INSTANCE="INSTANCE_NAME" export ALLOYDB_POSTGRES_DATABASE="DATABASE_NAME"
תוסף ל-Gemini CLI ל-AlloyDB משתמש ב[פרטי הכניסה שמוגדרים כברירת מחדל לאפליקציה (ADC)](/authentication/application-default-credentials) לצורך אימות כברירת מחדל. אם רוצים להתחבר כמשתמש במסד נתונים, צריך להגדיר את משתני הסביבה האופציונליים הבאים:
#Optional: Set for database user authentication export ALLOYDB_POSTGRES_USER="USERNAME" export ALLOYDB_POSTGRES_PASSWORD="PASSWORD"
כדי להתחבר באמצעות כתובת IP פרטית, צריך להגדיר גם את משתנה הסביבה הבא:
export ALLOYDB_POSTGRES_IP_TYPE="private"
- מפעילים את Gemini CLI במצב אינטראקטיבי:
ממשק ה-CLI טוען באופן אוטומטי את התוסף AlloyDB ל-Gemini CLI ואת הכלים שלו, שבהם אפשר להשתמש כדי לקיים אינטראקציה עם מסד הנתונים.gemini
Gemini Code Assist
מומלץ להגדיר את Gemini Code Assist לשימוש ב-Gemini CLI. בגישה הזו אין צורך להגדיר שרת MCP באופן ידני.
- מוודאים שהתקנתם והגדרתם את Gemini CLI ואת התוסף
alloydb. - איך מגדירים את Gemini Code Assist לשימוש ב-Gemini CLI
- אפשר להתחיל אינטראקציה עם מופע AlloyDB באמצעות שפה טבעית ישירות בצ'אט של Gemini Code Assist.
התחברות ל-Antigravity
אפשר לחבר את AlloyDB ל-Antigravity בדרכים הבאות:
- שימוש ב-MCP Store
- שימוש בהגדרה מותאמת אישית
הערה: לא צריך להוריד את הקובץ הבינארי של MCP Toolbox כדי להשתמש בשיטות האלה.
חנות MCP
השיטה המומלצת ביותר להתחבר ל-AlloyDB ב-Antigravity היא באמצעות מאגר ה-MCP המובנה.
- פותחים את Antigravity ואת החלונית של הסוכן של הכלי לעריכה.
- לוחצים על סמל שלוש הנקודות בחלק העליון של החלונית ובוחרים באפשרות MCP Servers (שרתי MCP).
- מחפשים את AlloyDB ל-PostgreSQL ברשימת השרתים הזמינים ולוחצים על התקנה.
- פועלים לפי ההנחיות במסך כדי לקשר את החשבונות בצורה מאובטחת (אם רלוונטי).
אחרי שמתקינים את AlloyDB ב-MCP Store, המשאבים והכלים מהשרת זמינים באופן אוטומטי בכלי העריכה.
הגדרה בהתאמה אישית
כדי להתחבר לשרת MCP בהתאמה אישית, פועלים לפי השלבים הבאים:
- פותחים את Antigravity ואת החלונית של הסוכן של הכלי לעריכה.
- לוחצים על סמל שלוש הנקודות בחלק העליון של החלונית ובוחרים באפשרות MCP Servers (שרתי MCP).
- לוחצים על Manage MCP Servers > View raw config (ניהול שרתי MCP > הצגת הגדרות גולמיות) כדי לפתוח את הקובץ
mcp_config.json. - מוסיפים את ההגדרה הבאה לקובץ
mcp_config.jsonושומרים אותו.
{
"mcpServers": {
"alloydb-postgres": {
"command": "npx",
"args": ["-y","@toolbox-sdk/server","--prebuilt","alloydb-postgres","--stdio"],
"env": {
"ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
"ALLOYDB_POSTGRES_REGION": "REGION",
"ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
"ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
"ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
"ALLOYDB_POSTGRES_USER": "USERNAME",
"ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
}
}
}
}
-
PROJECT_ID: מזהה הפרויקט ב- Google Cloud . -
REGION: שם האזור של AlloyDB. -
CLUSTER_NAME: השם של אשכול AlloyDB. -
INSTANCE_NAME: השם של מופע AlloyDB. -
DATABASE_NAME: השם של מסד הנתונים שלכם ב-AlloyDB. -
USERNAME: שם המשתמש שלכם ב-AlloyDB למשתנהALLOYDB_POSTGRES_USER. -
PASSWORD: הסיסמה שלכם ב-AlloyDB למשתנהALLOYDB_POSTGRES_PASSWORD.
חיבור לסביבות פיתוח משולבות אחרות באמצעות MCP Toolbox for Databases
בקטע הזה מוסבר איך להתחבר למופע AlloyDB מסוכנים שונים באמצעות MCP Toolbox for Databases. Toolbox פועל כשרת Model Context Protocol (MCP) בקוד פתוח שנמצא בין סביבת הפיתוח המשולבת (IDE) לבין מסד הנתונים, ומספק מישור בקרה לכלי ה-AI. בקטע הזה מוסבר איך להתחבר למכונת AlloyDB באמצעות כתובת IP ציבורית או פרטית. כברירת מחדל, ארגז הכלים משתמש בכתובת IP ציבורית, אבל אפשר להגדיר קישור דרך IP פרטי על ידי הגדרת משתנה הסביבה ALLOYDB_POSTGRES_IP_TYPE כמו בדוגמאות ההגדרה.
התקנה של MCP Toolbox for Databases
כדי לחבר את סביבת הפיתוח המשולבת (IDE) ל-AlloyDB, צריך להתקין את MCP Toolbox for Databases, שרת קוד פתוח שמחבר סוכני AI לנתונים שלכם.
מורידים את הגרסה האחרונה של Toolbox כקובץ בינארי. בוחרים את הקובץ הבינארי שמתאים למערכת ההפעלה ולארכיטקטורת ה-CPU. צריך להשתמש בגרסה v0.15.0 ואילך של Toolbox.
linux/amd64
curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox
darwin/arm64
curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox
darwin/amd64
curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox
windows/amd64
curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox
הופכים את הקובץ הבינארי לקובץ הפעלה.
chmod +x toolboxמאמתים את ההתקנה.
./toolbox --version
הגדרת הלקוח
בוחרים את הכלי של הסוכן מבין האפשרויות הבאות:
Claude code
- מתקינים את Claude Code.
- יוצרים את הקובץ
.mcp.jsonבתיקיית הבסיס של הפרויקט, אם הוא לא קיים. - מוסיפים את ההגדרה, מחליפים את משתני הסביבה בערכים שלכם ושומרים.
{
"mcpServers": {
"alloydb": {
"command": "./PATH/TO/toolbox",
"args": ["--prebuilt","alloydb-postgres","--stdio"],
"env": {
"ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
"ALLOYDB_POSTGRES_REGION": "REGION",
"ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
"ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
"ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
"ALLOYDB_POSTGRES_USER": "USERNAME",
"ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
}
}
}
}
Claude למחשב
- פותחים את Claude Desktop ועוברים אל הגדרות.
- בכרטיסייה Developer (פיתוח), לוחצים על Edit Config (עריכת ההגדרות) כדי לפתוח את קובץ ההגדרות.
- מוסיפים את ההגדרה, מחליפים את משתני הסביבה בערכים שלכם ושומרים.
{
"mcpServers": {
"alloydb": {
"command": "./PATH/TO/toolbox",
"args": ["--prebuilt","alloydb-postgres","--stdio"],
"env": {
"ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
"ALLOYDB_POSTGRES_REGION": "REGION",
"ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
"ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
"ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
"ALLOYDB_POSTGRES_USER": "USERNAME",
"ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
}
}
}
}
- מפעילים מחדש את Claude Desktop.
- במסך הצ'אט החדש מוצג סמל של פטיש (MCP) עם שרת ה-MCP החדש.
Cline
- פותחים את התוסף Cline ב-VS Code ומקישים על הסמל MCP Servers (שרתי MCP).
- לוחצים על Configure MCP Servers (הגדרת שרתי MCP) כדי לפתוח את קובץ ההגדרות.
- מוסיפים את ההגדרה הבאה, מחליפים את משתני הסביבה בערכים שלכם ושומרים.
{
"mcpServers": {
"alloydb": {
"command": "./PATH/TO/toolbox",
"args": ["--prebuilt","alloydb-postgres","--stdio"],
"env": {
"ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
"ALLOYDB_POSTGRES_REGION": "REGION",
"ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
"ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
"ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
"ALLOYDB_POSTGRES_USER": "USERNAME",
"ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
}
}
}
}
סטטוס פעיל ירוק יופיע אחרי שהשרת יתחבר בהצלחה.
סמן
- אם התיקייה
.cursorלא קיימת, יוצרים אותה בתיקיית הבסיס של הפרויקט. - יוצרים את הקובץ
.cursor/mcp.jsonאם הוא לא קיים, ופותחים אותו. - מוסיפים את ההגדרה הבאה, מחליפים את משתני הסביבה בערכים שלכם ושומרים.
{
"mcpServers": {
"alloydb": {
"command": "./PATH/TO/toolbox",
"args": ["--prebuilt","alloydb-postgres","--stdio"],
"env": {
"ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
"ALLOYDB_POSTGRES_REGION": "REGION",
"ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
"ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
"ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
"ALLOYDB_POSTGRES_USER": "USERNAME",
"ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
}
}
}
}
- פותחים את Cursor ועוברים אל Settings > Cursor Settings > MCP. כשמתבצע חיבור לשרת, מופיע סטטוס פעיל בצבע ירוק.
קוד Visual Studio (Copilot)
- פותחים את VS Code ויוצרים את הספרייה
.vscodeבתיקיית הבסיס של הפרויקט, אם היא לא קיימת. - יוצרים את הקובץ
.vscode/mcp.jsonאם הוא לא קיים, ופותחים אותו. - מוסיפים את ההגדרה הבאה, מחליפים את משתני הסביבה בערכים שלכם ושומרים.
{
"servers": {
"alloydb": {
"command": "./PATH/TO/toolbox",
"args": ["--prebuilt","alloydb-postgres","--stdio"],
"env": {
"ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
"ALLOYDB_POSTGRES_REGION": "REGION",
"ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
"ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
"ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
"ALLOYDB_POSTGRES_USER": "USERNAME",
"ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
}
}
}
}
גלישת רוח
- פותחים את Windsurf ועוברים אל Cascade assistant.
- לוחצים על סמל ה-MCP ואז על Configure (הגדרה) כדי לפתוח את קובץ ההגדרות.
- מוסיפים את ההגדרה הבאה, מחליפים את משתני הסביבה בערכים שלכם ושומרים.
{
"mcpServers": {
"alloydb": {
"command": "./PATH/TO/toolbox",
"args": ["--prebuilt","alloydb-postgres","--stdio"],
"env": {
"ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
"ALLOYDB_POSTGRES_REGION": "REGION",
"ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
"ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
"ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
"ALLOYDB_POSTGRES_USER": "USERNAME",
"ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
}
}
}
}