From clickhouse-pack
Configures ClickHouse query concurrency, memory quotas, per-user limits, and client pooling to resolve 'too many simultaneous queries' and resource errors.
How this skill is triggered — by the user, by Claude, or both
Slash command
/clickhouse-pack:clickhouse-rate-limitsThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
ClickHouse does not have REST API rate limits like a SaaS product. Instead, it has
ClickHouse does not have REST API rate limits like a SaaS product. Instead, it has server-side concurrency limits, memory quotas, and per-user settings that control resource usage. This skill covers how to configure and work within those limits.
| Setting | Default | Description |
|---|---|---|
max_concurrent_queries | 100 | Max queries running simultaneously |
max_connections | 4096 | Max TCP/HTTP connections |
max_memory_usage | ~10GB | Per-query memory limit |
max_execution_time | 0 (unlimited) | Per-query timeout in seconds |
max_threads | CPU cores | Threads per query |
ClickHouse Cloud API limit: The Cloud management API (not the query interface) is limited to 10 requests per 10 seconds.
-- Create a quota that limits query resources per user
CREATE QUOTA IF NOT EXISTS app_quota
FOR INTERVAL 1 HOUR MAX
queries = 10000,
result_rows = 100000000,
read_rows = 1000000000,
execution_time = 3600
TO app_user;
-- Create a profile with resource limits
CREATE SETTINGS PROFILE IF NOT EXISTS app_profile
SETTINGS
max_memory_usage = 5000000000, -- 5GB per query
max_execution_time = 30, -- 30s timeout
max_threads = 4, -- 4 threads per query
max_concurrent_queries_for_user = 10 -- 10 parallel queries
TO app_user;
import { createClient } from '@clickhouse/client';
// The @clickhouse/client manages HTTP keep-alive connections internally
const client = createClient({
url: process.env.CLICKHOUSE_HOST!,
username: process.env.CLICKHOUSE_USER!,
password: process.env.CLICKHOUSE_PASSWORD!,
max_open_connections: 10, // Connection pool size
request_timeout: 30_000, // 30s per request
compression: {
request: true, // Compress request bodies (saves bandwidth)
response: true, // Decompress responses
},
});
import PQueue from 'p-queue';
// Limit concurrent ClickHouse queries from your app
const queryQueue = new PQueue({
concurrency: 5, // Max 5 concurrent queries
timeout: 30_000, // 30s timeout per query
throwOnTimeout: true,
});
async function rateLimitedQuery<T>(sql: string): Promise<T[]> {
return queryQueue.add(async () => {
const rs = await client.query({ query: sql, format: 'JSONEachRow' });
return rs.json<T>();
});
}
async function queryWithRetry<T>(
sql: string,
maxRetries = 3,
): Promise<T[]> {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
try {
const rs = await client.query({ query: sql, format: 'JSONEachRow' });
return await rs.json<T>();
} catch (err: any) {
const msg = err.message ?? '';
const isRetryable =
msg.includes('TOO_MANY_SIMULTANEOUS_QUERIES') ||
msg.includes('TIMEOUT_EXCEEDED') ||
msg.includes('NETWORK_ERROR');
if (!isRetryable || attempt === maxRetries) throw err;
const delay = 1000 * Math.pow(2, attempt) + Math.random() * 500;
await new Promise((r) => setTimeout(r, delay));
}
}
throw new Error('Unreachable');
}
-- Currently running queries
SELECT user, count() AS running_queries, sum(memory_usage) AS total_memory
FROM system.processes
GROUP BY user;
-- Query queue depth (if queries are waiting)
SELECT metric, value FROM system.metrics
WHERE metric IN ('Query', 'MaxConcurrentQueries', 'TCPConnection', 'HTTPConnection');
-- Historical peak concurrency
SELECT
toStartOfMinute(event_time) AS minute,
max(ProfileEvents['ConcurrentQuery']) AS peak_concurrent
FROM system.query_log
WHERE event_time >= now() - INTERVAL 1 HOUR
GROUP BY minute
ORDER BY minute;
// Buffer inserts to avoid "too many parts"
class InsertBuffer<T extends Record<string, unknown>> {
private buffer: T[] = [];
private timer: NodeJS.Timeout | null = null;
constructor(
private client: ReturnType<typeof import('@clickhouse/client').createClient>,
private table: string,
private batchSize = 10_000,
private flushIntervalMs = 5_000,
) {}
async add(row: T) {
this.buffer.push(row);
if (this.buffer.length >= this.batchSize) {
await this.flush();
} else if (!this.timer) {
this.timer = setTimeout(() => this.flush(), this.flushIntervalMs);
}
}
async flush() {
if (this.timer) { clearTimeout(this.timer); this.timer = null; }
if (this.buffer.length === 0) return;
const batch = this.buffer.splice(0);
await this.client.insert({ table: this.table, values: batch, format: 'JSONEachRow' });
}
}
| Error | Code | Solution |
|---|---|---|
TOO_MANY_SIMULTANEOUS_QUERIES | 202 | Reduce concurrency or increase max_concurrent_queries |
MEMORY_LIMIT_EXCEEDED | 241 | Lower max_threads, add query filters |
TIMEOUT_EXCEEDED | 159 | Increase max_execution_time or optimize query |
TOO_MANY_PARTS | 252 | Batch inserts, wait for merges |
For security hardening, see clickhouse-security-basics.
npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin clickhouse-packProvides patterns for @clickhouse/client: typed queries, streaming inserts with backpressure, batch inserts with retry, error handling. For robust ClickHouse Node.js integrations.
Reviews ClickHouse schemas, queries, and configurations using 31 prioritized rules across schema design, query optimization, data ingestion, and agent connectivity. Essential when working with ClickHouse databases.
Provides ClickHouse patterns for table design with MergeTree engines, query optimization via efficient filtering and aggregations, and best practices for high-performance analytics workloads.