Migration from @subql/query

1. Overview

omnihedron is a high-performance Rust reimplementation of @subql/query, the GraphQL query service for SubQuery Network indexers. The TypeScript original uses PostGraphile to auto-generate a GraphQL API from a live PostgreSQL schema. omnihedron replicates that behaviour entirely in Rust, producing an identical external API.

Why migrate?

• 6-12x higher throughput under concurrent load (benchmarked on real SubQuery databases)
• 2-5x lower p99 tail latency — Rust p99 stays under 2s at 5,000 concurrency; TypeScript hits 30s timeout
• 8.7x less memory under load (47 MB vs 408 MB peak RSS at concurrency=500)
• No event loop saturation — TypeScript collapses at ~5,000 concurrent connections; Rust maintains stable throughput past 10,000
• No GC pauses or JIT deoptimisations
• Native multi-core dispatch via Tokio

What stays identical

• The generated GraphQL schema is the same (verified by CI introspection tests comparing 716+ types)
• Query syntax — all existing queries, filters, ordering, pagination, aggregates work unchanged
• Database compatibility — connects to the same PostgreSQL database with the same schema
• Cursor format — base64-encoded JSON, fully compatible
• nodeId format — base64-encoded ["TypeName", pkValue], fully compatible
• Environment variables for database connection (DB_HOST, DB_PORT, DB_USER, DB_PASS, DB_DATABASE)

2. Quick start — drop-in replacement

Step 1: Stop the TypeScript service

# If running via docker compose
docker compose stop subql-query-ts

# If running directly
kill $(pgrep -f "subql-query")

Step 2: Pull the omnihedron image (or build from source)

# Docker Hub
docker pull polytopelabs/omnihedron:latest

# Or build from source
cargo build --release

Step 3: Start omnihedron with equivalent flags

# TypeScript command:
#   subql-query --name my_project --port 3000 --unsafe

# Rust equivalent:
omnihedron --name my_project --port 3000 --unsafe-mode

Step 4: Verify

# Health check
curl http://localhost:3000/health

# Run a test query
curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -d '{"query": "{ _metadata { lastProcessedHeight } }"}'

No client-side changes are needed. The GraphQL schema, endpoints, and response format are identical.

3. CLI flag mapping

4. Feature parity table

5. Known divergences

5.1 Aggregates: count field

Impact: Queries using aggregates { count } will work on omnihedron but fail on the TypeScript service. If you need to support both during migration, use totalCount on the connection instead.

5.2 Aggregate helper types

omnihedron does not generate certain PostGraphile aggregate helper types that are present in the TypeScript schema but unused by standard queries:

• Having* types
• *AggregatesFilter types
• *AggregateFilter types
• *ToMany* filter helper types

These types exist in the PostGraphile schema for advanced pg-aggregates plugin features that are not used by SubQuery indexer consumers. If your client introspects the schema and caches type definitions, be aware the type set is slightly smaller.

5.3 Naming conventions

Both services use identical PostGraphile-compatible naming:

• snake_case columns become camelCase fields
• Table names are singularized for type names (transfers -> Transfer)
• Leading underscores are preserved (_global -> _Global)
• Consecutive uppercase runs are normalised (cumulative_volume_u_s_ds -> CumulativeVolumeUsds)
• Latin neuter irregulars handled (metadata -> Metadatum)

The inflection logic in omnihedron has been verified against PostGraphile's exact output for all 716+ types in the test database. No naming divergences are expected.

5.4 Error message format

Both services return standard GraphQL error responses ({ "errors": [...] }), but the error message text may differ:

• Query validation errors (depth, complexity, alias limits) use omnihedron-specific wording
• Database errors surface the PostgreSQL error message directly in both, but omnihedron may include different context
• Batch request errors are returned per-item in the response array on both services

5.5 Subscriptions

Both services support WebSocket subscriptions via the graphql-ws protocol. omnihedron uses the async-graphql-axum WebSocket handler. Subscription behaviour is functionally equivalent but the underlying implementation differs (PostGraphile LISTEN/NOTIFY vs async-graphql's subscription engine).

5.6 Query timeout enforcement

• @subql/query: enforces timeout at the application layer (Node.js)
• omnihedron: enforces timeout via PostgreSQL's statement_timeout set on every pool connection, letting the database kill long-running queries directly

5.7 first: 0 behaviour

omnihedron treats first: 0 as unset (matching JavaScript's truthiness semantics where 0 is falsy). This matches the TypeScript service behaviour.

6. New features in omnihedron

6.1 Query validation with response headers

omnihedron returns query complexity information in response headers:

query-complexity: 42
max-query-complexity: 1000

This allows clients to monitor how close their queries are to the complexity limit without hitting errors.

6.2 Schema hot reload

Enabled by default. A dedicated PostgreSQL connection listens on the SubQuery schema channel. When a schema_updated notification arrives, introspection reruns and the schema is atomically swapped. In-flight requests are unaffected.

Disable with --disable-hot-schema if you prefer manual restarts. Configure the keep-alive interval with --sl-keep-alive-interval (default: 180,000 ms).

6.3 Prometheus metrics

Enable with --metrics. Exposes a /metrics endpoint with:

• omnihedron_http_requests_total (counter) — labeled by method, path, status
• omnihedron_http_request_duration_seconds (histogram) — labeled by method, path
• GraphQL-level counters for queries and errors

6.4 SQL EXPLAIN logging

Enable with --query-explain to log the PostgreSQL EXPLAIN output for every query at trace level. Useful for identifying slow queries and missing indexes during migration testing.

6.5 Fulltext search

omnihedron supports SubQuery's @fullText directive. PostgreSQL functions created by the indexer (pattern: search_{hash}(search text) RETURNS SETOF table) are automatically detected and exposed as root query fields with the GraphQL name from the function comment (@name search_{table}).

6.6 Read replicas

Set the DB_HOST_READ environment variable to route read queries to a replica:

DB_HOST=primary.db.example.com
DB_HOST_READ=replica.db.example.com

Subscription connections always use the primary host.

6.7 PostgreSQL TLS (mTLS)

omnihedron --name my_project \
  --pg-ca /path/to/ca.crt \
  --pg-key /path/to/client.key \
  --pg-cert /path/to/client.crt

6.8 Selective query optimisation

omnihedron automatically optimises queries:

• Selective column fetching — only columns referenced in the GraphQL selection set are included in the SQL SELECT
• Selective aggregate computation — only requested aggregate functions (sum, min, max, etc.) are computed in SQL
• Count-only fast path — queries requesting only totalCount (no nodes/edges) skip row fetching entirely
• Window function — COUNT(*) OVER() fetches total count and rows in a single SQL round-trip

6.9 Response compression and caching

• Automatic gzip/deflate compression via Tower's CompressionLayer
• Cache-Control: public, max-age=5 header on all responses

7. Environment variables mapping

Database connection (identical)

Application configuration

Performance tip: Tokio worker threads

Tokio defaults to one worker thread per CPU core. On many-core machines this inflates memory from thread stacks (128 cores x 2 MB = 256 MB idle). For a PostgreSQL-bound service with a pool of 10 connections, 8-16 worker threads is optimal:

TOKIO_WORKER_THREADS=8

8. Docker migration

Before: @subql/query

services:
  subql-query:
    image: subquerynetwork/subql-query:latest
    environment:
      DB_HOST: postgres
      DB_PORT: "5432"
      DB_USER: postgres
      DB_PASS: postgres
      DB_DATABASE: indexer
    ports:
      - "3000:3000"
    command: ["--name", "my_project", "--port", "3000", "--unsafe"]

After: omnihedron

services:
  omnihedron:
    image: polytopelabs/omnihedron:latest
    environment:
      DB_HOST: postgres
      DB_PORT: "5432"
      DB_USER: postgres
      DB_PASS: postgres
      DB_DATABASE: indexer
      OMNIHEDRON_LOG_LEVEL: info
      # Optional: limit worker threads on many-core machines
      # TOKIO_WORKER_THREADS: "8"
    ports:
      - "3000:3000"
    command: ["--name", "my_project", "--port", "3000", "--unsafe-mode"]
    restart: unless-stopped

Key changes in docker-compose.yml

1. Image: subquerynetwork/subql-query:latest -> polytopelabs/omnihedron:latest
2. --unsafe -> --unsafe-mode (the only renamed flag)
3. DB env vars stay the same (DB_HOST, DB_PORT, DB_USER, DB_PASS, DB_DATABASE)
4. Optional: Add OMNIHEDRON_LOG_LEVEL, OMNIHEDRON_METRICS, TOKIO_WORKER_THREADS

Building from source with Docker

services:
  omnihedron:
    build:
      context: .
      dockerfile: docker/Dockerfile
    environment:
      DB_HOST: postgres
      DB_PORT: "5432"
      DB_USER: postgres
      DB_PASS: postgres
      DB_DATABASE: indexer
    ports:
      - "3000:3000"
    command: ["--name", "my_project", "--port", "3000", "--unsafe-mode"]

9. Testing the migration — side-by-side comparison

The recommended approach is to run both services in parallel and compare responses before cutting over.

Step 1: Run both services

# docker-compose.yml
services:
  postgres:
    image: postgres:17
    environment:
      POSTGRES_DB: indexer
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"

  subql-query-ts:
    image: subquerynetwork/subql-query:latest
    environment:
      DB_HOST: postgres
      DB_PORT: "5432"
      DB_USER: postgres
      DB_PASS: postgres
      DB_DATABASE: indexer
    ports:
      - "3001:3001"
    command: ["--name", "my_project", "--port", "3001", "--unsafe"]

  omnihedron:
    image: polytopelabs/omnihedron:latest
    environment:
      DB_HOST: postgres
      DB_PORT: "5432"
      DB_USER: postgres
      DB_PASS: postgres
      DB_DATABASE: indexer
    ports:
      - "3000:3000"
    command: ["--name", "my_project", "--port", "3000", "--unsafe-mode"]

Step 2: Compare responses

# Query both services with the same request and diff the output
QUERY='{"query": "{ transfers(first: 5, orderBy: [ID_ASC]) { nodes { id blockNumber } } }"}'

TS_RESP=$(curl -s http://localhost:3001 -H "Content-Type: application/json" -d "$QUERY")
RS_RESP=$(curl -s http://localhost:3000 -H "Content-Type: application/json" -d "$QUERY")

# Compare (should be identical)
diff <(echo "$TS_RESP" | jq -S .) <(echo "$RS_RESP" | jq -S .)

Step 3: Compare schema introspection

INTROSPECTION='{"query": "{ __schema { types { name fields { name type { name kind ofType { name } } } } } }"}'

TS_TYPES=$(curl -s http://localhost:3001 -H "Content-Type: application/json" -d "$INTROSPECTION" | jq -S '.data.__schema.types | sort_by(.name)')
RS_TYPES=$(curl -s http://localhost:3000 -H "Content-Type: application/json" -d "$INTROSPECTION" | jq -S '.data.__schema.types | sort_by(.name)')

diff <(echo "$TS_TYPES") <(echo "$RS_TYPES")

Note: Some PostGraphile-internal types (e.g., Having*, *AggregatesFilter) will be absent from the omnihedron schema. Filter these from the diff if needed.

Step 4: Run the omnihedron integration tests

The project includes 62 integration tests that verify correctness:

# Clone the omnihedron repo and run its test suite against your database
git clone https://github.com/polytope-labs/omnihedron.git
cd omnihedron
cargo test

10. Troubleshooting

"Unknown flag --unsafe"

omnihedron renamed --unsafe to --unsafe-mode. Update your command or set OMNIHEDRON_UNSAFE=true.

Schema types are missing or different

1. Verify both services connect to the same PostgreSQL schema:

   curl http://localhost:3000/health | jq .

2. Check that the --name flag matches your PostgreSQL schema name exactly.
3. If using hot reload, wait a few seconds for the schema to refresh, or restart omnihedron.

Queries return fewer/more results than expected

• Check --query-limit (default: 100). If you were previously using --unsafe with no limit, set --unsafe-mode on omnihedron or specify an explicit --query-limit.
• Ensure first/last/offset arguments in your queries match expectations. omnihedron clamps negative values to zero and treats first: 0 as unset (same as TypeScript).

aggregates { count } works on omnihedron but fails on TypeScript

This is expected. omnihedron adds a count field to {Entity}Aggregates that PostGraphile does not expose. If you need to work with both services, use totalCount on the connection instead.

Connection pool exhaustion

omnihedron defaults to a pool of 10 connections (--max-connection 10). Under very high load, increase this value. Also consider setting TOKIO_WORKER_THREADS to match your pool size (8-16 is optimal for most deployments).

High memory usage on many-core machines

Tokio defaults to one worker thread per CPU core. Each thread allocates up to 2 MB of stack. On a 128-core machine, this alone accounts for ~256 MB of idle memory. Set TOKIO_WORKER_THREADS=8 (or 16) to reduce this.

Query timeout errors

omnihedron enforces timeouts via PostgreSQL's statement_timeout (default: 10,000 ms). If you see canceling statement due to statement timeout errors:

# Increase to 30 seconds
omnihedron --name my_project --query-timeout 30000

WebSocket subscriptions not working

Ensure --subscription is passed (it is off by default). The WebSocket endpoint is at /ws:

ws://localhost:3000/ws

Log output is hard to read

Switch to structured JSON logging for production:

omnihedron --output-fmt json --log-level info

Or write to a file with rotation:

omnihedron --log-path /var/log/omnihedron.log --log-rotate

PostgreSQL TLS connection errors

If your database requires TLS, provide the certificate paths:

omnihedron --name my_project \
  --pg-ca /path/to/ca.crt \
  --pg-key /path/to/client.key \
  --pg-cert /path/to/client.crt

Debugging query performance

Enable SQL EXPLAIN logging to identify slow queries:

omnihedron --name my_project --query-explain --log-level trace

Enable Prometheus metrics for ongoing monitoring:

omnihedron --name my_project --metrics
# Then scrape http://localhost:3000/metrics