{"id":20036891,"url":"https://github.com/cowsdb/cowsdb","last_synced_at":"2026-06-09T04:05:59.123Z","repository":{"id":213884116,"uuid":"735019197","full_name":"cowsdb/cowsdb","owner":"cowsdb","description":"CowsDB: Serverless OLAP Engine API and 100% ClickHouse alternative for CI and HTTP Services","archived":false,"fork":false,"pushed_at":"2026-02-03T01:21:47.000Z","size":26503,"stargazers_count":22,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-03T15:59:44.875Z","etag":null,"topics":["chdb","chdb-server","clickhouse","clickhouse-alternative","clickhouse-server","cowsdb","embedded-sql-database","olap-engine","serverless"],"latest_commit_sha":null,"homepage":"https://cowsdb.fly.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cowsdb.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":"2023-12-23T11:26:50.000Z","updated_at":"2025-08-04T07:30:56.000Z","dependencies_parsed_at":"2024-01-17T14:51:39.336Z","dependency_job_id":"e4754812-9a0f-4419-9e77-7bb32c515957","html_url":"https://github.com/cowsdb/cowsdb","commit_stats":null,"previous_names":["cowsdb/cowsdb"],"tags_count":50,"template":false,"template_full_name":null,"purl":"pkg:github/cowsdb/cowsdb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowsdb%2Fcowsdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowsdb%2Fcowsdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowsdb%2Fcowsdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowsdb%2Fcowsdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cowsdb","download_url":"https://codeload.github.com/cowsdb/cowsdb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowsdb%2Fcowsdb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34090807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"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":["chdb","chdb-server","clickhouse","clickhouse-alternative","clickhouse-server","cowsdb","embedded-sql-database","olap-engine","serverless"],"created_at":"2024-11-13T10:17:08.557Z","updated_at":"2026-06-09T04:05:59.106Z","avatar_url":"https://github.com/cowsdb.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg width=\"200\" height=\"200\" alt=\"image\" src=\"https://github.com/user-attachments/assets/a21ea293-36f0-4ff2-9898-c5f68883c22f\" /\u003e\u003cimg src=\"https://github.com/user-attachments/assets/685cc433-a5bb-45a4-bbd2-4f132f6dec44\" width=140\u003e\u003cimg src=\"https://github.com/user-attachments/assets/685cc433-a5bb-45a4-bbd2-4f132f6dec44\" width=100\u003e\u003cimg src=\"https://github.com/user-attachments/assets/685cc433-a5bb-45a4-bbd2-4f132f6dec44\" width=70\u003e\u003cimg src=\"https://github.com/user-attachments/assets/685cc433-a5bb-45a4-bbd2-4f132f6dec44\" width=40\u003e\n\n# CowsDB\n[![CowsDB SQL Bench](https://github.com/cowsdb/cowsdb/actions/workflows/test.yml/badge.svg)](https://github.com/cowsdb/cowsdb/actions/workflows/test.yml)\n\n\u003e CowsDB prentends to be ClickHouse and can be used with any ClickHouse client for serverless ops\n\n## ✨ Features\n\n- **🔌 ClickHouse HTTP API Compatibility** - Full HTTP API support on port 8123\n- **⚡ Native Protocol Support** - Binary protocol support on port 9000\n- **📊 Multiple Output Formats** - TSV, JSON, CSV, and Native binary formats\n\n\u003cbr\u003e\n\n## 🚀 Quick Start\n```\ndocker run --rm -p 8123:8123 -p 9000:9000 ghcr.io/cowsdb/cowsdb:latest\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `HOST` | `0.0.0.0` | Server host address |\n| `PORT` | `8123` | HTTP API port |\n| `NATIVE_PORT` | `9000` | Native protocol port |\n| `SESSION_TTL` | `3600` | Session timeout in seconds |\n\n### Example Configuration\n```bash\nexport HOST=0.0.0.0\nexport PORT=8123\nexport NATIVE_PORT=9000\nexport SESSION_TTL=7200\npython main.py\n```\n\n## 📖 Usage\n\n### HTTP API (Port 8123)\n\n#### Basic Query\n```bash\ncurl -G --data-urlencode \"query=SELECT version(), now()\" http://test:test@localhost:8123\n```\n\n#### POST Queries\n```bash\ncurl -X POST --data \"SELECT 1 as num, 'hello' as str\" http://test:test@localhost:8123\n```\n\n#### Ping Endpoint\n```bash\ncurl http://localhost:8123/ping\n# Returns: Ok.\n```\n\n### Native Protocol (Port 9000)\n\n#### Using clickhouse-driver\n```python\nfrom clickhouse_driver import Client\n\n# Connect to CowsDB\nclient = Client('localhost', port=9000)\n\n# Execute queries\nresult = client.execute('SELECT version(), now()')\nprint(result)\n\n# Query with parameters\nresult = client.execute('SELECT %(num)s as number', {'num': 42})\nprint(result)\n```\n\n#### Using clickhouse-client\n```bash\nclickhouse-client --host localhost --port 9000 --query \"SELECT version(), now()\"\n```\n\n\n## 🧪 Testing\n\n### Run the Complete Test Suite\n```bash\n# From project root\npython run_tests.py tests\n\n# Or directly\npython test/test_suite.py\n\n# Or using the CI script\nbash test/run_tests.sh\n```\n\nThis will test:\n- ✅ HTTP API functionality\n- ✅ Native protocol handshake and queries\n- ✅ Multiple data types (Integer, String, Float, DateTime)\n- ✅ Different output formats (TSV, JSON, CSV)\n- ✅ Session management and authentication\n- ✅ Error handling\n\n### Environment Setup\n```bash\n# Production environment variables\nexport HOST=0.0.0.0\nexport PORT=8123\nexport NATIVE_PORT=9000\n\n# Start with Gunicorn\ngunicorn -w 4 -b 0.0.0.0:8123 main:app\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n\n## 📄 License\n\nCowsDB is licensed under the AGPLv3 license and is NOT affiliated in any way with ClickHouse Inc.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcowsdb%2Fcowsdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcowsdb%2Fcowsdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcowsdb%2Fcowsdb/lists"}