HowlerOps

A powerful, cloud-enabled desktop SQL client with AI-powered features and multi-device sync

Features

🚀 Core Capabilities

• Multi-Database Support - Connect to PostgreSQL, MySQL, SQLite, MongoDB, ElasticSearch, and more
• Multi-Database Queries - Query across multiple databases with @connection.schema.table syntax
• AI-Powered SQL Generation - Generate SQL from natural language
• Smart Query Suggestions - Context-aware query completion
• Query History - Track all your queries with performance metrics
• Schema Explorer - Browse tables, views, and relationships

☁️ Cloud Sync (Phase 2 - NEW!)

• Multi-Device Sync - Access your queries, connections, and history across all devices
• Automatic Conflict Resolution - Smart merging with three resolution strategies
• Offline-First - Work offline, sync automatically when connected
• Secure Cloud Storage - Powered by Turso with edge replication
• Credential Protection - Passwords never leave your device
• Real-Time Updates - See changes across devices in seconds

🔐 Authentication & Security

• JWT Authentication - Secure token-based authentication
• Email Verification - Verify your account via email
• Password Reset - Secure password recovery flow
• Auto Token Refresh - Seamless session management
• Encrypted Storage - Database credentials encrypted at rest
• Sanitized Sync - Sensitive data never synced to cloud

🤖 AI Features

• Natural Language to SQL - Describe what you want, get the SQL
• Query Optimization - AI-powered query performance tips
• Error Fixing - Automatic SQL error detection and fixes
• Smart Autocomplete - Context-aware SQL suggestions
• RAG-Powered Context - Learns from your schema and past queries

💾 Hybrid Storage

• Local-First Architecture - All data stored locally in SQLite/IndexedDB
• Cloud Backup - Optional Turso cloud sync for multi-device access
• Offline Capable - Works completely offline
• Automatic Sync - Background synchronization when online
• Conflict Detection - Intelligent merge strategies for concurrent edits

Installation

Quick Install (Recommended)

Install Howlerops with a single command:

curl -fsSL https://raw.githubusercontent.com/howlerops/howlerops/main/install.sh | sh

Other options:

# Install specific version
curl -fsSL https://raw.githubusercontent.com/howlerops/howlerops/main/install.sh | sh -s -- --version v2.0.0

# Preview what will be installed (dry-run)
curl -fsSL https://raw.githubusercontent.com/howlerops/howlerops/main/install.sh | sh -s -- --dry-run

# Verbose output for troubleshooting
curl -fsSL https://raw.githubusercontent.com/howlerops/howlerops/main/install.sh | sh -s -- --verbose

What install.sh installs per platform:

• macOS, Apple Silicon (arm64) — the HowlerOps.app desktop app
• Linux (x86_64 / arm64) — the howlerops CLI

Not currently published: Intel (amd64) macOS builds and native Windows binaries. On Windows, use WSL (Linux CLI) or build from source. Intel macOS support can be restored by re-enabling the amd64 build matrix entries in .github/workflows/release.yml.

📖 Full installation guide | 📋 Quick reference

Alternative Methods

• Direct Download: Latest Release
• Build from Source: See Development section below
• Homebrew (not yet available): a cask is planned but not currently published

For detailed installation instructions, platform-specific guides, and troubleshooting, see docs/INSTALL.md.

Quick Start

Prerequisites (Development Only)

• Go 1.21+
• Node.js 22.12+ (recommended) or 20.19+
• Wails CLI v3

Development Setup

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

# Install Wails CLI (if not installed)
go install github.com/wailsapp/wails/v3/cmd/wails3@latest

# Install dependencies
make deps

# Start development server
make dev

The app will automatically:

1. Initialize local SQLite databases
2. Set up vector storage for AI/RAG
3. Start the development server with hot reload

First Run

On first launch:

1. Add a Database Connection

   • Click "Add Connection"
   • Enter your database details
   • Test connection
   • Save

2. Configure AI (Optional)

   • Go to Settings → AI
   • Add your OpenAI, Anthropic, or Ollama credentials
   • AI features will activate automatically

3. Start Querying!

   • Write SQL or use natural language
   • Query multiple databases at once
   • Save your favorite queries

Architecture

Hybrid Cloud Architecture (Phase 2)

Howlerops uses a hybrid local-first + cloud sync architecture for the best of both worlds:

┌─────────────────────────────────────────────────────────┐
│                   Desktop Application                    │
│              (Wails - React + Go Backend)               │
└─────────────────────┬───────────────────────────────────┘
                      │
         ┌────────────┴────────────┐
         │                         │
         ▼                         ▼
  ┌─────────────┐          ┌──────────────┐
  │   Local     │          │    Cloud     │
  │  SQLite DB  │◄────────►│  Turso DB    │
  │  (Primary)  │   Sync   │  (Backup)    │
  └─────────────┘          └──────┬───────┘
                                  │
                     ┌────────────┴────────────┐
                     │                         │
                     ▼                         ▼
              ┌─────────────┐          ┌──────────────┐
              │   Resend    │          │   GitHub     │
              │  (Emails)   │          │  (Releases)  │
              └─────────────┘          └──────────────┘

Key Components

Frontend (React 19 + TypeScript):

• React components with shadcn/ui
• Zustand state management
• IndexedDB for browser storage
• WebSocket for real-time updates

Backend (Go):

• Wails v2 desktop framework
• RESTful API endpoints
• JWT authentication
• gRPC for future services

Storage Layers:

• Local: SQLite (desktop) or IndexedDB (browser) - primary storage
• Cloud: Turso/libSQL database with edge replication
• Sync Engine: Bidirectional sync with conflict resolution

External Services:

• Turso: Cloud database with global edge replication
• Resend: Transactional email delivery
• GitHub Actions: CI/CD and automated releases

Data Flow

1. Local-First: All operations happen locally first (fast, offline-capable)
2. Background Sync: Changes sync to cloud in the background
3. Conflict Detection: Automatic detection when devices modify same data
4. Resolution: Three strategies (Last Write Wins, Keep Both, User Choice)
5. Multi-Device: Changes propagate to other devices in real-time

Storage Location

Desktop Application (~/.howlerops/):

• local.db - Connections, queries, settings (primary storage)
• vectors.db - AI embeddings and RAG data
• backups/ - Automatic local backups
• logs/ - Application logs

Cloud Storage (Turso):

• Connection metadata (passwords stored locally only)
• Saved queries
• Sanitized query history
• Sync state and conflict resolution

📖 Complete Architecture Documentation

Configuration

Environment Variables

# Optional: User configuration
export HOWLEROPS_USER_ID=your-user-id
export HOWLEROPS_DATA_DIR=~/.howlerops
export HOWLEROPS_MODE=local  # or 'team' (future)

# Optional: AI provider keys (can also set in UI)
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export OLLAMA_ENDPOINT=http://localhost:11434

AI Providers

HowlerOps supports multiple AI providers:

Provider	Setup	Notes
OpenAI	Add API key in Settings	Best quality, paid
Anthropic (Claude)	Add API key in Settings	Great for complex SQL
Ollama	Install locally, auto-detected	Free, runs locally
Claude Code	Binary path in Settings	Advanced coding model

Development

Project Structure

howlerops/
├── main.go               # Wails desktop entry point
├── app_lifecycle.go      # Desktop composition root
├── cmd/
│   └── server/           # Backend/server entry point
├── internal/             # Backend/domain packages
├── pkg/                  # Shared libraries
├── services/             # Desktop-facing Go service layer
├── frontend/             # React/TypeScript UI
├── proto/                # Shared protobuf definitions
├── scripts/              # Maintenance and CI helpers
└── docs/                 # Documentation

Make Commands

make deps            # Install all dependencies
make init-local-db   # Initialize SQLite databases
make dev             # Start development server
make build           # Build production app
make test            # Run all tests
make test-go         # Run Go tests only
make test-frontend   # Run frontend tests
make backup-local-db # Backup databases
make reset-local-db  # Reset databases (with backup)
make lint            # Run linters
make fmt             # Format code

Testing

# Run all tests
make test

# CRITICAL: Complete validation before any task
make validate        # Runs lint + test for both frontend and backend

# Frontend validation
cd frontend
npm run typecheck    # TypeScript type checking
npm run lint         # ESLint validation
npm run test:run     # Unit tests

# Backend validation
go mod tidy          # Clean up Go modules
go fmt ./...         # Format Go code
go test ./...        # Run Go tests

# Run specific tests
go test ./backend-go/pkg/storage/...
cd frontend && npm run test

# Run with coverage
go test -cover ./...

Database Management

Backup & Restore

# Create backup
make backup-local-db

# Backups are stored in ~/.howlerops/backups/

# Restore from backup
cp ~/.howlerops/backups/local_TIMESTAMP.db ~/.howlerops/local.db
cp ~/.howlerops/backups/vectors_TIMESTAMP.db ~/.howlerops/vectors.db

Reset Databases

# This will:
# 1. Create automatic backup
# 2. Delete existing databases
# 3. Reinitialize fresh databases
make reset-local-db

AI & RAG

How It Works

1. Schema Learning - AI indexes your database schemas
2. Query Learning - Successful queries are embedded and stored
3. Context Retrieval - When you ask questions, relevant context is fetched
4. Smart Generation - AI generates SQL using your specific schema

Performance

• Vector search: ~10-50ms (pure Go implementation)
• Query generation: ~1-3s (depends on AI provider)
• Schema indexing: Background, non-blocking

Optional: SQLite Vector Extension

For faster vector search on large datasets:

# Install sqlite-vec C extension (optional)
bash scripts/install-sqlite-vec.sh

This provides 2-3x faster vector search but is not required.

Troubleshooting

Databases Won't Initialize

# Check permissions
ls -la ~/.howlerops/

# Manually initialize
sqlite3 ~/.howlerops/local.db < backend-go/pkg/storage/migrations/001_init_local_storage.sql

Cloud Sync Not Working

1. Check authentication: Click user menu → verify logged in
2. Check network: Ensure internet connection is active
3. View sync status: Look for sync indicator in header
4. Check conflicts: Go to Settings → Sync → View Conflicts
5. Force sync: Click "Sync Now" in settings
6. Check logs: tail -f ~/.howlerops/logs/sync.log

AI Features Not Working

1. Check AI provider keys in Settings → AI
2. Test provider connection
3. Check logs: tail -f ~/.howlerops/logs/howlerops.log

App Won't Start

# Check system requirements
make doctor

# Verify Node.js version
node --version  # Should be 20.19+ or 22.12+

# Verify Wails
wails doctor

Contributing

See CONTRIBUTING.md for development guidelines.

Pull Request Process

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. CRITICAL: Complete validation checklist:
   • All TypeScript types are valid (npm run typecheck)
   • Frontend code passes linting (npm run lint)
   • Frontend tests pass (npm run test:run)
   • Go modules are tidy (go mod tidy)
   • Go code is formatted (go fmt ./...)
   • Go tests pass (go test ./...)
   • Full validation passes (make validate)
   • Code compiles successfully (make build)
5. Submit pull request

Documentation

Feature Documentation (NEW - Organized!)

Comprehensive documentation for all implemented features:

• Features - Implemented features with detailed guides

  • Auto-Connect - Automatic database reconnection ✅
  • Pagination - Query result pagination ⚠️ In Progress
  • Table Virtualization - Performance optimizations ✅

• Security - Security features and architecture

  • Keychain Integration - OS-native credential storage ✅
  • Password Encryption - Zero-knowledge encryption 🚧 In Progress

• Architecture - System design and technical specs

  • Storage Architecture - Data storage layers
  • Test Database Setup - Docker test environment

• Deployment - Production deployment guides

  • Deployment Overview - Complete deployment guide
  • Migration System - Automatic migrations

User Guides

• User Guide - Complete user manual
• Installation Guide - Detailed installation instructions for all platforms
• Quick Start Guide - Get started in 5 minutes
• AI Setup Guide - Configure AI providers
• Multi-Database Queries - Cross-database queries
• AI/RAG Integration - AI features

Phase 2 Documentation (Cloud Sync & Auth)

• Architecture Overview - System design and components (NEW)
• API Reference - Complete API documentation (NEW)
• Cloud Sync Guide - Multi-device synchronization
• Sync Protocol - Technical sync implementation
• Authentication Guide - Auth system details
• Email Service - Email integration

Developer Guides

• Contributing Guide - Development guidelines
• Storage Architecture - Database design
• Turso Integration - Cloud storage
• Backend API - Backend endpoints
• Frontend Integration - Frontend setup
• Deployment Guide - Production deployment
• Release Process - Creating releases
• Change Log - Version history (NEW)

Technical Specifications

• Phase 2 Tech Specs - Detailed specifications
• Phase 2 Timeline - Project timeline
• Cost Analysis - Infrastructure costs
• Risk Register - Risk management
• Testing Checklist - QA procedures

License

MIT License - see LICENSE file for details.

Acknowledgments

• Built with Wails - Go + React desktop framework
• AI powered by OpenAI, Anthropic, and Ollama
• Local storage powered by SQLite
• Cloud storage powered by Turso - Edge database platform
• Email delivery powered by Resend
• UI components from shadcn/ui
• Vector search powered by sqlite-vec (optional)
• CI/CD by GitHub Actions

Support

• 🐛 Report Bugs
• 💡 Request Features
• 📖 Read Docs
• 💬 Discussions

---

Made with ❤️ by the HowlerOps team