Full documentation is available in the docs/ directory:
- Quickstart — install and first query in 5 minutes
- Defining models — fields, types, composite keys
- Basic queries — CRUD, filtering, serialization
- Relationships — HasMany, BelongsToMany, SelfReferential
- Query builder reference — all clause methods
- Transactions and sessions — identity map, dirty tracking
- Migrations — snapshot-based schema diffing
- Performance — N+1 queries and eager loading
- API reference — complete Python API
- FAQ
- Contributing
Bridge uses the Performance Bridge principle by splitting the ORM into two distinct parts to maximize both Speed and Developer Ergonomics:
- Expression Layer (Python): A thin, expressive API for intuitive queries and models. Handles high-level logic, task-local identity mapping, dirty tracking, hooks, and eager loading orchestration.
- Execution Engine (Rust): An ultra-fast core built on
sqlxandtokio. Handles connection pooling, SQL construction, row hydration, circuit breaking, and cross-language telemetry.
Instead of slow HTTP or JSON-over-pipe communication, Bridge utilizes Native Memory Bindings (FFI via PyO3), allowing data to flow between Python and Rust with near-zero latency.
frombridgeimportBaseModel, HasMany, BelongsToMany, transaction, connectclassUser(BaseModel):
table="users"_fields= ["id", "username", "email"]
id: strusername: stremail: strasyncdefmain():
pool=awaitconnect("postgres://localhost/mydb")
asyncwithtransaction() astx:
user=awaitUser.create(tx, username="alice", email="alice@example.com")
found=awaitUser.find_one(tx, username="alice")
print(found.to_dict())| Feature | Description |
|---|---|
| Declarative Models | Define models with Python type hints; auto-registration with Rust metadata |
| Fluent Query Builder | .filter(), .limit(), .select(), .prefetch_related(), .first() |
| CRUD Operations | Single and bulk insert, update, delete with automatic type coercion |
| Unit of Work / Session | Identity map, dirty tracking with snapshot-based diff, automatic flush on commit |
| Eager Loading | Batch SELECT IN for HasMany, BelongsToMany, and SelfReferential relations |
| Lazy Loading | Per-relation lazy proxies that resolve on first access |
| Lazy Streaming | fetch_lazy() returns an async iterator for large result sets |
| Arrow IPC | fetch_arrow() uses Apache Arrow for zero-copy data transfer (feature data-science) |
| Schema Migration Engine | Snapshot-based diffing generates UP/DOWN SQL for evolving schemas |
| CLI Tools | bridge reflect, bridge makemigrations, bridge migrate |
| Schema Introspection | Reflect existing database tables into Python model classes |
| Admin Panel | Auto-generated FastAPI admin with JWT auth, CSRF, rate limiting (optional) |
| REST API Generator | Auto-generate FastAPI routers from model classes |
| Lifecycle Hooks | before_create, after_create, before_delete, after_delete decorators |
| Optimistic Concurrency | Version-guarded updates via _bridge_row_version column |
| OpenTelemetry | Distributed tracing with OTLP export, slow query logging |
| Pytest Integration | db_session fixture with transactional rollback |
| factory_boy | BridgeFactory base class for async test data creation |
Bridge provides native and protocol-compatible support for a wide range of modern and enterprise databases:
| Database | Compatibility | Specific Optimizations |
|---|---|---|
| PostgreSQL | Native | Full async support via sqlx. |
| SQLite | Native | High-performance local and embedded storage. |
| MySQL | Native | Standard industry support with backtick quoting. |
| MariaDB | Native | Specialized MariaDB dialect optimizations. |
| Oracle | Custom | Custom :1 placeholders & FETCH NEXT pagination. |
| MS SQL Server | Native | Support for [] quoting and @p1 placeholders. |
| CockroachDB | Postgres-Protocol | Optimized for distributed UUIDs and SERIAL8. |
| PlanetScale | MySQL-Protocol | Optimized for Vitess-based serverless pooling. |
| Neon | Postgres-Protocol | Native support for serverless Postgres architecture. |
| YugabyteDB | Postgres-Protocol | Built for distributed SQL workloads. |
| Cloudflare D1 | SQLite-Protocol | Optimized for serverless SQLite environments. |
| Dolt | MySQL-Protocol | Native support for versioned SQL databases. |
When I started designing Bridge, my absolute priority was Security. I've tried my best to build a secure wall around your data.
Here is how Bridge protection works around your data:
- Forbidden String Interpolation: String interpolation in queries is strictly forbidden. If it's not parameterized, it doesn't run. Period.
- Rust-Level Guardrails: Before any dynamic SQL identifier reaches the database, the Rust Engine forces it through a strict regular expression validator. No sneak attacks.
- Panic-Proof FFI: The language boundary is wrapped in
catch_unwindblocks. If something goes wrong in the Rust core, your Python app won't crash; it gets a clean exception. - Strict Type Coercion: We don't guess types. Every piece of data crossing the bridge is validated against your model's metadata. No silent data corruption.
- The Circuit Breaker: If your database starts failing or slowing down, our internal circuit breaker trips. This protects your application from cascading failures and keeps your threads alive.
Bridge uses Cargo feature flags to keep the core lightweight:
| Feature | Description |
|---|---|
default | No default features — build only what you need |
allow-raw-sql | Enables execute_raw() and Raw SQL expressions |
data-science | Enables Arrow IPC via fetch_arrow() |
java-interop | Enables JNI bindings for Java interop |
bridge reflect --url <DATABASE_URL> --table <TABLE_NAME> # Introspect table → Python model
bridge makemigrations --dialect <sqlite|postgres> # Generate migration SQL from models
bridge migrate --url <DATABASE_URL> # Apply pending migrations
Collaborator Must Follow This Rules:
- Self-Documenting Code: Meaningful identifiers are a must. If something doesn't make sense to you, rename it so its logic inspires clarity.
- Single Responsibility Principle: Each method must have only one responsibility and be of equal simplicity.
- D.R.Y. Principle: Do not duplicate common functionality; instead, use a single reference point when using common functionality.
- Meaningful Identifier: Write your identifiers as if they were spoken words. Use common sense when naming them; avoid unnecessary jargon; choose names with clarity as the focus.
- Avoid Magic Numbers/Strings: Use named constants for hard-coded values so their meaning is clear.
- Explicit Handling of Errors: Fix the actual problem first (fix the code), then use typed return values or exception handling to guarantee errors are visible and cannot go unaddressed.
- Consistent Formatting: Use automated tools for visual consistency across the entire codebase.
- Provide Explanation to your Intent: Comment on your code to explain why you made those coding decisions, not just what the code is doing.
- FFI Boundary Safety: Any new feature crossing the Python/Rust boundary MUST be wrapped in the
ffi_guard!macro to ensure the application remains crash-safe. - Dialect Agnosticism: Never write SQL specific to one database in the core engine. Always use the
Dialecttrait to ensure changes work across all supported databases. - Telemetry Integrity: Every new database operation must include tracing spans. If we can't measure it, we shouldn't merge it.
- Eager Loading: Relations support both high-speed Lazy Loading (per-relation) and batch
prefetch_relatedviaQueryBuilder.with_relation()/.prefetch_related(). - SQL Complexity: Advanced operations like CTEs and Window Functions require the
execute_raw()fallback (requiresallow-raw-sqlfeature). - Identity Isolation: The Identity Map is strictly scoped per
asyncio.Taskto ensure memory safety. - ALTER COLUMN Nullability: Changing column nullability via migration requires dialect-specific SQL syntax (SET NOT NULL / DROP NOT NULL).
- Composite Foreign Keys: Relations assume single-column foreign keys; composite FKs are not yet supported.