bevy_persistence_database

Persistence for Bevy ECS to ArangoDB or Postgres with an idiomatic Bevy Query API.

Highlights

Bevy Query API consistency
- PersistentQuery SystemParam derefs to Bevy’s Query, so iter/get/single/get_many/contains/iter_combinations work as usual.
- Explicit load trigger: ensure_loaded performs DB I/O, then you use pass-throughs on world data.
Smart caching and explicit refresh
- Identical loads in the same frame coalesce into a single DB call.
- Repeated identical loads hit the cache. Use force_refresh to bypass it.
Presence and value filters
- Type-driven presence via With, Without, and Or<(…)>.
- Optional components in Q (Option<&T>) are fetched when present.
- Value filters: eq, ne, gt, gte, lt, lte, combined with and/or/in.
- Key filtering via Guid::key_field().eq("…") or .in_([...]).
Resources
- #[persist(resource)] resources are persisted and fetched alongside any query.
Optimistic concurrency and conflict handling
- Per-document versioning with conflict detection.
Batching and parallel commit
- Configurable batching with a thread pool and concurrent transaction execution.
Backends
- ArangoDB and Postgres, selected at build time via features.

Install Add the core and derive crates, enabling one or both backends.

[dependencies]
bevy = { version = "0.16" }
bevy_persistence_database = { path = "bevy_persistence_database/bevy_persistence_database", features = ["arango", "postgres"] }
bevy_persistence_database_derive = { path = "bevy_persistence_database/bevy_persistence_database_derive" }

Backends and features

Enable features on bevy_persistence_database:
- arango: builds the ArangoDB backend (arangors).
- postgres: builds the Postgres backend (tokio-postgres).
Provide an Arc at startup:
- Arango:
  - await ArangoDbConnection::ensure_database(url, user, pass, db_name)
  - let db = ArangoDbConnection::connect(url, user, pass, db_name).await?
- Postgres:
  - PostgresDbConnection::ensure_database(host, user, pass, db_name, Some(port)).await?
  - let db = PostgresDbConnection::connect(host, user, pass, db_name, Some(port)).await?

Quickstart

Persist-able types.

use bevy_persistence_database_derive::persist;

#[persist(component)]
#[derive(Clone)]
pub struct Health { pub value: i32 }

#[persist(component)]
pub struct Position { pub x: f32, pub y: f32 }

#[persist(resource)]
#[derive(Clone)]
pub struct GameSettings { pub difficulty: f32, pub map_name: String }

Add the plugin with a real database connection.

use bevy::prelude::*;
use bevy_persistence_database::{persistence_plugin::PersistencePlugins, ArangoDbConnection};
use std::sync::Arc;

fn main() {
    // Build a small runtime to create the DB connection up-front
    let rt = tokio::runtime::Runtime::new().unwrap();

    // Arango example (see tests/common/setup.rs for the same pattern)
    let url = "http://127.0.0.1:8529";
    let user = "root";
    let pass = "password";
    let db_name = "bevy_example";
    rt.block_on(ArangoDbConnection::ensure_database(url, user, pass, db_name)).unwrap();
    let db = rt.block_on(ArangoDbConnection::connect(url, user, pass, db_name)).unwrap();
    let db = Arc::new(db) as Arc<dyn bevy_persistence_database::DatabaseConnection>;

    App::new()
        .add_plugins(PersistencePlugins(db))
        .run();
}

Loading pattern

Use PersistentQuery as a SystemParam.
Add value filters via .where(...) (alias of .filter(...)).
Explicitly trigger the load with .ensure_loaded(); then use pass-throughs on world-only data.

use bevy::prelude::*;
use bevy_persistence_database::PersistentQuery;

fn sys(
    mut pq: PersistentQuery<(&Health, Option<&Position>), (With<Health>, Without<Creature>, Or<(With<PlayerName>,)>)>
) {
    let count = pq
        .where(Health::value().gt(100))
        .ensure_loaded()
        .iter()
        .count();
    info!("Loaded {} entities", count);
}

Pass-throughs are world-only After a load, PersistentQuery derefs to bevy::prelude::Query. Use standard accessors without new DB I/O:

fn pass_through(mut pq: PersistentQuery<&Health>) {
    let _ = pq.ensure_loaded();

    // single
    if let Ok((_e, h)) = pq.get_single() {
        info!("single: {}", h.value);
    }

    // get_many (array-of-entities)
    let [a, b] = [e1, e2];
    let Ok([(_, ha), (_, hb)]) = pq.get_many([a, b]) else { return; };

    // iter_combinations
    for [(_e1, h1), (_e2, h2)] in pq.iter_combinations() {
        info!("pair: {} {}", h1.value, h2.value);
    }
}

Key filtering

Single key:

use bevy_persistence_database::{PersistentQuery, Guid};

fn by_key(mut pq: PersistentQuery<&Health>) {
    let _ = pq.where(Guid::key_field().eq("my-key")).ensure_loaded();
}

Multiple keys via IN:

let _ = pq.where(Guid::key_field().in_(&["k1","k2","k3"])).ensure_loaded();

Optional Q semantics and presence via F

Option<&T> in Q fetches T only when present, without gating presence.
Presence is driven by type-level filters in F (With, Without, Or<(... )>), which gate backend queries.

Caching and force-refresh

Default CachePolicy is UseCache. Identical loads coalesce within a frame and reuse cached results across frames.
Use force_refresh to bypass cache and overwrite world state:

let _ = pq.force_refresh().ensure_loaded();

Resources

#[persist(resource)] resources are fetched alongside any query call; versions are tracked and updated on commits automatically.

Scheduling notes

Loads can run in Update or PostUpdate.
Deferred world mutations from loads are applied before PreCommit; schedule readers after PersistenceSystemSet::PreCommit to observe fresh data in the same frame.

bevy_persistence_database 0.1.0

bevy_persistence_database