Performance Optimization in ormDB

Performance by Design

ormDB is a relational database engine written in Rust that replaces PostgreSQL, MySQL, and SQLite. Performance optimization in ormDB starts with the architecture: graph fetches eliminate N+1 queries, the zero-copy wire protocol eliminates serialization overhead, and query budgets prevent runaway queries. This guide covers how to use these features and tune them for your workload.

Query Budgets

Query budgets are ormDB’s primary mechanism for preventing expensive queries from degrading system performance. A budget is a numeric limit on the computational cost of a single query, measured in internal cost units that account for records scanned, relations traversed, and result size.

Set a default budget per session:

const session = db.session({
  user_id: user.id,
  query_budget: 10000, // default budget for all queries in this session
})

Override the budget on individual queries:

const results = await session.graphFetch('User', {
  include: {
    posts: {
      include: { comments: true },
    },
  },
  budget: 50000, // higher budget for this specific query
})

When a query exceeds its budget, ormDB returns a partial result:

{
  records: [...],  // results gathered before budget exhaustion
  truncated: true,
  budget_consumed: 10000,
  budget_limit: 10000,
}

Budget Strategy

Assign budgets based on the context:

• Public API endpoints: Low budgets (5,000-10,000) to prevent abuse
• Authenticated user requests: Medium budgets (10,000-50,000) for normal application queries
• Admin dashboards: Higher budgets (50,000-200,000) for complex data views
• Background jobs: Highest budgets (200,000+) for batch processing and reports

Fanout Limits

Graph fetches can produce combinatorial explosion when entities have many related records. A user with 1,000 posts, each with 100 comments, produces 100,000 comment records in a single query. Fanout limits cap the number of related records at each level:

graph_fetch User [limit: 50] {
  id, name,
  posts [limit: 20, order_by: { created_at: desc }] {
    id, title,
    comments [limit: 10, order_by: { created_at: desc }] {
      id, body,
      author { id, name }
    }
  }
}

Maximum result size: 50 users x 20 posts x 10 comments = 10,000 comment records. Without fanout limits, the same query could return millions.

Field Selection

Fetch only the fields you need. Over-fetching wastes bandwidth and memory:

// Bad: fetching all fields including large text columns
const users = await db.graphFetch('User', {
  fields: ['*'],
  include: { posts: { fields: ['*'] } },
})

// Good: fetching only needed fields
const users = await db.graphFetch('User', {
  fields: ['id', 'name', 'avatar_url'],
  include: {
    posts: {
      fields: ['id', 'title', 'created_at'],
      limit: 10,
    },
  },
})

Field selection applies at every level of the graph. The zero-copy wire protocol means that selected fields are read directly from the response buffer without materializing unselected fields.

Connection Pooling

ormDB supports connection pooling at the engine level:

const db = new OrmDB('ormdb://localhost:5555/mydb', {
  pool: {
    min: 5,
    max: 20,
    idle_timeout: 30000, // ms
  },
})

Size the pool based on your application’s concurrency. For SaaS applications and microservices, connection pool sizing is especially important. Each connection maintains its own session context (user identity, query budget), so connections are not shared across requests.

Index Optimization

ormDB automatically creates indexes for primary keys and relations. Additional indexes improve performance for filtered queries:

entity Order {
  id: uuid @primary
  status: text @index
  customer_id: uuid @relation(Customer) // auto-indexed
  created_at: timestamp @index
  total: integer

  @index([status, created_at]) // composite index
}

Use composite indexes for queries that filter on multiple columns. The index column order should match your most common query patterns: the most selective column first. For guidance on structuring your entities effectively, see schema design patterns.

Monitoring and Diagnostics

ormDB exposes query statistics for every request:

const result = await db.graphFetch('User', {
  include: { posts: true },
  explain: true,
})

console.log(result.stats)
// {
//   execution_time_ms: 12,
//   budget_consumed: 3400,
//   entities_scanned: 150,
//   relations_traversed: 150,
//   result_records: 750,
//   cache_hits: 120,
// }

The explain flag adds execution statistics without changing the query results. Use this in development to identify queries that consume more budget than expected, scan excessive records, or return more data than your application uses.

Performance in ormDB is not about writing better SQL. It is about setting appropriate budgets, limiting fanout, selecting only needed fields, and letting the engine’s native graph-fetch architecture do the work. See how this compares to traditional approaches in ormDB vs PostgreSQL and ormDB vs traditional ORMs.