8000 GitHub - imf4isal/clariq Β· GitHub
[go: up one dir, main page]

Skip to content
imf4isalPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

22 Commits

Folders and files

Repository files navigation

Clariq

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.

🎯 Philosophy

Incremental & Modular Development

  • Start simple, grow systematically
  • Each component works standalone
  • Use parts independently while we build the rest

πŸš€ Current Status

βœ… 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

πŸ“‹ Roadmap

Proof of Concept (POC) βœ… COMPLETED

  • 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)

Phase 0 - Basic UI

  • Simple frontend for database connection
  • SQL editor with syntax highlighting
  • Query results as sortable tables
  • Error handling and session management

Phase 1 - MVP

  • Save queries as "Insights"
  • Basic charts (bar, line, pie)
  • Parameterized queries
  • Alert rules and notifications
  • Role-based access control

NEXT - Advanced Features

  • AI query generation
  • Dashboard builder
  • Plugin platform
  • Advanced security & governance

πŸ› οΈ Development

Prerequisites

  • Node.js 20+
  • pnpm 9+
  • PostgreSQL (for development)

Getting Started

Quick Setup

# Clone the repository
git clone https://github.com/YOUR_USERNAME/clariq.git
cd clariq

# Install dependencies and build
pnpm install
pnpm build

Database Connection Setup

# 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

Usage Examples

# 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

Development Mode

# Start development with watch mode
pnpm dev

Project Structure

clariq/
β”œβ”€β”€ 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

CLI Commands

# 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 variable

Scripts

  • pnpm build - Build all packages
  • pnpm dev - Start development with watch mode
  • pnpm test - Run tests across all packages
  • pnpm lint - Lint all packages
  • pnpm clean - Clean build artifacts

πŸš€ Quick Start for New Machines

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"

πŸ”§ Alert Engine (Future Enhancement)

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"

πŸ“– Documentation

🀝 Contributing

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

πŸ“„ License

MIT License - see LICENSE file for details.

πŸ”— Links

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0