Skip to main content

Plans & Previews

Drivers don’t receive a raw SQL string from Ormed. They receive immutable plan objects that represent the intent of an operation.

QueryPlan​

QueryPlan is an immutable description of a read query (filters, joins, selects, eager loads, limits, unions, etc.). A driver executes it via DriverAdapter.execute(plan) and can preview it via DriverAdapter.describeQuery(plan).

In user code, you typically don’t construct a QueryPlan directly. Instead you build a query and call toSql():

StatementPreview previewSelectSql(DataSource dataSource) {
  return dataSource.query<$User>().whereEquals('email', 'a@b.com').toSql();
}

MutationPlan​

MutationPlan describes write operations (insert/update/delete/upsert and query-based updates/deletes). A driver executes it via DriverAdapter.runMutation(plan) and can preview it via DriverAdapter.describeMutation(plan).

Repositories expose preview helpers that build the same mutation plans as the write methods:

StatementPreview previewInsertSql(DataSource dataSource) {
  final repo = dataSource.repo<$User>();
  return repo.previewInsert({'email': 'a@b.com'});
}

StatementPreview​

Drivers return a StatementPreview for both queries and mutations. It contains:

  • sql (or a non-SQL summary for non-SQL backends)
  • parameters (single execution parameter bag)
  • parameterSets (optional: batched executions / bulk inserts)
  • metadata used by logging (driver name, connection info, etc.)

This is the object Ormed uses for logging, diagnostics, and “pretend” mode.

If you are implementing a driver adapter, the goal is:

  • compile plans deterministically
  • return previews that match what execute(...) / runMutation(...) will do