Lifeguard is a coroutine-native PostgreSQL ORM and data access platform built for Rust's may runtime. It aims for SeaORM-like ergonomics without async/Tokio: stackful coroutines and may_postgres as the database client.
The problem: Existing Rust ORMs (SeaORM, Diesel, SQLx) target async/Tokio. The may coroutine runtime uses stackful coroutines, not async futures—architectures do not bridge without significant cost. For the narrative on that mismatch and the pain of forcing async ORMs onto a coroutine stack, see LIFEGUARD_BLOG_POST.md.
The approach: A full ORM on **may_postgres** (coroutine-native PostgreSQL). No async runtime on the database path. Pure coroutine I/O.
Who it is for: Teams on **may** (for example BRRTRouter) who want SeaORM-like productivity, typed models and queries, a production connection pool (primary/replica, WAL-aware routing, optional read preference), OTel-compatible metrics/tracing, and a cache-coherence story (LifeReflector + Redis) aimed at latency-sensitive tiers.
Shipped vs aspirational: Treat COMPARISON.md (repository truth), cargo doc, and examples/ as source of truth; some diagrams and marketing copy still describe target behavior (for example fully automatic transparent Redis on every read path). Product vision, feature lists, and the LifeReflector narrative: VISION.md. Parity tables and competitive framing: COMPARISON.md and the SeaORM mapping.
High-level data flow: your app and ORM go through **LifeguardPool** to PostgreSQL (writes and strong reads on the primary; scaled reads may use replicas when routing allows). Redis is optional cache-aside; **[lifeguard-reflector](./lifeguard-reflector/)** refreshes warm keys asynchronously after commits (not on the SELECT hot path).
flowchart LR
subgraph Req["Request path"]
A[App / LifeModel] --> P[LifeguardPool]
P --> PR[(Primary)]
P --> RP[(Replicas)]
end
subgraph Opt["Optional + async"]
A -.-> R[(Redis)]
PR -.-> LR[LifeReflector]
LR -.-> R
end
style PR fill:#c0c0c0
style RP fill:#d8d8d8
style R fill:#ffcccb
style LR fill:#add8e6
style P fill:#90ee90
Full diagrams (numbered call order, multi-service deployment, pool slots, LifeReflector sequence): ARCHITECTURE.md.
[dependencies]
lifeguard = { git = "https://github.com/microscaler/lifeguard" }
lifeguard-derive = { git = "https://github.com/microscaler/lifeguard", package = "lifeguard-derive" }Enable optional features as needed, for example metrics, tracing, or graphql (see root Cargo.toml).
- Direct client: connect with
lifeguard::connectand wrap the client inMayPostgresExecutor. - Pooled: build a
[LifeguardPool](./src/pool/pooled.rs)(new,new_with_settings, orfrom_database_config) and use[PooledLifeExecutor](./src/pool/pooled.rs)forLifeExecutortraffic (seecargo doconlifeguard::pool). - Define entities with
#[derive(LifeModel, LifeRecord)]and#[table_name = "..."](see[lifeguard-derive/tests/test_minimal.rs](./lifeguard-derive/tests/test_minimal.rs)). - Build queries with
SelectQueryand related APIs; see[examples/query_builder_example.rs](./examples/query_builder_example.rs).
Pooling behavior and tunables evolve with PRD_CONNECTION_POOLING.md; prefer rustdoc for the exact public API at your revision.
- DEVELOPMENT.md — Clippy (CI parity), pre-commit,
justrecipes. - docs/TEST_INFRASTRUCTURE.md — Postgres/Redis for integration tests and CI.
Lifeguard is OpenTelemetry-compatible: optional **tracing** spans/events and optional Prometheus metrics (metrics / tracing features) fit standard OTLP pipelines—use them with OpenTelemetry-native backends (Grafana, Jaeger, Tempo, collectors) or Datadog via OTLP intake or the Datadog Agent’s OpenTelemetry support. Lifeguard does not install global OTel or tracing subscribers for you; the host app owns one provider and subscriber (see OBSERVABILITY.md and docs/OBSERVABILITY_APP_INTEGRATION.md).
Details: Prometheus series (pool, queries, replica lag), tracing scopes, LifeReflector metrics, and Kind/Tilt dashboard refresh — OBSERVABILITY.md (overview) and docs/OBSERVABILITY.md (full metric tables, feature flags, kubectl apply).
- Library tests:
cargo test -p lifeguard, workspace members (lifeguard-derive,lifeguard-migrate, etc.), and (when configured)cargo nextestper DEVELOPMENT.md / justfile. - Integration database:
lifeguard::test_helpers::TestDatabaseand env vars such asTEST_DATABASE_URL— see docs/TEST_INFRASTRUCTURE.md.
There is no lifeguard::testkit / test_pool! macro in this repository; use test_helpers and the integration-test binaries under tests/.
| Topic | Document |
|---|---|
| Repository truth, competitive matrix, ecosystem, performance | COMPARISON.md |
| Roadmap (high-level areas) | ROADMAP.md |
| Product vision & long-form “what we’re building” | VISION.md |
Blog: async ORMs vs may, and why Lifeguard exists |
LIFEGUARD_BLOG_POST.md |
| Architecture (diagrams, flows) | ARCHITECTURE.md |
| Observability overview (OTel-compatible, Datadog via OTLP) | OBSERVABILITY.md |
| Host-owned OTel/tracing wiring | docs/OBSERVABILITY_APP_INTEGRATION.md |
Metrics tables, Kind/Tilt kubectl apply |
docs/OBSERVABILITY.md |
| Connection pool operations & tuning | docs/POOLING_OPERATIONS.md · docs/planning/DESIGN_CONNECTION_POOLING.md |
| SeaORM ↔ Lifeguard mapping (authoritative parity) | docs/planning/lifeguard-derive/SEAORM_LIFEGUARD_MAPPING.md |
PostgreSQL UUID columns → Rust types (uuid::Uuid, not String) |
docs/UUID_AND_POSTGRES_TYPES.md |
| Developer workflow, Clippy / pre-commit, G6 doc alignment | DEVELOPMENT.md |
**find_related + related-side scope (compile-only example)** |
examples/find_related_scope_example.rs |
| Tests & CI Postgres/Redis | docs/TEST_INFRASTRUCTURE.md |
| Epic notes & story tree | docs/EPICS/ · docs/planning/epics-stories/ |
| Planning index | docs/planning/README.md |
Lifeguard is under active development. We welcome:
- 📝 Documentation improvements
- 🐛 Bug reports
- 💡 Feature suggestions
- 🧪 Testing and feedback
See EPICS for current development priorities.
Licensed under MIT OR Apache-2.0 at your option ([Cargo.toml](./Cargo.toml)). The [LICENSE](./LICENSE) file in this repository contains the Apache-2.0 text.