{"id":39589416,"url":"https://github.com/tobilg/text-to-sql-proxy","last_synced_at":"2026-01-21T16:00:37.394Z","repository":{"id":333193640,"uuid":"1134816549","full_name":"tobilg/text-to-sql-proxy","owner":"tobilg","description":"A local HTTP proxy that bridges web applications with AI CLI tools to generate SQL queries for different databases","archived":false,"fork":false,"pushed_at":"2026-01-18T22:24:52.000Z","size":63,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-20T21:57:51.797Z","etag":null,"topics":[],"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/tobilg.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":null,"dco":null,"cla":null}},"created_at":"2026-01-15T08:43:34.000Z","updated_at":"2026-01-20T10:34:19.000Z","dependencies_parsed_at":"2026-01-19T14:01:48.043Z","dependency_job_id":null,"html_url":"https://github.com/tobilg/text-to-sql-proxy","commit_stats":null,"previous_names":["tobilg/ai-cli-proxy"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/tobilg/text-to-sql-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Ftext-to-sql-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Ftext-to-sql-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Ftext-to-sql-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Ftext-to-sql-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tobilg","download_url":"https://codeload.github.com/tobilg/text-to-sql-proxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Ftext-to-sql-proxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28635926,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T15:01:31.228Z","status":"ssl_error","status_checked_at":"2026-01-21T14:42:58.942Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":[],"created_at":"2026-01-18T07:41:50.168Z","updated_at":"2026-01-21T16:00:37.366Z","avatar_url":"https://github.com/tobilg.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# text-to-sql-proxy\n\nA local HTTP proxy that bridges web applications with AI CLI tools to generate SQL queries for your target database (configurable, defaults to DuckDB).\n\n## Overview\n\nThis proxy allows browser-based applications (like [sql-workbench.com](https://sql-workbench.com)) to leverage your local AI CLI subscriptions for SQL generation. It accepts DDL schemas and natural language questions, then returns SQL queries for the configured target database.\n\n### How It Works\n\n```\n┌─────────────────┐     HTTP POST      ┌────────────────────┐     exec      ┌───────────────┐\n│   Web Browser   │ ─────────────────► │  text-to-sql-proxy │ ────────────► │    AI CLI     │\n│ (sql-workbench) │ ◄───────────────── │  localhost:4000    │ ◄──────────── │ (claude/etc.) │\n└─────────────────┘     SQL Response   └────────────────────┘    Response   └───────────────┘\n```\n\n### Supported Providers\n\n| Provider    | CLI Command | Install |\n|-------------|-------------|---------|\n| Claude Code | `claude` | [Installation Guide](https://docs.anthropic.com/en/docs/claude-cli) |\n| Google Gemini | `gemini` | [Installation Guide](https://geminicli.com/docs/installation) |\n| OpenAI Codex | `codex` | [Installation Guide](https://developers.openai.com/codex/cli/installation) |\n| Continue | `cn` | `npm i -g @continuedev/cli` |\n| OpenCode | `opencode` | [Installation Guide](https://opencode.ai/docs/cli) |\n\n## Installation\n\n### Homebrew (macOS Apple Silicon)\n\n```bash\nbrew tap tobilg/text-to-sql-proxy\nbrew install text-to-sql-proxy\n```\n\nAfter installation, you can run it as a service:\n```bash\nbrew services start text-to-sql-proxy\n```\n\nOr run it manually:\n```bash\ntext-to-sql-proxy\n```\n\n### Build from source\n\n```bash\n# Clone the repository\ngit clone https://github.com/tobilg/text-to-sql-proxy.git\ncd text-to-sql-proxy\n\n# Build for your platform\nmake build\n\n# Or build for all platforms\nmake build-all\n```\n\n### Pre-built binaries\n\nDownload the appropriate binary for your platform from the [releases page](https://github.com/tobilg/text-to-sql-proxy/releases):\n\n| Platform | Binary |\n|----------|--------|\n| Windows | `text-to-sql-proxy-windows-amd64.exe` |\n| Linux | `text-to-sql-proxy-linux-amd64` |\n| macOS (Apple Silicon) | `text-to-sql-proxy-darwin-arm64` |\n\n## Usage\n\n### Prerequisites\n\nAt least one of these CLI tools must be installed and authenticated:\n\n```bash\n# Claude CLI (Anthropic)\n# Follow: https://docs.anthropic.com/en/docs/claude-cli\n\n# Gemini CLI (Google)\n# Follow: https://geminicli.com/docs/installation\n\n# Codex CLI (OpenAI)\n# Follow: https://developers.openai.com/codex/cli/installation\n\n# Continue CLI\nnpm i -g @continuedev/cli\n\n# OpenCode CLI\n# Follow: https://opencode.ai/docs/cli\n```\n\n### Running the proxy\n\n```bash\n# Run with default settings (Claude provider)\n./dist/text-to-sql-proxy\n\n# Run with a specific default provider\nTEXT_TO_SQL_PROXY_PROVIDER=gemini ./dist/text-to-sql-proxy\nTEXT_TO_SQL_PROXY_PROVIDER=codex ./dist/text-to-sql-proxy\nTEXT_TO_SQL_PROXY_PROVIDER=continue ./dist/text-to-sql-proxy\nTEXT_TO_SQL_PROXY_PROVIDER=opencode ./dist/text-to-sql-proxy\n\n# Run with custom port\nTEXT_TO_SQL_PROXY_PORT=8080 ./dist/text-to-sql-proxy\n\n# Run with custom allowed origin\nTEXT_TO_SQL_PROXY_ALLOWED_ORIGIN=\"http://localhost:3000\" ./dist/text-to-sql-proxy\n\n# Run with a different target database (e.g., PostgreSQL)\nTEXT_TO_SQL_PROXY_DATABASE=PostgreSQL ./dist/text-to-sql-proxy\n\n# Run with HTTPS/TLS (requires certificate and key files)\nTEXT_TO_SQL_PROXY_TLS_CERT=/path/to/cert.pem TEXT_TO_SQL_PROXY_TLS_KEY=/path/to/key.pem ./dist/text-to-sql-proxy\n```\n\nThe proxy will start and display (with default settings):\n\n```\nText-to-SQL Proxy active at http://localhost:4000\nDefault provider: claude\nTarget database: DuckDB\nAllowed origin: https://sql-workbench.com\nAvailable providers: claude, gemini, codex, continue, opencode\nAPI docs: http://localhost:4000/openapi.json\nPress Ctrl+C to stop\n```\n\n### Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `TEXT_TO_SQL_PROXY_PORT` | `4000` | Port the proxy listens on |\n| `TEXT_TO_SQL_PROXY_ALLOWED_ORIGIN` | `https://sql-workbench.com` | CORS allowed origin |\n| `TEXT_TO_SQL_PROXY_PROVIDER` | `claude` | Default AI provider |\n| `TEXT_TO_SQL_PROXY_DATABASE` | `DuckDB` | Target database for SQL generation |\n| `TEXT_TO_SQL_PROXY_TLS_CERT` | - | Path to TLS certificate file (enables HTTPS) |\n| `TEXT_TO_SQL_PROXY_TLS_KEY` | - | Path to TLS private key file (enables HTTPS) |\n\nValid providers: `claude`, `gemini`, `codex`, `continue`, `opencode`\n\n### HTTPS/TLS Support\n\nTo run the proxy over HTTPS (required for Safari and strict browser security), provide both TLS certificate and key files:\n\n```bash\n# Generate self-signed certificates with mkcert (recommended for local development)\n# Install mkcert: https://github.com/FiloSottile/mkcert\nmkcert -install\nmkcert localhost 127.0.0.1 ::1\n\n# Run with the generated certificates\nTEXT_TO_SQL_PROXY_TLS_CERT=localhost+2.pem TEXT_TO_SQL_PROXY_TLS_KEY=localhost+2-key.pem ./dist/text-to-sql-proxy\n```\n\nWhen TLS is enabled, the proxy will display:\n```\nText-to-SQL Proxy active at https://localhost:4000\n...\nTLS enabled: cert=localhost+2.pem, key=localhost+2-key.pem\n```\n\n## API\n\n### GET /health\n\nHealth check endpoint to verify the proxy is running.\n\n**Example Request:**\n\n```bash\ncurl http://localhost:4000/health\n```\n\n**Example Response (200):**\n\nEmpty response with HTTP status 200.\n\n---\n\n### GET /openapi.json\n\nReturns the OpenAPI v3 specification for this API.\n\n**Example Request:**\n\n```bash\ncurl http://localhost:4000/openapi.json\n```\n\n**Example Response (200):**\n\n```json\n{\n  \"openapi\": \"3.0.3\",\n  \"info\": {\n    \"title\": \"Text-to-SQL Proxy API\",\n    \"version\": \"1.0.0\"\n  },\n  \"paths\": { ... }\n}\n```\n\n---\n\n### GET /providers\n\nReturns the list of available AI providers with their descriptions.\n\n**Example Request:**\n\n```bash\ncurl http://localhost:4000/providers\n```\n\n**Example Response (200):**\n\n```json\n{\n  \"providers\": [\n    {\"name\": \"claude\", \"description\": \"Claude Code\"},\n    {\"name\": \"gemini\", \"description\": \"Google Gemini\"},\n    {\"name\": \"codex\", \"description\": \"OpenAI Codex\"},\n    {\"name\": \"continue\", \"description\": \"Continue\"},\n    {\"name\": \"opencode\", \"description\": \"OpenCode\"}\n  ]\n}\n```\n\n---\n\n### POST /generate-sql\n\nGenerate a SQL query for the configured target database from a schema and natural language question.\n\n**Request Body:**\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `ddl` | string | Yes | DDL schema (CREATE TABLE statements) |\n| `question` | string | Yes | Natural language question |\n| `provider` | string | No | AI provider to use (defaults to configured provider) |\n\n**Example Request:**\n\n```bash\ncurl -X POST http://localhost:4000/generate-sql \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"ddl\": \"CREATE TABLE users (id INT, name TEXT, email TEXT);\",\n    \"question\": \"Find all users whose name starts with A\"\n  }'\n```\n\n**Example Response (200):**\n\n```json\n{\n  \"sql\": \"SELECT * FROM users WHERE name LIKE 'A%'\"\n}\n```\n\n**Example Request with Provider Override:**\n\n```bash\ncurl -X POST http://localhost:4000/generate-sql \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"ddl\": \"CREATE TABLE orders (id INT, user_id INT, total DECIMAL, created_at TIMESTAMP);\",\n    \"question\": \"Calculate total sales per month\",\n    \"provider\": \"gemini\"\n  }'\n```\n\n**Example Response (200):**\n\n```json\n{\n  \"sql\": \"SELECT DATE_TRUNC('month', created_at) AS month, SUM(total) AS total_sales FROM orders GROUP BY month ORDER BY month\"\n}\n```\n\n**Error Responses:**\n\n| Status | Description | Example |\n|--------|-------------|---------|\n| 400 | Invalid JSON or missing required fields | `{\"error\": \"Both 'ddl' and 'question' fields are required\"}` |\n| 400 | Unknown provider | `{\"error\": \"Unknown provider: invalid\"}` |\n| 405 | Method not allowed | `{\"error\": \"Method not allowed\"}` |\n| 500 | AI CLI execution failed | `{\"error\": \"Failed to generate SQL\"}` |\n\n## Development\n\n### Running tests\n\n```bash\nmake test\n```\n\n### Build commands\n\n```bash\nmake build              # Build for current platform\nmake build-all          # Build for all platforms\nmake build-windows      # Build for Windows\nmake build-linux        # Build for Linux\nmake build-darwin-amd64 # Build for macOS Intel\nmake build-darwin-arm64 # Build for macOS Apple Silicon\nmake clean              # Remove build artifacts\n```\n\n### Project structure\n\n```\ntext-to-sql-proxy/\n├── src/\n│   ├── cmd/text-to-sql-proxy/    # Application entry point\n│   └── internal/\n│       ├── config/          # Configuration loading\n│       ├── handler/         # HTTP handlers\n│       └── provider/        # AI CLI provider implementations\n├── dist/                    # Built binaries\n├── Makefile\n└── README.md\n```\n\n## Browser Security Notes\n\nModern browsers enforce strict security policies for requests from HTTPS sites to local HTTP servers. This proxy includes:\n\n- **CORS headers** for cross-origin requests\n- **Private Network Access** header (`Access-Control-Allow-Private-Network: true`) for browser compatibility\n- **Optional HTTPS/TLS support** for browsers with strict mixed content policies (like Safari)\n\n**Recommended:** Use HTTPS with [mkcert](https://github.com/FiloSottile/mkcert) for the best browser compatibility (see [HTTPS/TLS Support](#httpstls-support)).\n\n**Alternative for Chrome:** Enable `chrome://flags/#allow-insecure-localhost` to allow HTTP connections to localhost.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobilg%2Ftext-to-sql-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftobilg%2Ftext-to-sql-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobilg%2Ftext-to-sql-proxy/lists"}