Skip to content

gnodux/adb-link

BranchesTags

Repository files navigation

ADB-Link

Bridging AI Agents to Your Databases

A lightweight, high-performance database gateway designed for AI agents — providing unified SQL access, schema discovery, and tool orchestration across multiple database engines via REST API and MCP (Model Context Protocol).

Go MCP License Platform

📚 Documentation | English | 中文

Quick Install

# One-line install
curl -fsSL https://raw.githubusercontent.com/gnodux/adb-link/main/scripts/install-adb-link.sh | bash

# Or build from source (requires Go 1.22+)
git clone https://github.com/gnodux/adb-link.git
cd adb-link
make build

Demo

A complete workflow: discover datasources, explore schema, then execute queries — all via the MCP protocol.

# 1. List available datasources
curl -s -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {"name": "list_datasources", "arguments": {}}
  }'
# => [{"name":"my-postgres","type":"postgresql","description":"Production DB", ...}]

# 2. List databases in a datasource
curl -s -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "jsonrpc": "2.0", "id": 2, "method": "tools/call",
    "params": {"name": "list_databases", "arguments": {"datasource_name": "my-postgres"}}
  }'
# => [{"name":"mydb","comment":"Main application database"}, ...]

# 3. Get schema (tables & columns)
curl -s -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "jsonrpc": "2.0", "id": 3, "method": "tools/call",
    "params": {"name": "get_schema", "arguments": {"datasource_name": "my-postgres", "database": "mydb"}}
  }'
# => {"tables":[{"name":"users","columns":[{"name":"id","type":"INT4"},{"name":"username","type":"VARCHAR"}, ...]}]}

# 4. Execute a query
curl -s -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "jsonrpc": "2.0", "id": 5, "method": "tools/call",
    "params": {
      "name": "execute_query",
      "arguments": {
        "datasource_name": "my-postgres",
        "database": "mydb",
        "sql": "SELECT id, username, created_at FROM users ORDER BY created_at DESC LIMIT 10"
      }
    }
  }'
# => {"columns":[...],"rows":[[1,"alice","2026-03-15"], ...],"row_count":3}

Core Features

Feature Description
Multi-Database Support MySQL, PostgreSQL, ClickHouse, SQLite, SQL Server, Hive, Oracle, GaussDB, TiDB, Redis, MongoDB, Milvus, Elasticsearch
MCP Protocol Full JSON-RPC 2.0 implementation (stdio + HTTP transport)
Dynamic Tool Registry Register/unregister query tools at runtime via API or MCP
Dynamic Datasource Register/unregister datasources at runtime with connection validation
Async Query Engine Submit long-running queries, poll status, retrieve results
Schema Discovery Databases, tables, views, columns with type & comment info
Hot Reload YAML config changes are detected and applied within seconds
RBAC Permissions Glob-based access control on datasources, databases, tables, fields, and tools
Connection Health Auto-ping, periodic health checks, fail-fast on unreachable hosts
Pure Go Zero CGO dependencies — single static binary, cross-compile anywhere

Quick Start

Install (one-liner)

curl -fsSL https://raw.githubusercontent.com/gnodux/adb-link/main/scripts/install-adb-link.sh | bash

This installs the latest release to ~/.adb-link/ and creates a symlink at ~/.local/bin/adb-link.

Build from Source

git clone https://github.com/gnodux/adb-link.git
cd adb-link
make build
# Binary: bin/adb-link

Configure

Configuration files live in ~/.adb-link/conf/ by default (override via ADB_LINK_CONFIG_DIR).

# Copy example configs to get started
mkdir -p ~/.adb-link/conf
cp conf/mcp_stdio.yaml.example ~/.adb-link/conf/mcp_stdio.yaml
# Edit with your datasource details

Example datasource config:

kind: datasource
name: my-postgres
type: postgresql
description: "Production PostgreSQL"
connection:
  host: 127.0.0.1
  port: 5432
  username: app_user
  password: ${PG_PASSWORD}   # supports env var interpolation
  default_database: mydb
options:
  pool_size: 10

Authentication config:

kind: users
users:
  - name: admin
    api_key: "your-secret-api-key"
    group: admin
  - name: mcp_stdio_user
    group: mcp
    description: "Default user for MCP stdio transport"

Run

# API + MCP HTTP on a single port (default :8000)
adb-link run-all

# API only
adb-link run-api

# MCP over stdio (for IDE/agent integration)
adb-link run-mcp

Verify

curl http://localhost:8000/api/health
# {"status":"ok"}

MCP Integration

Claude Desktop / Cursor

Add to your MCP client configuration:

{
  "mcpServers": {
    "adb-link": {
      "command": "adb-link",
      "args": ["run-mcp"]
    }
  }
}

The stdio transport uses mcp_stdio_user as the default identity. Configure permissions for this user in your auth/permission YAML files.

HTTP Transport

For remote or multi-client access, use the HTTP transport:

adb-link run-all  # serves MCP at /mcp endpoint

Documentation

Architecture

┌─────────────────────────────────────────────────────┐
│                   AI Agent / Client                  │
└──────────┬─────────────────────────┬────────────────┘
           │ REST API                │ MCP (JSON-RPC)
           ▼                         ▼
┌──────────────────────────────────────────────────────┐
│                    ADB-Link Server                    │
│  ┌──────────┐ ┌───────────┐ ┌────────────────────┐  │
│  │  Router  │ │    MCP    │ │   Config Service   │  │
│  │  + Auth  │ │  Server   │ │  (Hot-Reload/YAML) │  │
│  └─────┬────┘ └─────┬─────┘ └────────────────────┘  │
│        │             │                               │
│  ┌─────▼─────────────▼───────────────────────────┐   │
│  │          Service Layer                        │   │
│  │  Schema · Query · Async · Permission · Meta   │   │
│  └──────────────────┬────────────────────────────┘   │
│                     │                                │
│  ┌──────────────────▼────────────────────────────┐   │
│  │         Connection Service (Pool + Health)    │   │
│  └──────────────────┬────────────────────────────┘   │
│                     │                                │
│  ┌──────────────────▼────────────────────────────┐   │
│  │   Dialect Layer (DSN Builder per DB engine)   │   │
│  └───────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────┘
           │         │         │         │
     ┌─────┘    ┌────┘    ┌────┘    ┌────┘
     ▼          ▼         ▼         ▼
  MySQL    PostgreSQL  ClickHouse  SQLite ...

API Endpoints

Method Path Description
GET /api/health Liveness check
POST /api/datasources/list List datasources
POST /api/datasources/detail Datasource details
POST /api/datasources/test Test connectivity
POST /api/datasources/register Register datasource
POST /api/datasources/unregister Unregister datasource
POST /api/databases/list List databases
POST /api/schema/get Full schema
POST /api/schema/table Table info
POST /api/schema/view View info
POST /api/query/execute Execute SQL
POST /api/query/explain Explain plan
POST /api/async/query/submit Async query submit
POST /api/async/query/status Async query status
POST /api/async/query/result Async query result
POST /api/async/query/cancel Cancel async query
GET /api/tools List registered tools
POST /api/tool/register Register tool
POST /api/tool/unregister Unregister tool
POST /api/tool/{name} Execute tool
POST /mcp MCP JSON-RPC endpoint

MCP Tools

All MCP tools are available via tools/call:

  • list_datasources — List all datasources
  • list_databases — List databases in a datasource
  • get_schema — Get full schema
  • get_table_info / get_view_info — Column details
  • execute_query — Run SQL/DSL
  • explain_query — Execution plan
  • submit_async_query — Async query
  • get_async_query_status / get_async_query_result — Poll async results
  • register_tool / unregister_tool — Dynamic tool management
  • register_datasource / unregister_datasource — Dynamic datasource management
  • Any dynamically registered tool

Configuration

All configuration is YAML-based in the config directory (~/.adb-link/conf/ by default):

File Kind Purpose
datasource.yaml datasource Database connection definitions
auth.yaml users API keys and users
permission-*.yaml permission RBAC rules
tool-*.yaml tool Custom query tools
metadata-*.yaml metadata Column/table comments
mcp_stdio.yaml mixed MCP stdio default config (auth + permissions + datasources)

Environment variables are supported via ${VAR_NAME} syntax. Configuration changes are hot-reloaded automatically.

Environment Variables

Variable Default Description
ADB_LINK_CONFIG_DIR ~/.adb-link/conf Config directory path
ADB_LINK_API_HOST 0.0.0.0 API bind address
ADB_LINK_API_PORT 8000 API bind port
ADB_LINK_LOG_LEVEL INFO Log level
ADB_LINK_LOG_DIR ~/.adb-link/logs Log directory
ADB_LINK_RELOAD true Enable hot-reload
ADB_LINK_ASYNC_QUERY_TTL 3600 Async result TTL (seconds)

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

# Development workflow
make fmt       # Format code
make vet       # Run tests
make test      # Run tests
make build     # Build binary

License

MIT

If you find ADB-Link useful, please give it a star!

About

An MCP server that connects to multiple databases. Supports access control and dynamic SQL query tool registration and invocation.

Topics

go agent mcp data-analysis ai-tools database-gateway mcp-server

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 13

adb-link v1.0.13 Latest
Jun 8, 2026
+ 12 releases

Packages

 
 
 

Contributors

Languages