CowsDB prentends to be ClickHouse and can be used with any ClickHouse client for serverless ops

• 🔌 ClickHouse HTTP API Compatibility - Full HTTP API support on port 8123
• ⚡ Native Protocol Support - Binary protocol support on port 9000
• 📊 Multiple Output Formats - TSV, JSON, CSV, and Native binary formats

docker run --rm -p 8123:8123 -p 9000:9000 ghcr.io/cowsdb/cowsdb:latest

export HOST=0.0.0.0
export PORT=8123
export NATIVE_PORT=9000
export SESSION_TTL=7200
python main.py

curl -G --data-urlencode "query=SELECT version(), now()" http://test:test@localhost:8123

curl -X POST --data "SELECT 1 as num, 'hello' as str" http://test:test@localhost:8123

curl http://localhost:8123/ping
# Returns: Ok.

from clickhouse_driver import Client

# Connect to CowsDB
client = Client('localhost', port=9000)

# Execute queries
result = client.execute('SELECT version(), now()')
print(result)

# Query with parameters
result = client.execute('SELECT %(num)s as number', {'num': 42})
print(result)

clickhouse-client --host localhost --port 9000 --query "SELECT version(), now()"

# From project root
python run_tests.py tests

# Or directly
python test/test_suite.py

# Or using the CI script
bash test/run_tests.sh

This will test:

• ✅ HTTP API functionality
• ✅ Native protocol handshake and queries
• ✅ Multiple data types (Integer, String, Float, DateTime)
• ✅ Different output formats (TSV, JSON, CSV)
• ✅ Session management and authentication
• ✅ Error handling

# Production environment variables
export HOST=0.0.0.0
export PORT=8123
export NATIVE_PORT=9000

# Start with Gunicorn
gunicorn -w 4 -b 0.0.0.0:8123 main:app

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

CowsDB is licensed under the AGPLv3 license and is NOT affiliated in any way with ClickHouse Inc.