{"id":30501197,"url":"https://github.com/aliciaschep/pgbabble","last_synced_at":"2026-04-17T06:33:28.689Z","repository":{"id":311364822,"uuid":"1018734715","full_name":"AliciaSchep/pgbabble","owner":"AliciaSchep","description":"CLI client for LLM-assisted querying of postgres databases with restricted data sharing options","archived":false,"fork":false,"pushed_at":"2025-08-24T01:06:24.000Z","size":11089,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-24T11:06:06.381Z","etag":null,"topics":["llm","postgres","postgresql","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/AliciaSchep.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":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-12T23:22:00.000Z","updated_at":"2025-08-24T01:06:28.000Z","dependencies_parsed_at":"2025-08-24T11:06:15.666Z","dependency_job_id":"386a8d19-dcf8-4198-afda-6f63042989ee","html_url":"https://github.com/AliciaSchep/pgbabble","commit_stats":null,"previous_names":["aliciaschep/pgbabble"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/AliciaSchep/pgbabble","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AliciaSchep%2Fpgbabble","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AliciaSchep%2Fpgbabble/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AliciaSchep%2Fpgbabble/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AliciaSchep%2Fpgbabble/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AliciaSchep","download_url":"https://codeload.github.com/AliciaSchep/pgbabble/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AliciaSchep%2Fpgbabble/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31918585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["llm","postgres","postgresql","sql"],"created_at":"2025-08-25T09:10:51.911Z","updated_at":"2026-04-17T06:33:28.675Z","avatar_url":"https://github.com/AliciaSchep.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PGBabble\n\nAn interactive CLI tool for exploring PostgreSQL databases using natural language while maintaining data privacy (sharing query results with LLM is disabled by default) and ensuring quality and transparency (queries get reviewed \u0026 approved before actually being run).\n\n## Features\n\n- Natural language to SQL conversion, but with human-in-the-loop for approving LLM-generated SQL before it is run.\n- Privacy-first design (only metadata sent to LLM by default)\n- Interactive chat interface\n- psql-compatible connection handling\n- Schema inspection and exploration\n\n## Installation\n\n### Download Pre-built Binaries (Recommended)\n\nDownload the latest release for your platform from the [GitHub Releases page](https://github.com/AliciaSchep/pgbabble/releases).\n\nFor example, on macOS (Apple Silicon):\n```bash\ncurl -L https://github.com/AliciaSchep/pgbabble/releases/latest/download/pgbabble_Darwin_arm64.tar.gz | tar xz\n```\n\nAdd the `pgbabble` binary to your PATH. To verify installation:\n\n```bash\npgbabble -h\n```\n\n### Build from Source\n\nIf you have Go 1.24+ installed:\n\n```bash\ngit clone https://github.com/AliciaSchep/pgbabble.git\ncd pgbabble\nmake install\n```\n\n## Usage\n\n### API Key Setup \u0026 model selection\n\nBefore using pgbabble, you need to set up your Anthropic API key:\n\n```bash\nexport ANTHROPIC_API_KEY=your_api_key_here\n```\n\nYou can get an API key from [Anthropic's Console](https://console.anthropic.com/).\n\n**Note**: Currently, pgbabble only supports Anthropic's Claude models. We have plans to support other model providers (OpenAI, local models, etc.) in the future, but this has not yet been implemented.\n\nThe model can be specified using the `--model` flag with a valid anthropic model alias like `claude-sonnet-4-0`. The default is `claude-3-7-sonnet-latest`.\n\n### Connection Examples\n\n```bash\n# Connect with URI\npgbabble \"postgresql://user:pass@localhost/mydb\"\n\n# Connect with individual parameters\npgbabble --host localhost --port 5432 --user myuser --dbname mydb\n\n# Use environment variables (like psql)\nexport PGHOST=localhost PGUSER=myuser PGDATABASE=mydb\npgbabble\n\n# Specify data sharing mode (optional)\npgbabble --mode schema-only \"postgresql://user:pass@localhost/mydb\"\n\n# specify model (optional)\npgbabble --model laude-sonnet-4-0` \"postgresql://user:pass@localhost/mydb\"\n```\n\n## Privacy Modes\n\nPGBabble offers three privacy modes to control what information is shared with the LLM:\n\n| Data Type | `schema-only` | `default` | `share-results` |\n|-----------|:-------------:|:---------:|:---------------:|\n| **Schema information** (table names, column names, types) | ✅ | ✅ | ✅ |\n| **EXPLAIN query plans** (for optimization) | ❌ | ✅ | ✅ |\n| **Table size estimates** (approximate row counts) | ❌ | ✅ | ✅ |\n| **Query execution metadata** (row counts, execution time) | ❌ | ✅ | ✅ |\n| **Actual query result data** (limited to 50 rows) | ❌ | ❌ | ✅ |\n\n**Best use cases:**\n- **`schema-only`**: Highly sensitive databases where even table sizes should not be shared\n- **`default`**: General database exploration and query development with privacy protection\n- **`share-results`**: Development/testing environments where full data access is acceptable\n\n### Example Usage\n```bash\n# Maximum privacy mode\npgbabble --mode schema-only \"postgresql://user:pass@localhost/mydb\"\n\n# Default balanced mode\npgbabble --mode default \"postgresql://user:pass@localhost/mydb\"\n\n# Full data sharing mode\npgbabble --mode share-results \"postgresql://user:pass@localhost/mydb\"\n```\n\n## Quick Start with Sample Data\n\nTo test PGBabble with sample data, you can set up a PostgreSQL database with the LEGO dataset, which includes tables for sets, themes, parts, colors, and more.\n\n\n### 1. Start PostgreSQL with Docker\n\n```bash\n# Start PostgreSQL 17 container\ndocker run --name postgres-lego \\\n  -e POSTGRES_PASSWORD=password \\\n  -e POSTGRES_USER=postgres \\\n  -e POSTGRES_DB=postgres \\\n  -p 5432:5432 \\\n  -d postgres:17\n```\n\n### 2. Create and Load LEGO Database\n\n```bash\n# Wait a moment for PostgreSQL to start, then create the lego database\ndocker exec -it postgres-lego psql -U postgres -c \"CREATE DATABASE lego;\"\n\n# Download the LEGO dataset\ncurl -O https://raw.githubusercontent.com/neondatabase/postgres-sample-dbs/main/lego.sql\n\n# Load the data into the database\ndocker exec -i postgres-lego psql -U postgres -d lego \u003c lego.sql\n```\n\n### 3. Connect with PGBabble\n\n```bash\n# Build pgbabble\ngo build -o pgbabble cmd/pgbabble/main.go\n\n# Connect to the LEGO database\n./pgbabble \"postgresql://postgres:password@localhost/lego\"\n```\n\n### 4. Ask LLM to help with queries\n\nOnce connected, try asking about the data or for specific queries:\n```\npgbabble\u003e Can you describe what tables are in this database?\npgbabble\u003e How many themes have a parent theme?\npgbabble\u003e Can you provide a summary of all colors and how many parts they are used in?\n```\n\n### 5. Use Interactive Commands\n```\npgbabble\u003e /help              # Show all available commands\npgbabble\u003e /browse            # Browse last query results in full\npgbabble\u003e /save [filename]   # Save last query results to CSV file\npgbabble\u003e /schema            # Database overview\npgbabble\u003e /tables            # List all tables\npgbabble\u003e /describe \u003ctable\u003e  # Detailed table structure\npgbabble\u003e /mode              # Show privacy mode\n```\n\n### Example Workflow\n1. Run a natural language query that returns many rows\n2. View the first 25 rows with intelligent column formatting\n3. Type `/browse` to explore all results in the `less` pager\n4. Use standard `less` navigation (space, arrows, search with `/pattern`)\n5. Press 'q' to return to the pgbabble prompt\n6. Type `/save` to export results to CSV file with default filename\n7. Or use `/save my_analysis.csv` to specify a custom filename\n\n## Development\n\n```bash\n# Run tests\nmake test\n\n# Build\nmake build\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faliciaschep%2Fpgbabble","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faliciaschep%2Fpgbabble","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faliciaschep%2Fpgbabble/lists"}