Skip to content

Upgrading

This page tracks user-facing deltas between consecutive releases. For the .surql migration file format (which has not changed), see Migrations.

Upgrading 0.2.5 -> 0.2.6

0.2.6 is a maintenance release. No public-API breaking changes.

  • TLS dependency openssl bumped to 0.10.80 to close CVE-2026-45784 (medium severity, AES-KW-PAD out-of-bounds write). The crate's default backend is client-rustls, which does not link openssl; the bump only affects consumers that opt into the client / client-tls features.
  • Security Audit workflow rewired to a direct cargo audit invocation so the daily scheduled scan no longer relies on a Node.js 20 action that the runner is being upgraded off.
  • CI matrix on push / pull-request now runs the stable toolchain only; beta coverage moved to the daily Nightly workflow.
  • New documentation pages: Connection Management, Caching, and Orchestration.

Upgrading 0.1.x -> 0.2.x

API deltas between the 0.1.0 feature-complete release and the 0.2.0 query-UX surface.

TL;DR

  • No removals. Every 0.1.x public item is still present in 0.2.x.
  • SurrealDB driver bumped to 3.x (crate feature-gated). Several SurrealQL shapes were adjusted - see v3 patterns.
  • New crate-root helpers: type_record, type_thing, extract_many, has_result.
  • New builder methods: Query::select_expr, Query::execute.
  • New aggregation API: AggregateOpts, aggregate_records, build_aggregate_query.
  • Full-tree CLI now lands behind the cli feature.
  • Pre-push hook + CONTRIBUTING.md added; no runtime effect.

Step-by-step

1. Bump the dependency

[dependencies]
oneiriq-surql = "0.2"

The crate still installs from crates.io as oneiriq-surql and is imported as use surql::.... No rename.

2. (Optional) drop boilerplate around v2-era helpers

None of the pre-0.2 helpers were removed, but many calls can be shortened. See Query UX helpers for the full before/after matrix. Representative examples:

0.1.x 0.2.x
execute_query(&client, &q).await? q.execute(&client).await?
Hand-rendered type::thing('task','...') type_record("task", id).to_surql()
extract_result(&raw).into_iter().map(Value::Object).collect() extract_many(&raw)
Stringly-typed select list with manual AS concatenation Query::select_expr(vec![as_(...), ...])
Hand-rolled SELECT count() ... GROUP ALL + extraction glue aggregate_records(client, "t", opts)

3. v3-specific SurrealQL shapes

If your code contained raw SurrealQL passed to client.query(...), check the patterns in v3 patterns. The most common breakages:

  1. type::thing(...) - rename to type::record(...) (or use the type_record helper).
  2. UPSERT INTO <table> [...] - switch to per-record UPSERT <target> CONTENT $data or call batch::upsert_many.
  3. Incoming edges - write FROM <record><-<edge>, not FROM <-<edge><-<record>.
  4. Variable-depth traversal - unroll to a fixed ->edge->? chain per iteration instead of ->edge{d}->.
  5. Datetime inserts - keep the <datetime> $var cast visible in SurrealQL.

4. CLI migration

The CLI shipped partial in 0.1.x and is now complete in 0.2.0 under the cli feature. Existing automation that called ad-hoc SurrealQL through surql db query or surql migrate up keeps working unchanged. New commands:

  • surql migrate squash <FROM> <TO> - squash a contiguous range.
  • surql migrate validate [<VERSION>] - structural validation.
  • surql schema visualize / surql schema export / surql schema inspect.
  • surql orchestrate deploy|status|validate.

See CLI reference for the full tree.

5. Feature flags

0.2.x formalises the feature matrix:

Feature 0.1.x 0.2.x
client default native-tls TLS stack; opt-in since 0.2.3
client-rustls - new in 0.2.2; default since 0.2.3 (pure-Rust TLS, no openssl-sys)
cli partial (migrate only) full tree; implies client + orchestration + settings
cache new MemoryCache backend + CacheManager
cache-redis new RedisCache backend (implies cache)
settings new layered Settings / SettingsBuilder
orchestration new deployment strategies, environment registry
watcher new filesystem watcher

See Feature flags for the detailed matrix.

6. Switching to client-rustls (0.2.2+)

If your CI runner or container does not have libssl-dev installed, swap the default client feature for client-rustls:

[dependencies]
oneiriq-surql = { version = "0.2", default-features = false, features = ["client-rustls"] }

The public API is unchanged -- DatabaseClient, executor::*, crud::*, and every other client-gated item resolves identically. The only difference is that reqwest is configured with rustls-tls-webpki-roots and surrealdb with its rustls feature, so no openssl-sys (or native-tls) enters the dependency graph. Mixing client and client-rustls compiles but pulls both TLS stacks -- pick one per workspace.

Deprecations

None in 0.2.x.

Build / tooling changes

  • CI and the new pre-push hook require cargo clippy --all-targets --all-features -- -D warnings.
  • Rustdoc now builds cleanly under RUSTDOCFLAGS="-D warnings".

Pre-push hook

Optional local hook that mirrors CI (fmt, clippy, doc, nextest). Enable with:

git config --local core.hooksPath .githooks

Full steps in CONTRIBUTING.md.

What's next