Crate pgorm 

pgorm

A model-definition-first, AI-friendly PostgreSQL ORM for Rust.

Quick Start

use pgorm::prelude::*;

Two-level API

• Recommended: PgClient — monitoring + SQL checking + statement cache + policy
• Low-level: GenericClient / Sql — pluggable, minimal abstraction

Modules

• monitor — query monitoring, hooks, [InstrumentedClient]
• check — SQL schema checking, linting, SchemaRegistry
• prelude — convenient use pgorm::prelude::* for daily use
• qb — thin wrapper around query() for hand-written SQL

Stability: pgorm is pre-1.0. APIs may change between minor versions. MSRV: 1.88+

Re-exports

pub use types::Bound;

pub use types::Range;

pub use eager::BelongsToMap;

pub use eager::HasManyMap;

pub use eager::HasOneMap;

pub use eager::Loaded;

pub use changeset::ValidationCode;

pub use changeset::ValidationError;

pub use changeset::ValidationErrors;

pub use check::ColumnMeta;

pub use check::SchemaRegistry;

pub use check::TableMeta;

pub use check::TableSchema;

pub use tokio_postgres;

Modules

changeset

Changeset-style validation error types.

check

SQL schema checking and linting utilities.

eager

Eager loading (batch preloading for relations).

monitor

Query monitoring and hooks for SQL execution.

prelude

Convenient imports for typical pgorm usage.

qb

Minimal facade for running hand-written SQL.

types

PostgreSQL special types.

validate

Validation helpers used by derive-generated Input structs.

Macros

assert_models_db_valid

Assert that all models match the database schema, panic if not.

assert_models_valid

Check models and panic if any have schema issues.

check_models

Check multiple models against a schema registry and return results.

check_models_db

Check models against the actual database schema.

nested_transaction

Runs the given block inside a nested transaction (savepoint).

print_model_check

Print schema check results for multiple models.

print_models_db_check

Check models against database and print results.

savepoint

Runs the given block inside a savepoint within an existing transaction.

transaction

Runs the given block inside a database transaction.

Structs

Condition

A query condition primitive used by builders.

DeleteManyBuilder

Builder for bulk DELETE operations.

FromRowStream

Ident

A SQL identifier (column, table, or schema name).

Json

A wrapper type to allow arbitrary Serialize/Deserialize types to convert to Postgres JSON values.

Keyset1

Single-column keyset pagination builder.

Keyset2

Two-column keyset pagination builder (primary key + tie-breaker).

ModelCheckResult

Result of checking a model against the database schema.

OrderBy

ORDER BY clause builder.

Pagination

Pagination configuration for LIMIT/OFFSET.

PgClient

Unified Postgres client with monitoring and SQL checking.

PgClientConfig

Configuration for PgClient.

PoolClient

Wrapper for deadpool_postgres::Client.

Query

A SQL string with pre-numbered placeholders ($1, $2, ...) plus bound parameters.

RowStream

A stream of database rows.

Savepoint

A named savepoint within a transaction.

Sql

A parameter-safe dynamic SQL builder.

SqlPolicy

Policy for runtime SQL safety rules.

StatementCacheConfig

Prepared statement cache configuration (per-connection).

StmtCacheStats

Statement cache statistics.

UpdateManyBuilder

Builder for bulk UPDATE operations.

WithBuilder

Builder for CTE (WITH clause) queries.

WriteReport

Report returned by insert_graph_report / update_by_id_graph_report.

WriteStepReport

Statistics for a single step in a write graph.

Enums

CheckMode

Check mode configuration for CheckedClient.

Cursor

Cursor position for keyset pagination.

DangerousDmlPolicy

IdentPart

A part of a SQL identifier.

NullsOrder

NULLS ordering for ORDER BY.

Op

Query operator for building conditions.

OrderItem

A single ORDER BY item.

OrmError

Error types for database operations.

SelectWithoutLimitPolicy

SetExpr

A SET clause expression for bulk updates.

SortDir

Sort direction for ORDER BY.

WhereExpr

A WHERE clause expression tree supporting AND/OR/NOT/grouping.

Traits

FromRow

Trait for converting a database row into a Rust struct.

GenericClient

A trait that unifies database clients and transactions.

IntoIdent

Convert an input into an Ident.

ModelPk

Trait for models with a primary key.

PgType

Trait that maps Rust types to PostgreSQL type names for UNNEST casts.

RowExt

Extension trait for Row to provide typed access

StreamingClient

Streaming query support (RowStream).

TransactionExt

Extension trait adding savepoint support to transactions.

Functions

create_pool

Create a connection pool from a database URL.

create_pool_with_config

Create a connection pool with custom configuration

create_pool_with_manager_config

Create a connection pool with injected deadpool_postgres::ManagerConfig and PoolBuilder.

create_pool_with_tls

Create a connection pool using a custom TLS connector.

query

Build a SQL query from a pre-numbered SQL string ($1, $2, ...).

sql

Start building a SQL statement.

Type Aliases

OrmResult

Result type alias for pgorm operations

Derive Macros

FromRow

Derive FromRow trait for a struct.

InsertModel

Derive InsertModel helpers for inserting into a table.

Model

Derive Model metadata for a struct.

PgComposite

Derive PgComposite helpers to map a Rust struct to a PostgreSQL composite type.

PgEnum

Derive PgEnum helpers to map a Rust enum to a PostgreSQL ENUM type.

QueryParams

Derive QueryParams helpers for building dynamic queries from a params struct.

UpdateModel

Derive UpdateModel helpers for updating a table (patch-style).

ViewModel

Derive ViewModel metadata for a struct.