When to Use Standalone

Most teams should start with the serve framework. Reach for standalone @hypequery/clickhouse when you only need the type-safe query builder and prefer to keep authentication, routing, multi-tenancy, caching, and API definitions entirely in your codebase.

Good Use Cases for Standalone

Custom workflows without the serve runtime

When you don't want the serve framework's routing/auth layers and only need the fluent query builder inside existing handlers or RPC endpoints.

Background jobs, scripts, ETL

Use standalone inside cron jobs, ETL workers, or migrations where you already manage retries, authentication, and scheduling.

Internal tools & one-off scripts

Ad-hoc admin tools, diagnostics, or scripts wired directly to ClickHouse without building APIs.

You want to own every concern

Standalone is perfect when you explicitly don’t want the built-in features serve provides:

• You have custom auth/tenant logic and don’t need serve’s auth hooks
• You want to design the HTTP/GraphQL/RPC surface yourself
• Caching, rate limits, logging, and observability live elsewhere in your stack
• You’re happy defining queries inline instead of a central schema
• Your workload is single-tenant or non-user facing so multi-tenancy, OpenAPI, and generated React hooks would be overkill

When NOT to Use Standalone

Consider the serve framework instead if you:

• Starting a new project: Serve provides authentication, multi-tenancy, OpenAPI out of the box
• Building dashboards: React hooks give you type-safe UI integration
• Need API endpoints: Serve handles routing, validation, and OpenAPI generation
• Want consistency: Define once, use everywhere (APIs, React, jobs)
• Multi-tenant apps: Built-in tenant isolation with enforced filtering

Comparison

Can I switch later?

Yes! The query builder API is identical. You can:

Start standalone → Add serve later:

npm install @hypequery/serve @hypequery/react

Use both: Use serve for APIs and standalone for background jobs:

// Shared query builder instance
import { createQueryBuilder } from '@hypequery/clickhouse';
import type { Schema } from './generated-schema';

export const db = createQueryBuilder<Schema>(config);

// Use in serve
import { defineServe } from '@hypequery/serve';

export const api = defineServe({
  context: () => ({ db }),
  queries: { /* ... */ }
});

// Use in jobs
await db.table('events').where(...).execute();