a2db

Agent: "Show me active users and their recent orders"
  ↓
a2db execute → 2 queries, 1 call, structured results
  ↓
Agent: "Got it — 847 active users, avg order $42.50"

Почему a2db?

Большинство MCP-серверов для баз данных заставляют вас выполнять по одному запросу за раз, повторять данные подключения при каждом вызове и возвращать результаты, дважды закодированные внутри JSON-строк. a2db решает все эти проблемы:

• Предварительно настроенные подключения — определяйте базы данных в .mcp.json с помощью --register, и агент сможет выполнять запросы немедленно.

• Пакетные запросы — выполняйте несколько именованных запросов за один вызов инструмента.

• Подключение по умолчанию — установите подключение один раз и используйте его для всех запросов в пакете.

• Чистый вывод — структурированный JSON-конверт с компактными данными в формате TSV и временем выполнения каждого запроса (см. почему TSV?).

• Принудительный режим только для чтения — парсинг AST через SQLGlot блокирует все операции записи.

• Все драйверы в комплекте — pip install a2db и готово.

• Секреты остаются в переменных окружения — ${DB_PASSWORD} в DSN раскрывается только во время подключения.

Поддерживаемые базы данных

Быстрый старт

pip install a2db

Как MCP-сервер (рекомендуется)

Claude Code (с предварительно настроенным подключением):

claude mcp add -s user a2db -- a2db-mcp \
  --register myapp/prod/main 'postgresql://user:${DB_PASSWORD}@host/mydb'

Claude Code (минимальный вариант — агент вызывает login по требованию):

claude mcp add -s user a2db -- a2db-mcp

Claude Desktop / Cursor / любой MCP-клиент (.mcp.json):

{
  "mcpServers": {
    "a2db": {
      "command": "uvx",
      "args": [
        "a2db-mcp",
        "--register", "myapp/prod/main", "postgresql://user:${DB_PASSWORD}@host/mydb"
      ],
      "env": {
        "DB_PASSWORD": "your-password-here"
      }
    }
  }
}

Несколько баз данных:

{
  "args": [
    "a2db-mcp",
    "--register", "myapp/prod/main", "postgresql://user:${DB_PASSWORD}@host/maindb",
    "--register", "myapp/prod/analytics", "postgresql://user:${DB_PASSWORD}@host/analytics"
  ]
}

--register предварительно регистрирует подключения при запуске сервера — агент может выполнять запросы немедленно. Пароли используют синтаксис ${ENV_VAR} и раскрываются во время подключения, никогда не сохраняясь в открытом виде.

Как CLI

# Save a connection (validates immediately)
a2db login -p myapp -e prod -d main 'postgresql://user:${DB_PASSWORD}@localhost/mydb'

# Query
a2db query -p myapp -e prod -d main "SELECT * FROM users LIMIT 10"

# JSON output
a2db query -p myapp -e prod -d main -f json "SELECT * FROM users LIMIT 10"

# Explore schema
a2db schema -p myapp -e prod -d main tables
a2db schema -p myapp -e prod -d main columns -t users

# List / remove connections
a2db connections
a2db logout -p myapp -e prod -d main

Инструменты MCP

execute — основной инструмент

Именованный словарь с подключением по умолчанию (предпочтительно):

{
  "connection": {"project": "myapp", "env": "prod", "db": "main"},
  "queries": {
    "active_users": {"sql": "SELECT id, name FROM users WHERE active = true"},
    "recent_orders": {"sql": "SELECT id, total FROM orders ORDER BY created_at DESC LIMIT 5"}
  }
}

Формат списка (автоматические имена q1, q2, ...):

{
  "connection": {"project": "myapp", "env": "prod", "db": "main"},
  "queries": [
    {"sql": "SELECT COUNT(*) AS cnt FROM users"},
    {"sql": "SELECT AVG(total) AS avg_order FROM orders"}
  ]
}

Ответ (формат TSV — по умолчанию):

{
  "active_users": {
    "data": "id\tname\n1\tAlice\n2\tBob\n3\tCharlie",
    "rows": 3,
    "truncated": false,
    "time_ms": 12
  },
  "recent_orders": {
    "data": "id\ttotal\n501\t129.00\n500\t49.99",
    "rows": 2,
    "truncated": false,
    "time_ms": 8
  }
}

Приведение типов ::text не требуется — целые числа, числа с плавающей точкой, временные метки, массивы и NULL работают нативно.

Контекст ошибки

Когда запрос завершается ошибкой столбца, a2db дополняет сообщение:

column "nme" does not exist
Did you mean: name?
Available columns: id (integer), name (text), email (text), active (integer)

Почему TSV?

Контекстные окна LLM стоят дорого. JSON-данные строк многословны — каждая строка повторяет имя каждого столбца, добавляет фигурные скобки, запятые и кавычки. TSV — это плоская сетка: одна строка заголовка, затем только значения, разделенные табуляцией.

Для набора из 100 строк и 5 столбцов TSV обычно использует на 40-60% меньше токенов, чем формат JSON. Структурированный JSON-конверт по-прежнему предоставляет метаданные (количество строк, статус усечения) — только полезная нагрузка строк представлена в TSV.

Установите format="json", если вам нужен полный структурированный вывод с именами столбцов в каждой строке.

Безопасность

Принудительный режим только для чтения

Каждый запрос перед выполнением парсится с помощью SQLGlot:

• Заблокировано: INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER, CREATE, GRANT, REVOKE

• Защита от обхода: атаки с несколькими операторами и записи, обернутые в комментарии, перехватываются на уровне AST, а не просто по ключевым словам

• Разрешено: SELECT, UNION, EXPLAIN, SHOW, DESCRIBE, PRAGMA

Это глубокоэшелонированная защита — вам также следует использовать пользователя базы данных с правами только для чтения, но a2db не пропустит запись, даже если у пользователя есть права на запись.

Поддержка записи реализована в ядре, но еще не представлена через MCP. В планах: права на запись для каждого подключения, явно включаемые оператором-человеком, а не агентом. См. TODO.md.

Хранение учетных данных

Подключения сохраняются в ~/.config/a2db/connections/ в виде файлов TOML.

• Синтаксис ${DB_PASSWORD} — ссылки на переменные окружения хранятся буквально и раскрываются только во время подключения. Секреты остаются в вашей среде, а не на диске.

• Никаких секретов в выводе списка — list_connections показывает проект/среду/базу данных и тип базы данных, но никогда не показывает DSN или пароли.

• Файлы подключений локальны для вашей машины и находятся вне любого репозитория.

Область развертывания

a2db в настоящее время работает как локальный stdio MCP-сервер. Он наследует переменные окружения от процесса, который его запускает (ваша оболочка, Claude Code, Docker). Это стандартная модель для локальных MCP-серверов — такой же подход используют DBHub, Google Toolbox и другие.

В планах: удаленный HTTP-транспорт с OAuth 2.1 согласно спецификации MCP. Пока что, при запуске в Docker, внедряйте секреты через переменные окружения во время выполнения контейнера.

Сравнение

Что и когда использовать:

• a2db — пакетные запросы к нескольким БД с чистым выводом, дизайн «агент прежде всего», быстрая настройка

• DBHub — пользовательские инструменты через конфиг TOML, веб-интерфейс

• Google Toolbox — экосистема GCP, интеграция с IAM, 40+ источников

• PGMCP — естественный язык в SQL для PostgreSQL (требуется ключ OpenAI)

• Supabase MCP — полное управление платформой Supabase (edge-функции, ветвление, хранилище)

Настройка по среде

Локально (macOS / Linux)

pip install a2db

# CLI
a2db login -p myapp -e dev -d main 'postgresql://user:pass@localhost/mydb'

# Or add as MCP server (see Quick Start)

Docker

FROM python:3.12-slim
RUN pip install a2db
CMD ["a2db-mcp", "--register", "myapp/prod/main", "postgresql://user:${DB_PASSWORD}@host/mydb"]

docker run -e DB_PASSWORD=secret -i my-a2db-image

Секреты внедряются как переменные окружения во время выполнения — никогда не вшиваются в образ.

CI / Автоматизация

pip install a2db

# Pre-configured — no login needed
a2db-mcp --register myapp/ci/main "postgresql://ci_user:${CI_DB_PASSWORD}@db-host/mydb"

# Or use CLI directly
a2db login -p myapp -e ci -d main "postgresql://ci_user:${CI_DB_PASSWORD}@db-host/mydb"
a2db query -p myapp -e ci -d main "SELECT COUNT(*) FROM migrations"

Разработка

make bootstrap   # Install deps + hooks
make check       # Lint + test + security (full gate)
make test        # Tests with coverage (90% minimum)
make lint        # Lint only (never modifies files)
make fix         # Auto-fix + lint

Лицензия

Apache 2.0