Skip to content

README.md

Latest commit

 

History

History
37 lines (28 loc) · 2.19 KB

README.md

File metadata and controls

37 lines (28 loc) · 2.19 KB

montrs-orm

A trait-driven, async-first ORM layer for MontRS.

Target Audiences: Application Developers, Framework Contributors, Agents.

1. What this package is

montrs-orm provides a unified, SQL-centric interface for interacting with different database backends (SQLite, PostgreSQL). It abstracts driver-specific details while maintaining high-performance async access.

2. What problems it solves

  • Backend Lock-in: Allows switching between SQLite (local dev) and PostgreSQL (production) with minimal code changes.
  • Boilerplate: Automates row-to-struct mapping and connection pool management.
  • Type Safety: Ensures that database queries and results are verified at compile-time or through structured traits.

3. What it intentionally does NOT do

  • Query DSL: It does not force a complex, non-SQL DSL (like Diesel). It prefers clean SQL or simple builder patterns.
  • Migration Management: It does not handle complex schema migrations (use external tools like sqlx-cli or sea-orm-cli as recommended in our docs).
  • Auto-Caching: It does not implement implicit query caching.

4. How it fits into the MontRS system

It provides the persistence layer for Plates. It implements the traits defined in montrs-core for data access.

5. When a user should reach for this package

  • When building a feature that requires persistent data storage.
  • When implementing a custom database backend or driver.
  • When defining data models that need to be persisted in a relational database.

6. Deeper Documentation

7. Notes for Agents

  • SQL Preference: Prefer writing raw SQL queries using the provided backend execute methods over complex abstractions.
  • Schema Discovery: Read the struct definitions that implement FromRow to understand the database schema.
  • Error Mapping: This package implements AgentError for DbError, providing specific codes for constraint violations, connection failures, etc.
  • Constraints: Assume all database operations are async and must be awaited within an Action or Loader.