{"id":42811194,"url":"https://github.com/zx06/xsql","last_synced_at":"2026-04-02T11:47:03.616Z","repository":{"id":335287395,"uuid":"1144848337","full_name":"zx06/xsql","owner":"zx06","description":"🤖 AI-first cross-database CLI tool. Query MySQL/PostgreSQL safely with read-only protection, SSH tunneling, and structured JSON output.","archived":false,"fork":false,"pushed_at":"2026-03-23T01:37:26.000Z","size":278,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T04:16:42.994Z","etag":null,"topics":["ai","cli","mysql","pg","sql"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zx06.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-29T05:42:59.000Z","updated_at":"2026-03-09T03:30:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zx06/xsql","commit_stats":null,"previous_names":["zx06/xsql"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/zx06/xsql","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zx06%2Fxsql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zx06%2Fxsql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zx06%2Fxsql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zx06%2Fxsql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zx06","download_url":"https://codeload.github.com/zx06/xsql/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zx06%2Fxsql/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31305809,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T09:48:21.550Z","status":"ssl_error","status_checked_at":"2026-04-02T09:48:19.196Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cli","mysql","pg","sql"],"created_at":"2026-01-30T05:08:12.217Z","updated_at":"2026-04-02T11:47:03.610Z","avatar_url":"https://github.com/zx06.png","language":"Go","readme":"# xsql\n\n[![CI](https://github.com/zx06/xsql/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/zx06/xsql/actions/workflows/ci.yml?query=branch%3Amain)\n[![codecov](https://codecov.io/github/zx06/xsql/graph/badge.svg?token=LrcR0pifCj)](https://codecov.io/github/zx06/xsql)\n[![Go Reference](https://pkg.go.dev/badge/github.com/zx06/xsql.svg)](https://pkg.go.dev/github.com/zx06/xsql)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/zx06/xsql)](https://github.com/zx06/xsql/blob/main/go.mod)\n[![Go Report Card](https://goreportcard.com/badge/github.com/zx06/xsql)](https://goreportcard.com/report/github.com/zx06/xsql)\n[![License](https://img.shields.io/github/license/zx06/xsql)](https://github.com/zx06/xsql/blob/main/LICENSE)\n[![Release](https://img.shields.io/github/v/release/zx06/xsql)](https://github.com/zx06/xsql/releases/latest)\n[![GitHub Downloads](https://img.shields.io/github/downloads/zx06/xsql/total)](https://github.com/zx06/xsql/releases)\n[![npm](https://img.shields.io/npm/v/xsql-cli)](https://www.npmjs.com/package/xsql-cli)\n[![npm downloads](https://img.shields.io/npm/dm/xsql-cli)](https://www.npmjs.com/package/xsql-cli)\n\n**Let AI safely query your databases** 🤖🔒\n\n[中文文档](README_zh.md)\n\nxsql is a cross-database CLI tool designed for AI agents. Read-only by default, structured output, ready out of the box.\n\n```bash\n# AI can query your database like this\nxsql query \"SELECT * FROM users WHERE created_at \u003e '2024-01-01'\" -p prod -f json\n```\n\n## ✨ Why xsql?\n\n| Feature | Description |\n|---------|-------------|\n| 🔒 **Safe by Default** | Dual-layer read-only protection prevents accidental writes by AI |\n| 🤖 **AI-first** | JSON structured output designed for machine consumption |\n| 🔑 **Secure Credentials** | OS Keyring integration — passwords never touch disk |\n| 🌐 **SSH Tunneling** | One-line config to connect to internal databases |\n| 📦 **Zero Dependencies** | Single binary, works out of the box |\n\n## 🚀 Quick Start\n\n### 1. Install\n\n```bash\n# macOS\nbrew install zx06/tap/xsql\n\n# Windows\nscoop bucket add zx06 https://github.com/zx06/scoop-bucket \u0026\u0026 scoop install xsql\n\n# npm / npx\nnpm install -g xsql-cli\n\n# Or download directly: https://github.com/zx06/xsql/releases\n```\n\n### 2. Configure\n\n```bash\nmkdir -p ~/.config/xsql\ncat \u003e ~/.config/xsql/xsql.yaml \u003c\u003c 'EOF'\nprofiles:\n  dev:\n    db: mysql\n    host: 127.0.0.1\n    port: 3306\n    user: root\n    password: your_password\n    database: mydb\n    allow_plaintext: true  # Use keyring for production\nEOF\n```\n\n### 3. Use\n\n```bash\nxsql query \"SELECT 1\" -p dev -f json\n# {\"ok\":true,\"schema_version\":1,\"data\":{\"columns\":[\"1\"],\"rows\":[{\"1\":1}]}}\n```\n\n---\n\n## 🤖 Let AI Use xsql\n\n### Option 1: Claude Code Plugin (Recommended)\n\n```bash\n# 1. Add marketplace\n/plugin marketplace add zx06/xsql\n\n# 2. Install plugin\n/plugin install xsql@xsql\n```\n\nAfter installation, Claude automatically gains xsql skills and can query databases directly.\n\n### Option 2: Copy Skill Prompt to Any AI\n\nSend the following to your AI assistant (ChatGPT/Claude/Cursor, etc.):\n\n\u003cdetails\u003e\n\u003csummary\u003e📋 Click to expand AI Skill Prompt (copy \u0026 paste)\u003c/summary\u003e\n\n```\nYou can now use the xsql tool to query databases.\n\n## Basic Usage\nxsql query \"\u003cSQL\u003e\" -p \u003cprofile\u003e -f json\n\n## Available Commands\n- xsql query \"SQL\" -p \u003cprofile\u003e -f json  # Execute query\n- xsql schema dump -p \u003cprofile\u003e -f json  # Export database schema\n- xsql profile list -f json               # List all profiles\n- xsql profile show \u003cname\u003e -f json        # Show profile details\n\n## Output Format\nSuccess: {\"ok\":true,\"schema_version\":1,\"data\":{\"columns\":[...],\"rows\":[...]}}\nFailure: {\"ok\":false,\"schema_version\":1,\"error\":{\"code\":\"XSQL_...\",\"message\":\"...\"}}\n\n## Important Rules\n1. Read-only mode by default — cannot execute INSERT/UPDATE/DELETE\n2. Always use -f json for structured output\n3. Use profile list to see available database configurations\n4. Check the ok field to determine execution success\n\n## Exit Codes\n0=success, 2=config error, 3=connection error, 4=read-only violation, 5=SQL execution error\n```\n\n\u003c/details\u003e\n\n### Option 3: MCP Server (Claude Desktop, etc.)\n\nAdd the xsql MCP server to your Claude Desktop configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"xsql\": {\n      \"command\": \"xsql\",\n      \"args\": [\"mcp\", \"server\", \"--config\", \"/path/to/xsql.yaml\"]\n    }\n  }\n}\n```\n\nOnce started, Claude can query databases directly via the MCP protocol.\n\n### Option 4: AGENTS.md / Rules (Cursor/Windsurf)\n\nCreate `.cursor/rules` or edit `AGENTS.md` in your project root:\n\n```markdown\n## Database Queries\n\nUse xsql to query databases:\n- Query: `xsql query \"SELECT ...\" -p \u003cprofile\u003e -f json`\n- Export schema: `xsql schema dump -p \u003cprofile\u003e -f json`\n- List profiles: `xsql profile list -f json`\n\nNote: Read-only mode by default. Write operations require the --unsafe-allow-write flag.\n```\n\n---\n\n## 📖 Features\n\n### Command Reference\n\n| Command | Description |\n|---------|-------------|\n| `xsql query \u003cSQL\u003e` | Execute SQL queries (read-only by default) |\n| `xsql schema dump` | Export database schema (tables, columns, indexes, foreign keys) |\n| `xsql profile list` | List all profiles |\n| `xsql profile show \u003cname\u003e` | Show profile details (passwords are masked) |\n| `xsql mcp server` | Start MCP Server (AI assistant integration) |\n| `xsql spec` | Export AI Tool Spec (supports `--format yaml`) |\n| `xsql version` | Show version information |\n\n### Output Formats\n\n```bash\n# JSON (for AI/programs)\nxsql query \"SELECT id, name FROM users\" -p dev -f json\n{\"ok\":true,\"schema_version\":1,\"data\":{\"columns\":[\"id\",\"name\"],\"rows\":[{\"id\":1,\"name\":\"Alice\"}]}}\n\n# Table (for terminals)\nxsql query \"SELECT id, name FROM users\" -p dev -f table\nid  name\n--  -----\n1   Alice\n\n(1 rows)\n```\n\n### Schema Discovery (AI auto-understands your database)\n\n```bash\n# Export database schema (for AI to understand table structures)\nxsql schema dump -p dev -f json\n\n# Filter specific tables\nxsql schema dump -p dev --table \"user*\" -f json\n\n# Example output\n{\n  \"ok\": true,\n  \"data\": {\n    \"database\": \"mydb\",\n    \"tables\": [\n      {\n        \"name\": \"users\",\n        \"columns\": [\n          {\"name\": \"id\", \"type\": \"bigint\", \"primary_key\": true},\n          {\"name\": \"email\", \"type\": \"varchar(255)\", \"nullable\": false}\n        ]\n      }\n    ]\n  }\n}\n```\n\n### SSH Tunnel Connection\n\n```yaml\nssh_proxies:\n  bastion:\n    host: jump.example.com\n    user: admin\n    identity_file: ~/.ssh/id_ed25519\n\nprofiles:\n  prod:\n    db: pg\n    host: db.internal  # Internal network address\n    port: 5432\n    user: readonly\n    password: \"keyring:prod/password\"\n    database: mydb\n    ssh_proxy: bastion  # Reference SSH proxy\n```\n\n### Port Forwarding Proxy (xsql proxy)\n\nWhen you need traditional `ssh -L` behavior or want to expose a local port for GUI clients, use `xsql proxy`:\n\n```bash\n# Start port forwarding (auto-assign local port)\nxsql proxy -p prod\n\n# Specify local port\nxsql proxy -p prod --local-port 13306\n```\n\n\u003e This command requires the profile to have `ssh_proxy` configured. It listens on a local port and forwards traffic to the target database.\n\n### Security Features\n\n- **Dual-layer Read-only Protection**: SQL static analysis + database transaction-level read-only\n- **Keyring Integration**: `password: \"keyring:prod/password\"`\n- **Password Masking**: `profile show` never exposes passwords\n- **SSH Security**: known_hosts verification enabled by default\n\n---\n\n## 📚 Documentation\n\n| Document | Description |\n|----------|-------------|\n| [CLI Specification](docs/cli-spec.md) | Detailed CLI interface reference |\n| [Configuration Guide](docs/config.md) | Config file format and options |\n| [SSH Proxy](docs/ssh-proxy.md) | SSH tunnel configuration |\n| [Error Handling](docs/error-contract.md) | Error codes and exit codes |\n| [AI Integration](docs/ai.md) | MCP Server and AI assistant integration |\n| [RFC Documents](docs/rfcs/) | Design change records |\n| [Development Guide](docs/dev.md) | Contributing and development notes |\n\n---\n\n## License\n\n[MIT](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzx06%2Fxsql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzx06%2Fxsql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzx06%2Fxsql/lists"}