Performance Guide

This guide covers the practical levers Disc exposes for query performance: indexing strategies, EXPLAIN-based diagnosis, the parse/compile/EXPLAIN caches, the connection pool, and the Prometheus gauges that reveal pressure on each of those subsystems.

Related documentation: Schema | Server Configuration | Production Deployment | Bundled PostgreSQL

Indexing

Disc translates SDL index on (...) clauses into PostgreSQL indexes during migration. The differ supports btree (default), hash, gist, gin, and brin methods (migration/types.ts IndexDefinition.method). Pick the method based on the access pattern:

Single-property index on User.name:

type User {
  required name: str;
  index on (.name);
};

Expression index on lower(email):

type User {
  required email: str;
  index on (str_lower(.email));
};

Composite index on (last_name, first_name):

type Person {
  required first_name: str;
  required last_name: str;
  index on ((.last_name, .first_name));
};

See Schema → Indexes for the full SDL grammar (named indexes, annotated indexes, multi-property composites).

Choosing what to index

Index the columns that appear in filter, order by, and group by clauses on hot queries. The foreign-key column of every single link is indexed automatically (idx_<table>_<link>_id), so Post filter .author = <uuid>$id already uses an index and a plain index on (.author) is skipped as redundant. Composite lookups need their own index: filter .author = <uuid>$a and .status = <str>$s wants index on ((.author, .status)), and a type-level constraint exclusive on ((.program, .object_id)) gives you a unique composite index for free that filter .program.id = <uuid>$p and .object_id in array_unpack(<array<str>>$ids) will use once the table has enough rows for the planner to prefer it. Don’t over-index: every additional index slows down writes and consumes disk.

Verifying an index is used

Use EXPLAIN (below) to confirm PostgreSQL actually picks the index for the planned query. A Seq Scan on a column you indexed usually means the predicate isn’t sargable (e.g. lower(email) = $1 against an index on email — switch to an expression index).

EXPLAIN

EdgeQL’s analyze keyword produces the underlying PostgreSQL EXPLAIN ANALYZE for a query, surfaced through Disc’s compiler. Use it to diagnose slow queries.

From the shell

disc> analyze select User { email, name } filter .email = "ada@example.com";

Seq Scan on user u  (cost=0.00..18.50 rows=1 width=64)
  Filter: (email = 'ada@example.com'::text)

From the SDK

const plan = await client.explain(
  `select User { email, name } filter .email = <str>$email`,
  { email: "ada@example.com" }
);

console.log(plan);

EXPLAIN cache

Disc caches EXPLAIN plan results in lib/explain-cache.ts to keep the admin UI’s query analyzer responsive. The TTL is configurable via DISC_EXPLAIN_CACHE_TTL (default 300 000 ms / 5 minutes). The cache is keyed by the compiled SQL plus parameter signature — semantically identical EdgeQL with different literal arguments shares one entry.

For ad-hoc diagnosis on a stale query plan, restart the server or wait for the TTL to expire. EXPLAIN cache hits are not currently exposed as a metric; the cache is best-effort.

Reading the plan

Look for these signals in the plan output:

For complex EdgeQL with nested shapes, the generated SQL uses lateral subqueries; EXPLAIN ANALYZE reflects those as nested loops. That’s expected — the goal is not avoiding loops but ensuring each iteration uses an index.

Parse and Compilation Caches

Disc caches both EdgeQL parse trees and compiled SQL output. A repeated query with the same shape reuses both stages.

Cache size

DISC_CACHE_MAX_SIZE=1000   # Default: 1000 entries each for parse + compile

Each entry holds a parsed AST or a compiled SQL string. Increase for large schemas with many distinct queries; reduce on memory-constrained hosts.

Cache key cardinality

The compiled-SQL cache is keyed by EdgeQL source plus role-derived access context (lib/query-cache.ts hashAccessContext). The key intentionally hashes only the role, not userId — different users with the same role share one compiled-SQL entry, since user identity is bound at parameter time ($user_id), not compile time. This dramatically reduces cache pressure for multi-tenant deployments where every user runs the same select Post filter .author = $self.

Hit-rate metrics

Both caches expose Prometheus counters via /metrics:

• disc_parse_cache_hits_total, disc_parse_cache_misses_total, disc_parse_cache_size
• disc_query_cache_hits_total, disc_query_cache_misses_total, disc_query_cache_evictions_total, disc_query_cache_size

Aim for a disc_query_cache_hits_total / (hits + misses) ratio above 0.7. Lower than that suggests churn — either cacheMaxSize is too small, or the schema is being reloaded faster than entries can warm up.

Cache invalidation

Caches are flushed on schema reload (SIGHUP, disc migrate, or admin-UI schema edit). Plan accordingly: a quiet redeploy followed by a migration causes a brief cold-cache window where the first request for each query pays the parse + compile cost.

Connection Pool

The PostgreSQL connection pool (lib/connection-pool.ts) sizes itself between minConnections (default 2) and maxConnections (default 10 inside the library, 100 on the server). The server’s pool is configured via DISC_MAX_CONNECTIONS, and it is the pool the query handler and open transactions draw from — an open transaction pins one connection until it commits or rolls back. The cap is enforced under concurrent load: callers beyond it queue (up to maxWaitQueueSize, each for at most connectionTimeout) rather than opening extra connections, and past the queue limit acquire() throws Connection pool wait queue is full.

Sizing

Total Disc connections across all instances must stay below PostgreSQL’s max_connections:

DISC_MAX_CONNECTIONS * disc_instance_count <= pg_max_connections - 5

See Production Deployment → Connection Pool Tuning for a deployment-size matrix.

Pool tunables

When constructing a pool programmatically (new ConnectionPool(...)), these knobs control behavior:

Pool health metrics

Surface via /metrics:

• disc_pool_connections_total — total connections (active + idle).
• disc_pool_connections_active — currently acquired.
• disc_pool_connections_idle — pooled but not in use.
• disc_pool_waiters — requests blocked waiting for a connection.

Sustained disc_pool_waiters > 0 is the canonical pool-pressure signal. When you see it:

1. Raise DISC_MAX_CONNECTIONS if the database has headroom.
2. Look for slow queries holding connections (slow-query log, EXPLAIN).
3. Add another Disc instance horizontally.
4. Insert PgBouncer in transaction mode for very high concurrency.

The full troubleshooting recipe lives in Production Deployment → Connection Pool Exhaustion.

Slow Query Logging

Set DISC_SLOW_QUERY_MS to log queries that exceed a threshold:

DISC_SLOW_QUERY_MS=200   # Log queries slower than 200ms

Each slow query emits a log line with the query hash, duration, parse/compile/execute split, and (when log level is DEBUG) the full EdgeQL text. Pair with the structured-JSON log format in production so an aggregator can index by query_hash and surface trends.

DISC_SLOW_QUERY_MS=0 disables the threshold.

Prometheus Gauges to Watch

A complete production dashboard should track these gauges over time:

The disc_tls_certificate_seconds_until_expiry gauge from Production Deployment → TLS is the alerting hook for cert renewal.

When in Doubt

1. Run analyze <query> from disc shell.
2. Check /stats for cache hit rate and pool waiters.
3. Compare disc_query_avg_compile_ms over time — a rising trend means schema growth or cache churn.
4. Profile the slowest queries from the slow-query log against PostgreSQL EXPLAIN ANALYZE directly.

Most performance work in Disc is one of: missing index, undersized pool, or cache thrash. Identify which one with the metrics above before reaching for code changes.

Benchmark Suite

Disc ships a deno bench suite in benchmarks/ for measuring the pure-CPU stages of the pipeline -- parsing, compilation, codegen, schema diffing, and cache behaviour. Use it to catch regressions in the compiler when you change it; use the EXPLAIN and Prometheus tooling above for query-level work against real data.

deno task bench

The bench:pg task runs the same suite with DISC_PG_AUTO=1, matching the test:pg convention so PG-backed benchmarks can be added under the same harness:

deno task bench:pg

Suites

The compiler, parser, and pipeline suites all run the same query set -- simple select, filtered select, nested shape, insert, update, delete, and ordered-and-limited -- so a slowdown can be attributed to a stage by comparing the three.

Adding a Benchmark

Benchmarks are plain Deno.bench() calls; the suite runs with --allow-all --no-check. Name cases "<stage>: <case>" (for example "compile: nested shape") so results group readably in the output table, and build fixtures from createTestSchema() in compiler/context.ts rather than hitting a live database -- these suites are deliberately in-process so they stay deterministic.

See Also

• Schema → Indexes — full SDL syntax for indexes
• Server Configuration — cache / pool / metrics environment variables
• Production Deployment — sizing, health checks, troubleshooting
• EdgeQL → EXPLAIN — analyze semantics
• Bundled PostgreSQL — PG configuration knobs that feed the pool
• Testing — running the test suite the benchmarks share fixtures with