The Grimoire

Arcane Documentation

Everything you need to master the four core spells. From first incantation to advanced sorcery.

Getting Started

Welcome, apprentice. Before you can wield the arcane arts, you'll need to set up your enchantment circle. Here's how to begin.

Installation

QueryMage is available as a CLI tool, a VS Code extension, and a REST API. Choose your weapon:

# Via npm (recommended)
npm install -g @querymage/cli

# Via pip
pip install querymage

# Via Homebrew
brew install querymage

Authentication

After installation, authenticate with your Archmage token:

querymage auth login
# Opens browser for OAuth flow
# Or use API key directly:
querymage auth set-key YOUR_API_KEY

Connect Your Schema

QueryMage works best when it understands your database structure. Feed it your DDL:

# From a SQL file
querymage connect --schema ./schema.sql

# From a live database
querymage connect --url "postgresql://user:pass@host:5432/db"

# Describe it in plain English
querymage connect --describe "users table with id, name, email; orders table with id, user_id, total, created_at"

Incantation Translation (Prompt-to-SQL)

The foundational spell. Transform natural language into production-ready SQL queries. Supports multiple dialects out of the box.

Supported Dialects

  • PostgreSQL — Full support including CTEs, window functions, JSONB operations
  • MySQL 8.0+ — Including recursive CTEs and JSON functions
  • ClickHouse — Columnar-optimized queries with proper aggregation patterns
  • SQLite — Lightweight queries with SQLite-specific syntax
  • SQL Server — T-SQL with proper TOP, OFFSET-FETCH patterns

Usage

# Basic cast
querymage cast "find all users who signed up this month"

# Specify dialect
querymage cast --dialect postgres "monthly revenue by product category"

# With context from connected schema
querymage cast --context "top 10 customers by lifetime value with their last order date"

Pro Tips

Be specific about your requirements. Instead of "get users," try "get active users who placed at least 3 orders in the last 90 days, sorted by total spend descending." The more context, the better the spell.

Performance Crystal Ball (AI Optimization)

Feed your sluggish queries to the AI, and receive instant diagnosis with actionable optimization suggestions.

How It Works

The optimization engine analyzes your query's execution plan, identifies bottlenecks, and suggests improvements across three dimensions:

  • Index Suggestions — Detects missing indexes and recommends optimal indexing strategies
  • Query Rewriting — Refactors subqueries into JOINs, eliminates redundant operations
  • Schema Hints — Identifies denormalization opportunities for read-heavy workloads

Usage

# Optimize a single query
querymage optimize "SELECT * FROM orders WHERE user_id IN (SELECT id FROM users WHERE status = 'active')"

# Analyze slow query log
querymage optimize --log ./slow-query.log

# Get EXPLAIN analysis
querymage explain "your_query_here" --format human

Database Prophecy (Schema Design)

Describe your business scenario, and the AI generates normalized, scalable database schemas complete with indexes and constraints.

Usage

# Generate schema from business description
querymage design "e-commerce platform with users, products, orders, reviews, and a referral program"

# Analyze existing schema for bottlenecks
querymage analyze-schema --file ./current_schema.sql --growth-rate "10x over 2 years"

# Generate migration
querymage migrate --from ./v1_schema.sql --to ./v2_schema.sql

Output Format

The design spell generates complete DDL with:

  • 3NF-compliant table definitions
  • Primary keys, foreign keys, and unique constraints
  • Suggested indexes based on predicted access patterns
  • Partitioning recommendations for large tables
  • Commentary explaining design decisions

Injection Ward (Security Audit)

Automatically scans SQL statements and application code for injection vulnerabilities. Aligned with OWASP Top 10.

Detection Capabilities

  • SQL Injection — Classic, blind, time-based, and second-order injection patterns
  • Privilege Escalation — Detects overly permissive queries and role misconfigurations
  • Data Exposure — Flags queries that might leak sensitive columns (PII, passwords)
  • Dynamic SQL Risks — Identifies unsafe string concatenation in query building

Usage

# Scan a single query
querymage audit "SELECT * FROM users WHERE name = '" + userInput + "'"

# Scan a codebase
querymage audit --dir ./src --lang python

# CI/CD integration
querymage audit --ci --fail-on high --report ./security-report.json

API Reference

All QueryMage spells are available via REST API. Base URL: https://api.querymage.dev/v1

Authentication

Include your API key in the Authorization header:

Authorization: Bearer qm_live_xxxxxxxxxxxx

Endpoints

POST /cast          # Generate SQL from natural language
POST /optimize      # Optimize an existing query
POST /design        # Generate schema design
POST /audit         # Security scan
GET  /usage         # Check token usage
GET  /health        # API health status

Example Request

curl -X POST https://api.querymage.dev/v1/cast \
  -H "Authorization: Bearer qm_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "top 10 customers by revenue last quarter",
    "dialect": "postgresql",
    "schema_id": "sch_abc123"
  }'

Frequently Asked Questions

Is my data safe?

Absolutely. QueryMage uses zero-knowledge architecture. Your schemas are processed in ephemeral sessions and never stored or used for training. We're SOC 2 Type II compliant.

Which databases do you support?

PostgreSQL, MySQL, ClickHouse, SQLite, SQL Server, and MariaDB. Oracle and Snowflake are on the roadmap.

Can I self-host QueryMage?

Enterprise customers can deploy QueryMage in their own VPC or on-premises environment. Contact our team for details.

How accurate are the generated queries?

Our benchmark shows 99.7% syntactic accuracy and 96.2% semantic accuracy on complex multi-table queries. Every generated query includes a confidence score.

What happens if I exceed my token limit?

You'll receive a gentle notification and can upgrade your plan instantly. We never cut off mid-spell — your current query will always complete.