Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Używanie AlloyDB Omni z zestawem narzędzi MCP do integracji agentów

1. Wprowadzenie

Aby zapewnić agentom AI, takim jak Antigravity CLI, bezpieczny i uporządkowany dostęp do bazy danych, możesz zintegrować AlloyDB Omni z MCP Toolbox for Databases.

AlloyDB Omni to wersja AlloyDB for PostgreSQL, którą można pobrać i uruchomić w dowolnym miejscu – lokalnie, na stacjach roboczych programistów, na urządzeniach brzegowych lub w chmurze – przy jednoczesnym zachowaniu wydajności i zgodności PostgreSQL klasy korporacyjnej.

MCP Toolbox for Databases to serwer open source od Google, który implementuje protokół Model Context Protocol (MCP), aby ułatwić, przyspieszyć i zabezpieczyć tworzenie narzędzi generatywnej AI, które wchodzą w interakcje z bazami danych. Znajduje się między platformą orkiestracji agenta a bazą danych i zapewnia te możliwości:

Uproszczone tworzenie: gotowe lub niestandardowe narzędzia baz danych, które łączą się z agentem przy minimalnej konfiguracji i mogą być używane w wielu agentach lub platformach.
Lepsza wydajność: wbudowane sprawdzone metody, takie jak agregacja połączeń i zarządzanie cyklem życia.
Większe bezpieczeństwo: scentralizowane zarządzanie danymi logowania i uwierzytelnianiem, dzięki czemu agenty nie wymagają nieprzetworzonych danych logowania do bazy danych.
Kompleksowa dostrzegalność: gotowe wskaźniki i logi czasu z wbudowaną obsługą OpenTelemetry.

Na koniec tego ćwiczenia będziesz mieć działający kontener AlloyDB Omni wypełniony przykładowymi danymi e-commerce, serwer MCP Toolbox udostępniający 31 gotowych narzędzi do wysyłania zapytań do administrowania AlloyDB Omni i wykonywania zapytań oraz skonfigurowanego agenta Antigravity CLI (agy), który może sprawdzać schematy, wykonywać zapytania SQL, analizować plany zapytań i diagnozować stan bazy danych za pomocą promptów w języku naturalnym.

Schemat architektury przedstawiający kompleksowy przepływ pracy od agenta do klienta MCP (Antigravity CLI), zestawu narzędzi MCP i AlloyDB Omni

Wymagania wstępne

dostęp do projektu w chmurze Google Cloud i Cloud Shell z konsoli Google Cloud lub stacji roboczej z systemem Linux;
zainstalowany i uruchomiony Docker,
Zainstalowano klienta PostgreSQL psql.
Zainstalowane curl i jq, aby skonfigurować Antigravity CLI i MCP Toolbox.

Czego się nauczysz

Jak wdrożyć i uruchomić kontener serwera bazy danych AlloyDB Omni za pomocą Dockera.
jak tworzyć przykładowe tabele, dane i indeksy w AlloyDB Omni;
Jak pobrać, skonfigurować i uruchomić MCP Toolbox for Databases z gotowym zestawem narzędzi alloydb-omni.
jak skonfigurować Antigravity CLI jako klienta MCP, aby połączyć się z serwerem MCP Toolbox.
jak używać promptów w języku naturalnym w interfejsie wiersza poleceń Antigravity do sprawdzania stanu bazy danych, eksplorowania schematów, uruchamiania zapytań SQL, analizowania planów zapytań i przeprowadzania diagnostyki konserwacyjnej;

Czego potrzebujesz

Działające środowisko terminala z Dockerem, psql, curl i jq. Możesz użyć Google Cloud Shell, które ma te narzędzia zainstalowane fabrycznie.

2. Konfiguracja i wymagania

Konfigurowanie projektu

Tworzenie projektu Google Cloud

W konsoli Google Cloud na stronie selektora projektów wybierz lub utwórz projekt Google Cloud.
Sprawdź, czy w projekcie Google Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności.

Uruchamianie Cloud Shell

Chociaż AlloyDB Omni i MCP Toolbox możesz uruchomić lokalnie na laptopie, w tym ćwiczeniu możesz użyć Google Cloud Shell, czyli środowiska wiersza poleceń działającego w chmurze, które ma wstępnie zainstalowane narzędzia Docker, psql, curl i jq.

Ikona aktywowania Cloud Shell

Otwórz konsolę Google Cloud i na pasku narzędzi w prawym górnym rogu kliknij Aktywuj Cloud Shell. Możesz też otworzyć Cloud Shell na jeden z tych sposobów:
- Jeśli używasz konsoli Google Cloud, naciśnij G, a następnie S.
- Otwórz bezpośrednio Cloud Shell.

Uzyskanie dostępu do środowiska i połączenie się z nim może zająć kilka chwil. Po zakończeniu tej operacji zobaczysz coś podobnego do tego:

Terminal Google Cloud Shell pokazujący, że środowisko zostało połączone

3. Przygotowywanie i uruchamianie serwera bazy danych AlloyDB Omni

W tej sekcji pobierzesz i uruchomisz kontener Dockera AlloyDB Omni oraz wypełnisz go przykładowymi danymi e-commerce do testowania.

Uruchamianie serwera bazy danych AlloyDB Omni

Zdefiniuj zmienne środowiskowe dla hosta, portu, bazy danych, użytkownika i wygenerowanego hasła AlloyDB Omni:

export ALLOYDB_OMNI_HOST="127.0.0.1"
export ALLOYDB_OMNI_PORT="5432"
export ALLOYDB_OMNI_DATABASE="postgres"
export ALLOYDB_OMNI_USER="postgres"
export ALLOYDB_OMNI_PASSWORD="$(openssl rand -hex 8)@1aA"
echo "Your generated AlloyDB Omni postgres password is: $ALLOYDB_OMNI_PASSWORD"

Uruchom kontener AlloyDB Omni w trybie odłączonym za pomocą Dockera:

docker run --name alloydbomni \
    -e POSTGRES_PASSWORD=$ALLOYDB_OMNI_PASSWORD \
    -p $ALLOYDB_OMNI_PORT:$ALLOYDB_OMNI_PORT \
    -d google/alloydbomni:latest

Sprawdź, czy kontener działa i czy możesz połączyć się z serwerem AlloyDB Omni za pomocą psql:

docker ps -a
until docker exec alloydbomni pg_isready -U "$ALLOYDB_OMNI_USER" -d "$ALLOYDB_OMNI_DATABASE"; do sleep 2; done
PGPASSWORD=$ALLOYDB_OMNI_PASSWORD psql -h $ALLOYDB_OMNI_HOST -p $ALLOYDB_OMNI_PORT -U $ALLOYDB_OMNI_USER -d $ALLOYDB_OMNI_DATABASE -c "SELECT 1;"

Tworzenie przykładowych danych do testów

Utwórz przykładowe tabele categories, products, customers i orders, wstaw rekordy testowe i utwórz indeksy, aby przetestować sprawdzanie schematu, zapytania SQL i plany wykonywania zapytań za pomocą MCP Toolbox:

PGPASSWORD="$ALLOYDB_OMNI_PASSWORD" psql -h $ALLOYDB_OMNI_HOST -p $ALLOYDB_OMNI_PORT -U $ALLOYDB_OMNI_USER -d $ALLOYDB_OMNI_DATABASE << 'EOF'
CREATE TABLE IF NOT EXISTS categories (
    category_id SERIAL PRIMARY KEY,
    name VARCHAR(50) UNIQUE NOT NULL
);

CREATE TABLE IF NOT EXISTS products (
    product_id SERIAL PRIMARY KEY,
    product_name VARCHAR(100) UNIQUE NOT NULL,
    category VARCHAR(50) NOT NULL,
    price NUMERIC(10, 2) NOT NULL,
    stock INT DEFAULT 0
);

CREATE TABLE IF NOT EXISTS customers (
    customer_id SERIAL PRIMARY KEY,
    first_name VARCHAR(50),
    last_name VARCHAR(50),
    email VARCHAR(100) UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS orders (
    order_id SERIAL PRIMARY KEY,
    customer_id INT REFERENCES customers(customer_id),
    order_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    total_amount NUMERIC(10, 2)
);

-- Insert sample rows
INSERT INTO categories (name) VALUES
('Smartphones'),
('Laptops'),
('Audio')
ON CONFLICT DO NOTHING;

INSERT INTO products (product_name, category, price, stock) VALUES
('Pixel 9 Pro', 'Smartphones', 999.00, 50),
('MacBook Pro M3', 'Laptops', 1999.00, 20),
('ThinkPad X1 Carbon', 'Laptops', 1450.00, 35),
('Dell XPS 15', 'Laptops', 1700.00, 15),
('Bose QuietComfort', 'Audio', 349.00, 100)
ON CONFLICT DO NOTHING;

INSERT INTO customers (first_name, last_name, email) VALUES
('Ada', 'Lovelace', 'ada@example.com'),
('Alan', 'Turing', 'alan@example.com'),
('Grace', 'Hopper', 'grace@example.com')
ON CONFLICT DO NOTHING;

INSERT INTO orders (order_id, customer_id, total_amount, order_date) VALUES
(1, 1, 999.00, pg_catalog.now() - INTERVAL '7 months'),
(2, 2, 349.00, pg_catalog.now() - INTERVAL '1 month')
ON CONFLICT DO NOTHING;

CREATE INDEX IF NOT EXISTS idx_products_category ON products(category);
CREATE INDEX IF NOT EXISTS idx_orders_customer ON orders(customer_id);
EOF

4. Uruchamianie serwera MCP Toolbox

W tej sekcji pobierzesz plik binarny MCP Toolbox, skonfigurujesz gotowe definicje narzędzi AlloyDB Omni i uruchomisz serwer MCP Toolbox.

Pobieranie MCP Toolbox

Utwórz katalog dla zestawu narzędzi MCP i pobierz plik binarny toolbox:

mkdir -p ~/mcp/tools
cd ~/mcp
curl -L -O https://storage.googleapis.com/genai-toolbox/v0.31.0/linux/amd64/toolbox
chmod +x toolbox
./toolbox --version

Konfigurowanie i uruchamianie serwera MCP Toolbox

Pobierz gotową konfigurację narzędzi alloydb-omni.yaml i uruchom serwer MCP Toolbox na porcie 5000 (używając wyeksportowanych wcześniej zmiennych środowiskowych ALLOYDB_OMNI_*):
```
curl -sL --create-dirs -o "tools/alloydb-omni.yaml" "https://raw.githubusercontent.com/googleapis/mcp-toolbox/v0.31.0/internal/prebuiltconfigs/tools/alloydb-omni.yaml"
# Remove the trailing group definition block and YAML document separator for --config-folder compatibility
sed -i '/^kind: group/,$d' tools/alloydb-omni.yaml
sed -i '${/---/d;}' tools/alloydb-omni.yaml

./toolbox --config-folder ./tools/ --port 5000 --address 127.0.0.1
```
Konfiguracja alloydb-omni.yaml udostępnia 31 gotowych narzędzi, w tym kluczowe narzędzia przedstawione w tym ćwiczeniu:
- execute_sql
- get_query_plan
- database_overview
- list_active_queries
- list_tables, list_indexes, list_views, list_triggers
- list_top_bloated_tables, list_locks, list_autovacuum_configurations, list_invalid_indexes
Pełną listę narzędzi znajdziesz w alloydb-omni.yaml na GitHubie.
Wskazówka: pozostaw serwer MCP Toolbox uruchomiony na tej karcie terminala i otwórz nową kartę terminala (+ w Cloud Shell), aby uruchomić pozostałe polecenia w tym ćwiczeniu.

Na nowej karcie terminala sprawdź, czy serwer MCP Toolbox działa i udostępnia narzędzia przez punkt końcowy JSON-RPC /mcp:

curl -X POST http://localhost:5000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

5. Konfigurowanie klienta MCP (Antigravity CLI)

W tej sekcji zainstalujesz Antigravity CLI (agy) i skonfigurujesz go tak, aby łączył się z serwerem MCP Toolbox.

Instalowanie Antigravity CLI

Jeśli nie masz jeszcze zainstalowanego interfejsu wiersza poleceń Antigravity (agy), pobierz go i uruchom instalator, a następnie sprawdź wersję:

curl -fsSL https://antigravity.google/cli/install.sh -o /tmp/install.sh
bash /tmp/install.sh
rm -f /tmp/install.sh

# If prompted by the installer, add ~/.local/bin to your PATH:
export PATH="$HOME/.local/bin:$PATH"

# Verify the installation
agy --version

Konfigurowanie Antigravity CLI

Dodaj wpis serwera MCP Toolbox do pliku konfiguracji MCP klienta (np. ~/.gemini/config/mcp_config.json w przypadku Antigravity CLI, .cursor/mcp.json, .vscode/mcp.json, claude_desktop_config.json lub .mcp.json w przypadku Claude Code).

Aby połączyć interfejs wiersza poleceń Antigravity z uruchomionym serwerem HTTP MCP Toolbox na porcie 5000, uruchom agy mcp add i zweryfikuj wpis za pomocą agy mcp list:
```
export MCP_SERVER="127.0.0.1"
export MCP_PORT="5000"

agy mcp add alloydb-omni "http://${MCP_SERVER}:${MCP_PORT}/mcp"
agy mcp list
```
Spowoduje to zapisanie konfiguracji serwera alloydb-omni w ~/.gemini/config/mcp_config.json:
```
{
  "mcpServers": {
    "alloydb-omni": {
      "url": "http://127.0.0.1:5000/mcp"
    }
  }
}
```

Potwierdź konfigurację

Uruchom Antigravity CLI:
```
agy
```
Jeśli uruchamiasz agy po raz pierwszy, postępuj zgodnie z instrukcjami na ekranie, aby się zalogować (za pomocą protokołu OAuth Google lub projektu w chmurze Google Cloud), i wybierz Tak, ufam temu folderowi, gdy pojawi się pytanie, czy ufasz bieżącemu katalogowi.

W wierszu poleceń interfejsu wiersza poleceń Antigravity wpisz /mcp, aby otworzyć panel Serwery MCP i sprawdzić, czy serwer alloydb-omni jest połączony:

/mcp

Dane wyjściowe są podobne do tych:

MCP Servers

Configured (~/.gemini/config/mcp_config.json)
>  ✓ alloydb-omni  Tools: database_overview, execute_sql, get_column_cardinality, get_query_plan, list_active_queries, +26 more

Keyboard: ↑/↓ Navigate  enter Actions

Naciśnij Esc, aby zamknąć panel Serwery MCP i wrócić do promptu interfejsu wiersza poleceń Antigravity.

6. Testowanie za pomocą zapytań dotyczących AlloyDB Omni

Teraz, gdy interfejs wiersza poleceń Antigravity jest połączony z instancją AlloyDB Omni za pomocą zestawu narzędzi MCP, możesz wchodzić w interakcje z bazą danych za pomocą promptów w języku naturalnym.

Uruchamianie zapytania z przeglądem bazy danych

W interfejsie wiersza poleceń Antigravity poproś o podsumowanie bieżącej bazy danych:

Give me an overview of the current database.

Gdy pojawi się prośba o zezwolenie na wywołanie narzędzia, wybierz Tak (lub Tak i zawsze zezwalaj w tej rozmowie). Dane wyjściowe są podobne do tych:

> Give me an overview of the current database.

● alloydb-omni/database_overview(Database overview check) (ctrl+o to expand)

  Here is an overview of the current AlloyDB Omni database instance:

  ### Database Overview
  • Instance / Engine: PostgreSQL 17.9 (AlloyDB Omni)
  • Role: Primary (is_replica: false)
  • Uptime: ~7 hours, 57 minutes
  • Connected Database: postgres
  • Connected User: postgres
  • Connections: 11 current / 100 max (1 active, 11% used)

  ### Databases in Instance
  • postgres
  • alloydbadmin (~15.74 MB)
  • alloydbmetadata (~14.82 MB)

Przykłady testów według kategorii

Wpisz w Antigravity CLI te prośby w języku naturalnym. Agent automatycznie mapuje każde żądanie na odpowiednie narzędzie w zestawie narzędzi MCP AlloyDB Omni:

1. Przegląd i stan bazy danych

Cel testu	Prompt w języku naturalnym	Wywołanie narzędzia
Sprawdzanie systemu	`Give me an overview of the current database.`	`database_overview`
Aktywne połączenia	`What queries are currently running on the database?`	`list_active_queries`
Zainstalowane rozszerzenia	`What extensions are installed in this database?`	`list_installed_extensions`
Dostępne rozszerzenia	`What extensions are available that I can install?`	`list_available_extensions`

2. Eksploracja schematu i katalogu

Cel testu	Prompt w języku naturalnym	Wywołanie narzędzia
Wyświetlanie listy tabel	`Show me all the tables in the current database.`	`list_tables`
Sprawdzanie indeksów	`List all indexes in the database and which tables they belong to.`	`list_indexes`
Widoki eksploracji	`What views are available in the public schema?`	`list_views`
Sprawdzanie aktywatorów tabeli	`Show me the triggers defined on the orders table.`	`list_triggers`

3. Zapytania i filtrowanie danych (`execute_sql`)

Cel testu	Prompt w języku naturalnym	Wywołanie narzędzia
Zapytanie zbiorcze	`Show me the 3 most expensive products in the 'Laptops' category.`	`execute_sql`
Zapytanie o dołączenie	`Find all customers who have placed an order in the last 6 months.`	`execute_sql`
Niedopasowane rekordy	`Which customers haven't placed any orders yet?`	`execute_sql`

4. Wydajność zapytań i plany wyjaśniające (`get_query_plan`)

Cel testu	Prompt w języku naturalnym	Wywołanie narzędzia
Wyjaśnij plan	`Explain the query plan for a query that finds all customers who have not placed an order in the last 6 months.`	`get_query_plan`
Weryfikacja indeksu	`Get the query plan for SELECT * FROM products WHERE category = 'Audio' and tell me if it uses the index.`	`get_query_plan`

5. Konserwacja i diagnostyka bazy danych

Cel testu	Prompt w języku naturalnym	Wywołanie narzędzia
Rozrost tabeli	`List the top five most bloated tables.`	`list_top_bloated_tables`
Rywalizacja o blokadę	`Show me if there are any active locks or blocked transactions.`	`list_locks`
Ustawienia autovacuum	`Show me the current autovacuum configuration.`	`list_autovacuum_configurations`
Nieprawidłowe indeksy	`Check for any invalid indexes in the database.`	`list_invalid_indexes`

7. Czyszczenie danych

Po ukończeniu ćwiczenia w programowaniu wyczyść lokalny kontener i uruchomione procesy.

Zamknij interfejs wiersza poleceń Antigravity, wpisując /quit (lub naciskając dwukrotnie Ctrl+D).
Przejdź na kartę terminala, na której działa serwer MCP Toolbox, i naciśnij Ctrl+C, aby go zatrzymać.
Zatrzymaj i usuń kontener Dockera AlloyDB Omni:
```
docker stop alloydbomni
docker rm alloydbomni
```

8. Gratulacje

Gratulujemy ukończenia tego ćwiczenia! Udało Ci się wdrożyć AlloyDB Omni w kontenerze, skonfigurować MCP Toolbox for Databases z gotowym zestawem narzędzi AlloyDB Omni i zintegrować go z Antigravity CLI, aby wykonywać zapytania i zarządzać bazą danych za pomocą języka naturalnego.

Omówione zagadnienia

jak wdrożyć i zweryfikować kontener AlloyDB Omni za pomocą Dockera;
Jak wypełnić przykładowe tabele i indeksy na potrzeby testowania Agentic Workflows.
Jak skonfigurować i uruchomić MCP Toolbox for Databases z gotową konfiguracją narzędzi alloydb-omni.
Jak połączyć interfejs wiersza poleceń Antigravity z zestawem narzędzi MCP i uruchamiać prompty w języku naturalnym do wykrywania schematów, wykonywania zapytań SQL, analizowania planów zapytań i diagnozowania baz danych.

Więcej informacji znajdziesz w tych materiałach:

9. Ankieta

Jak będziesz korzystać z tego samouczka?

Tylko przeczytałem(-am)

Przeczytałem(-am) i wykonałem(-am) ćwiczenia