MaestroQL

Conduct your SQL queries with precision.

A component-based TypeScript library for orchestrating complex SQL queries with CTEs, joins, and pagination. Think of it as React for SQL: reusable components that compose into powerful queries.

Full Documentation

Visit maestroql.dev for:

• Getting Started Tutorial
• Complete API Reference
• Real-World Examples
• Performance Guides
• Database Indexing Best Practices

Quick Start

Installation

npm install @maestroql/composer

Basic Example

import { buildComplexSQL } from '@maestroql/composer';
import type { SQLQuery, WithSubquerySQL } from '@maestroql/composer';

// Define a reusable component
const postComments: WithSubquerySQL = {
  name: "post_comments",
  alias: "pc",
  query: `
    SELECT post_id, JSON_ARRAYAGG(
      JSON_OBJECT('id', id, 'content', content)
    ) as comments
    FROM comments
    GROUP BY post_id
  `,
  joinType: "LEFT JOIN",
  joinOn: "pc.post_id = p.id",
  fields: {
    comments: "COALESCE(pc.comments, JSON_ARRAY())"
  }
};

// Compose it into a query
const postsQuery: SQLQuery = {
  sourceTable: "posts",
  alias: "p",
  fields: { id: "p.id", title: "p.title" },
  withSubqueries: [postComments]
};

// Build and execute
const { query, params } = buildComplexSQL(postsQuery);
const results = await db.query(query, params);

Features

• Component-Based - Reusable SQL components
• Type-Safe - Full TypeScript support
• Single Query - Eliminate N+1 problems
• Testable - Test components in isolation
• Production Ready - Pagination, sorting, parameter binding

Documentation

• Getting Started - Build your first component in 10 minutes
• API Reference - Complete interface documentation
• Database Indexes - Essential performance guide

Links

• Website
• GitHub
• npm

License

MIT