{"id":36934965,"url":"https://github.com/vectorize-io/pg0","last_synced_at":"2026-01-31T18:22:30.305Z","repository":{"id":326078082,"uuid":"1103831403","full_name":"vectorize-io/pg0","owner":"vectorize-io","description":"pg0 - language agnostic embedded postgres ","archived":false,"fork":false,"pushed_at":"2025-12-12T16:23:50.000Z","size":16670,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-14T04:12:00.970Z","etag":null,"topics":["embedded","postgres","sqlite"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vectorize-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2025-11-25T11:49:30.000Z","updated_at":"2025-12-13T05:59:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vectorize-io/pg0","commit_stats":null,"previous_names":["vectorize-io/embedded-pg-cli"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/vectorize-io/pg0","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vectorize-io%2Fpg0","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vectorize-io%2Fpg0/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vectorize-io%2Fpg0/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vectorize-io%2Fpg0/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vectorize-io","download_url":"https://codeload.github.com/vectorize-io/pg0/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vectorize-io%2Fpg0/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28380789,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T08:40:31.739Z","status":"ssl_error","status_checked_at":"2026-01-13T08:40:23.736Z","response_time":56,"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":["embedded","postgres","sqlite"],"created_at":"2026-01-13T09:54:18.549Z","updated_at":"2026-01-31T18:22:30.298Z","avatar_url":"https://github.com/vectorize-io.png","language":"Rust","readme":"# pg0\n\n[![PyPI version](https://badge.fury.io/py/pg0-embedded.svg)](https://pypi.org/project/pg0-embedded/)\n[![PyPI downloads](https://img.shields.io/pypi/dm/pg0-embedded.svg)](https://pypi.org/project/pg0-embedded/)\n[![Python versions](https://img.shields.io/pypi/pyversions/pg0-embedded.svg)](https://pypi.org/project/pg0-embedded/)\n\n**Zero-config PostgreSQL with pgvector.**\n\nA single binary that runs PostgreSQL locally - no installation, no configuration, no Docker required. Includes **pgvector** for AI/vector workloads out of the box.\n\n## Why pg0?\n\nPostgreSQL setup is painful. Docker adds complexity. Local installs conflict with system packages. pg0 gives you a real PostgreSQL server with zero friction:\n\n- **No installation** - download a single binary and run `pg0 start`\n- **No Docker** - no containers, no daemon, no complexity\n- **No configuration** - sensible defaults, just works\n- **Production parity** - develop with the same database you'll deploy\n- **Full PostgreSQL** - JSON, arrays, CTEs, window functions, extensions, pgvector - everything works\n\nUse pg0 for local development, testing, CI/CD pipelines, or any scenario where you want PostgreSQL without the setup overhead.\n\n## Supported Platforms\n\n| Platform | Architecture | Binary |\n|----------|--------------|--------|\n| macOS | Apple Silicon (M1/M2/M3) | `pg0-macos-arm64` |\n| Linux | x86_64 (glibc) | `pg0-linux-amd64-gnu` |\n| Linux | x86_64 (musl/Alpine) | `pg0-linux-amd64-musl` |\n| Linux | ARM64 (glibc) | `pg0-linux-arm64-gnu` |\n| Linux | ARM64 (musl/Alpine) | `pg0-linux-arm64-musl` |\n| Windows | x64 | `pg0-windows-amd64.exe` |\n\n## Features\n\n- **Zero dependencies** - single binary, works offline\n- **PostgreSQL 18** with pgvector 0.8.1 bundled\n- **Multiple instances** - run multiple PostgreSQL servers simultaneously\n- **Cross-platform** - macOS (Apple Silicon), Linux (x86_64 \u0026 ARM64), Windows (x64)\n- **Language SDKs** - Python and Node.js libraries for programmatic control\n- **Bundled psql** - no separate client installation needed\n- **Persistent data** - survives restarts, stored in `~/.pg0/`\n\n## Installation\n\n### CLI Binary\n\nThe install script automatically detects your platform and downloads the correct binary:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/vectorize-io/pg0/main/install.sh | bash\n```\n\nOr with a custom install directory:\n\n```bash\nINSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/vectorize-io/pg0/main/install.sh | bash\n```\n\n### Python SDK\n\nInstall via pip:\n\n```bash\npip install pg0-embedded\n```\n\nQuick start:\n\n```python\nfrom pg0 import Pg0\n\n# Start PostgreSQL\npg = Pg0()\npg.start()\nprint(pg.uri)  # postgresql://postgres:postgres@localhost:5432/postgres\n\n# Or use context manager\nwith Pg0() as pg:\n    result = pg.execute(\"SELECT version();\")\n    print(result)\n```\n\nSee [PyPI package](https://pypi.org/project/pg0-embedded/) for more details.\n\n### Node.js SDK\n\nInstall via npm:\n\n```bash\nnpm install @vectorize-io/pg0\n```\n\nQuick start:\n\n```typescript\nimport { Pg0 } from '@vectorize-io/pg0';\n\nconst pg = new Pg0();\nawait pg.start();\nconsole.log(await pg.getUri());\nawait pg.stop();\n```\n\n### Linux Distributions\n\npg0 provides separate binaries optimized for different Linux distributions:\n\n- **Debian/Ubuntu/RHEL** (glibc-based): Uses `pg0-linux-{arch}-gnu`\n- **Alpine** (musl-based): Uses `pg0-linux-{arch}-musl`\n\nThe install script automatically detects your distribution and downloads the correct binary.\n\n## Docker\n\npg0 works in Docker containers. Here are the minimal setup steps for each supported image type:\n\n### Debian/Ubuntu (glibc-based)\n\n```dockerfile\nFROM debian:bookworm-slim\n# or: python:3.11-slim, ubuntu:22.04, etc.\n\n# Install required dependencies\nRUN apt-get update \u0026\u0026 apt-get install -y \\\n    curl \\\n    libxml2 \\\n    libssl3 \\\n    libgssapi-krb5-2 \\\n    \u0026\u0026 apt-get install -y libicu72 || apt-get install -y libicu74 || apt-get install -y libicu* \\\n    \u0026\u0026 rm -rf /var/lib/apt/lists/*\n\n# Create non-root user (PostgreSQL cannot run as root)\nRUN useradd -m -s /bin/bash pguser\nUSER pguser\n\n# Install pg0\nRUN curl -fsSL https://raw.githubusercontent.com/vectorize-io/pg0/main/install.sh | bash\nENV PATH=\"/home/pguser/.local/bin:${PATH}\"\n\n# Start PostgreSQL when container runs\nCMD [\"bash\", \"-c\", \"pg0 start \u0026\u0026 tail -f /dev/null\"]\n```\n\nOr start it with your application:\n\n```bash\ndocker run -d myimage bash -c \"pg0 start \u0026\u0026 exec your-application\"\n```\n\n### Alpine (musl-based)\n\n**Note:** The musl binary requires ICU 74. Use Alpine 3.20 (not 3.22+) as newer versions have ICU 76.\n\n```dockerfile\nFROM alpine:3.20\n# or: python:3.12-alpine3.20\n\n# Install required dependencies\nRUN apk add --no-cache curl bash shadow icu-libs lz4-libs libxml2\n\n# Create non-root user (PostgreSQL cannot run as root)\nRUN adduser -D -s /bin/bash pguser\nUSER pguser\n\n# Install pg0\nRUN curl -fsSL https://raw.githubusercontent.com/vectorize-io/pg0/main/install.sh | bash\nENV PATH=\"/home/pguser/.local/bin:${PATH}\"\n\n# Start PostgreSQL when container runs\nCMD [\"sh\", \"-c\", \"pg0 start \u0026\u0026 tail -f /dev/null\"]\n```\n\nOr start it with your application:\n\n```bash\ndocker run -d myimage sh -c \"pg0 start \u0026\u0026 exec your-application\"\n```\n\n### Quick Test\n\nRun pg0 in a Docker container with a single command:\n\n```bash\n# Debian/Ubuntu\ndocker run --rm -it python:3.11-slim bash -c '\n  apt-get update -qq \u0026\u0026\n  apt-get install -y curl libxml2 libssl3 libgssapi-krb5-2 libicu72 \u0026\u0026\n  useradd -m pguser \u0026\u0026\n  su - pguser -c \"curl -fsSL https://raw.githubusercontent.com/vectorize-io/pg0/main/install.sh | bash \u0026\u0026\n    export PATH=\\\"\\$HOME/.local/bin:\\$PATH\\\" \u0026\u0026\n    pg0 start \u0026\u0026\n    sleep 3 \u0026\u0026\n    pg0 psql -c \\\"SELECT version();\\\"\"\n'\n\n# Alpine (use 3.20 for ICU 74 compatibility)\ndocker run --rm -it python:3.12-alpine3.20 sh -c '\n  apk add --no-cache curl bash shadow icu-libs lz4-libs libxml2 \u0026\u0026\n  adduser -D pguser \u0026\u0026\n  su - pguser -c \"curl -fsSL https://raw.githubusercontent.com/vectorize-io/pg0/main/install.sh | bash \u0026\u0026\n    export PATH=\\\"\\$HOME/.local/bin:\\$PATH\\\" \u0026\u0026\n    pg0 start \u0026\u0026\n    sleep 3 \u0026\u0026\n    pg0 psql -c \\\"SELECT version();\\\"\"\n'\n```\n\n**Note:** PostgreSQL requires a non-root user for security. The examples above create a `pguser` for this purpose.\n\n## Quick Start\n\n```bash\n# Start PostgreSQL\npg0 start\n\n# Connect with psql\npg0 psql\n\n# Use pgvector\npg0 psql -c \"CREATE EXTENSION IF NOT EXISTS vector;\"\npg0 psql -c \"CREATE TABLE items (embedding vector(3));\"\npg0 psql -c \"INSERT INTO items VALUES ('[1,2,3]');\"\n\n# Stop when done\npg0 stop\n```\n\n## Usage\n\n### Commands\n\npg0 provides the following commands:\n\n1. **start** - Start a PostgreSQL server instance\n2. **stop** - Stop a running PostgreSQL server instance\n3. **drop** - Stop and permanently delete an instance (removes all data)\n4. **info** - Display instance information (status, connection URI, etc.)\n5. **list** - List all PostgreSQL instances\n6. **psql** - Open an interactive psql shell connected to an instance\n7. **logs** - View PostgreSQL logs for debugging\n\n### Start PostgreSQL\n\n```bash\n# Start with defaults (port 5432)\npg0 start\n\n# Start with custom options\npg0 start --port 5433 --username myuser --password mypass --database myapp\n```\n\n### Stop PostgreSQL\n\n```bash\npg0 stop\n```\n\n### Drop Instance\n\nPermanently delete an instance and all its data:\n\n```bash\n# Drop the default instance\npg0 drop\n\n# Drop a named instance\npg0 drop --name myapp\n```\n\n**Warning:** This command will stop the instance if running and delete all data. This action cannot be undone.\n\n### Get Server Info\n\n```bash\n# Human-readable format\npg0 info\n\n# JSON output\npg0 info -o json\n\n# Info for a specific instance\npg0 info --name myapp\n```\n\n### List Instances\n\n```bash\n# List all instances\npg0 list\n\n# JSON output\npg0 list -o json\n```\n\n### Open psql Shell\n\n```bash\n# Interactive shell\npg0 psql\n\n# Run a single command\npg0 psql -c \"SELECT version();\"\n\n# Run a SQL file\npg0 psql -f schema.sql\n```\n\n### View Logs\n\nView PostgreSQL logs for debugging startup issues or errors:\n\n```bash\n# View all logs\npg0 logs\n\n# View last 50 lines\npg0 logs -n 50\n\n# Follow logs in real-time (like tail -f)\npg0 logs --follow\n\n# Logs for a specific instance\npg0 logs --name myapp\n```\n\nLogs are stored in `~/.pg0/instances/\u003cname\u003e/data/log/`.\n\n### Using pgvector\n\npgvector is pre-installed. Just enable it:\n\n```bash\npg0 psql -c \"CREATE EXTENSION IF NOT EXISTS vector;\"\n```\n\nThen use it for vector similarity search:\n\n```sql\n-- Create a table with vector column\nCREATE TABLE items (id serial PRIMARY KEY, embedding vector(1536));\n\n-- Insert vectors\nINSERT INTO items (embedding) VALUES ('[0.1, 0.2, ...]');\n\n-- Find similar vectors\nSELECT * FROM items ORDER BY embedding \u003c-\u003e '[0.1, 0.2, ...]' LIMIT 5;\n```\n\n### Multiple Instances\n\nRun multiple PostgreSQL servers simultaneously using named instances:\n\n```bash\n# Start multiple instances on different ports\npg0 start --name app1 --port 5432\npg0 start --name app2 --port 5433\npg0 start --name test --port 5434\n\n# List all instances\npg0 list\n\n# Get info for a specific instance\npg0 info --name app1\n\n# Connect to a specific instance\npg0 psql --name app2\n\n# Stop a specific instance\npg0 stop --name test\n\n# Stop all (one by one)\npg0 stop --name app1\npg0 stop --name app2\n```\n\nEach instance has its own data directory at `~/.pg0/instances/\u003cname\u003e/data/`.\n\n## Options\n\n### Global Options\n\n```\n  -v, --verbose  Enable verbose logging\n```\n\n### Start Options\n\n```\npg0 start [OPTIONS]\n\nOptions:\n      --name \u003cNAME\u003e           Instance name [default: default]\n  -p, --port \u003cPORT\u003e           Port to listen on [default: 5432]\n  -d, --data-dir \u003cDATA_DIR\u003e   Data directory [default: ~/.pg0/instances/\u003cname\u003e/data]\n  -u, --username \u003cUSERNAME\u003e   Username [default: postgres]\n  -P, --password \u003cPASSWORD\u003e   Password [default: postgres]\n  -n, --database \u003cDATABASE\u003e   Database name [default: postgres]\n  -c, --config \u003cKEY=VALUE\u003e    PostgreSQL config option (can repeat)\n```\n\n### PostgreSQL Configuration\n\npg0 applies optimized defaults for vector/AI workloads:\n- `shared_buffers=256MB`\n- `maintenance_work_mem=512MB` (faster index builds)\n- `effective_cache_size=1GB`\n- `max_parallel_maintenance_workers=4`\n- `work_mem=64MB`\n\nOverride any setting with `-c`:\n\n```bash\n# Custom memory settings\npg0 start -c shared_buffers=512MB -c work_mem=128MB\n\n# For larger workloads\npg0 start -c shared_buffers=1GB -c maintenance_work_mem=2GB\n```\n\n## How It Works\n\nPostgreSQL and pgvector are **bundled directly** into the pg0 binary - no downloads required, works completely offline! On first start, pg0 extracts PostgreSQL and pgvector to `~/.pg0/installation/` and initializes the database.\n\nData is stored in `~/.pg0/instances/\u003cname\u003e/data/` (or your custom `--data-dir`) and persists between restarts.\n\n## Runtime Dependencies\n\npg0 bundles PostgreSQL but requires some shared libraries at runtime. These are typically pre-installed on most systems, but may need to be added in minimal environments like Docker.\n\n**macOS:** No additional dependencies required.\n\n**Linux (Debian/Ubuntu):**\n```bash\napt-get install libxml2 libssl3 libgssapi-krb5-2\n```\n\n**Linux (Alpine):**\n```bash\napk add icu-libs lz4-libs libxml2\n```\n\n### Why these dependencies?\n\nThe bundled PostgreSQL binaries are compiled with these features enabled:\n\n| Library | Purpose | Can disable? |\n|---------|---------|--------------|\n| OpenSSL (`libssl`) | SSL/TLS connections | Not recommended |\n| GSSAPI (`libgssapi-krb5`) | Kerberos authentication | Rarely needed locally |\n| libxml2 | XML data type and functions | Rarely needed |\n| ICU (`icu-libs`) | Unicode collation (Alpine only) | glibc builds don't need it |\n| LZ4 (`lz4-libs`) | WAL/TOAST compression | Small impact |\n\nMost desktop Linux distributions and macOS have these libraries pre-installed. You only need to install them manually in minimal Docker images or bare-metal servers.\n\n## Troubleshooting\n\n### PostgreSQL Cannot Run as Root\n\nPostgreSQL refuses to run as root for security reasons. If you see this error:\n\n```\ninitdb: error: cannot be run as root\n```\n\nYou need to run pg0 as a non-root user:\n\n```bash\n# Create a non-root user and run pg0\nuseradd -m pguser\nsu - pguser -c \"pg0 start\"\n```\n\n**Note:** This means pg0 won't work in environments that only allow root access, such as:\n- Google Colab (runs as root)\n- Some CI environments\n- Restricted containers\n\nSee the [Docker](#docker) section for complete examples of running pg0 as a non-root user.\n\n### Port Already in Use\n\nIf port 5432 is already in use, pg0 will automatically find an available port:\n\n```bash\npg0 start --name second-instance\n# Output: Port 5432 is in use, using port 54321 instead.\n```\n\nTo use a specific port, specify it explicitly:\n\n```bash\npg0 start --port 5433\n```\n\n## Build from Source\n\n```bash\ncargo build --release\n```\n\nThe binary will be at `target/release/pg0`.\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvectorize-io%2Fpg0","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvectorize-io%2Fpg0","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvectorize-io%2Fpg0/lists"}