A lightweight, open-source analytics platform that starts with the essentials β connect to a live database, run SQL queries, and see results. From day one, it includes a modular alert/notification system so even without the full UI, teams can get value immediately.
Incremental & Modular Development
- Start simple, grow systematically
- Each component works standalone
- Use parts independently while we build the rest
β POC Phase Complete - Ready for production use!
- PostgreSQL database connectivity with connection pooling
- CLI interface for SQL query execution
- JSON result output with comprehensive error handling
- Connection profile storage - save database connections, no more repetitive URLs
- Named connection management with default profile support
- Real database validation completed
π Next Phase - Basic Frontend (Phase 0)
- Simple web UI for database connections
- SQL editor with syntax highlighting
- Result visualization as tables
- Project structure and monorepo setup
- Connect to PostgreSQL database with connection pooling
- Run SQL queries from CLI with parameter binding
- Return results as JSON with execution metrics
- Connection profile storage system (save/load/manage database connections)
- Named connection management with environment variable fallback
- Real database testing and validation
- Comprehensive error handling and resource cleanup
- Basic alert/notification system (stub implementation exists)
- Simple frontend for database connection
- SQL editor with syntax highlighting
- Query results as sortable tables
- Error handling and session management
- Save queries as "Insights"
- Basic charts (bar, line, pie)
- Parameterized queries
- Alert rules and notifications
- Role-based access control
- AI query generation
- Dashboard builder
- Plugin platform
- Advanced security & governance
- Node.js 20+
- pnpm 9+
- PostgreSQL (for development)
# Clone the repository
git clone https://github.com/YOUR_USERNAME/clariq.git
cd clariq
# Install dependencies and build
pnpm install
pnpm build# Save your database connection (one-time setup)
node ./packages/cli/dist/cli.js profile add production \
--url "postgresql://user:password@host:port/database" \
--description "My database" \
--default
# Test the connection
node ./packages/cli/dist/cli.js profile test production# List saved profiles
node ./packages/cli/dist/cli.js profile list
# Run queries using default profile (no URL needed!)
node ./packages/cli/dist/cli.js run "SELECT * FROM users LIMIT 10"
# Use specific profile
node ./packages/cli/dist/cli.js run "SELECT COUNT(*) FROM orders" --profile production
# Test connection
node ./packages/cli/dist/cli.js test --profile production# Start development with watch mode
pnpm devclariq/
βββ packages/
β βββ core/ # Database connectivity, connection management, config storage
β βββ alert-engine/ # Standalone alert system (stub)
β βββ cli/ # Command-line interface with profile management
βββ context/ # Project documentation and requirements
βββ examples/ # Sample configurations
βββ ~/.clariq/ # User profiles stored as profiles.yaml
# Profile Management
clariq profile add <name> --url <url> [--default] # Save connection
clariq profile list # List all profiles
clariq profile remove <name> # Delete profile
clariq profile test <name> # Test connection
# Query Execution
clariq run <query> [--profile <name>] # Execute SQL
clariq test [--profile <name>] # Test connection
# Connection Priority (highest to lowest)
# 1. Explicit --url flag
# 2. --profile flag
# 3. Default profile
# 4. CLARIQ_DATABASE_URL environment variablepnpm build- Build all packagespnpm dev- Start development with watch modepnpm test- Run tests across all packagespnpm lint- Lint all packagespnpm clean- Clean build artifacts
Deploy Clariq on a new machine in 3 steps:
# 1. Clone and build
git clone <repo-url> && cd clariq
pnpm install && pnpm build
# 2. Add your database connection
node ./packages/cli/dist/cli.js profile add production \
--url "postgresql://user:pass@host:port/database" \
--default
# 3. Start querying (no more connection details needed!)
node ./packages/cli/dist/cli.js run "SELECT 1"The alert engine has stub implementation ready for development:
import { createAlertEngine } from '@clariq/alert-engine';
const engine = createAlertEngine('postgresql://...');
engine.start(); // Currently logs "Alert engine started"- Project Brief - Detailed project overview and phases
- Alert System Design - Modular notification system specs
- Development Guide - Development principles and approach
We welcome contributions! Please read our development principles:
- Incremental approach - deliver simple, working features one by one
- Modularity first - components should work as standalone tools
- Developer experience - focus on ease of use and adoption
MIT License - see LICENSE file for details.