Crate dibs

Expand description

Postgres toolkit for Rust, powered by facet reflection.

This crate provides:

Database migrations as Rust functions
Schema introspection via facet reflection
Query building (planned)

§Naming Convention

Table names use singular form (e.g., user, post, comment).

This convention treats each table as a definition of what a single record represents, rather than a container of multiple records. It reads more naturally in code: User::find(id) returns “a user”, and foreign keys like author_id reference “the user table”.

Junction tables for many-to-many relationships use singular forms joined by underscore: post_tag, post_like, user_follow.

§Migrations

Migrations are registered using the #[dibs::migration] attribute. The version is automatically derived from the filename:

// In file: src/migrations/m_2026_01_17_120000_create_user.rs
#[dibs::migration]
async fn migrate(ctx: &mut MigrationContext) -> MigrationResult<()> {
    ctx.execute("CREATE TABLE user (id SERIAL PRIMARY KEY, name TEXT NOT NULL)").await?;
    Ok(())
}

Use MigrationResult instead of Result to enable #[track_caller] - when an error occurs, the exact source location (file:line:column) is captured.

Run migrations with MigrationRunner:

let runner = MigrationRunner::new(&client);
runner.migrate().await?;

Re-exports§

pub use backoffice::SquelServiceImpl;
pub use diff::Change;
pub use diff::SchemaDiff;
pub use diff::TableDiff;
pub use meta::create_meta_tables_sql;
pub use meta::record_migration_sql;
pub use meta::sync_tables_sql;
pub use pool::ConnectionProvider;
pub use service::DibsServiceImpl;
pub use service::run_service;
pub use inventory;

Modules§

backoffice: Squel service implementation - the data plane.
diff: Schema diffing - compare Rust-defined schema against database schema.
introspect: Database introspection - read schema from a live Postgres database.
meta: Meta tables for schema provenance tracking.
pool: Connection pooling abstractions.
query: Query builder for dibs.
schema: Schema definition and introspection.
service: Dibs service implementation.
solver: Migration solver - orders and validates schema changes.

Macros§

__facet_invoke: Plugin chain entry point.

Structs§

AppliedMigration: A migration that was already applied.
ChangeInfo: A single schema change.
Check: CHECK constraint definition.
CheckConstraint: A table CHECK constraint.
Column: A database column definition.
ColumnInfo: Column information.
CompositeIndex: Composite index definition for multi-column indices.
CompositeUnique: Composite unique constraint for multi-column uniqueness.
CreateRequest: Request to create a new row.
DeleteRequest: Request to delete a row.
DibsServiceClient: Client for the DibsService service.
DibsServiceDispatcher: Dispatcher for this service.
DiffRequest: Request to diff schema against a database.
DiffResult: Full diff result.
Filter: A single filter condition.
ForeignKey: A foreign key constraint.
ForeignKeyInfo: Foreign key information.
GeneratedCode: Generated Rust code for a query file.
GetRequest: Request to get a single row by primary key.
Index: A database index.
IndexColumn: A column in an index with optional sort order and nulls ordering.
IndexColumnInfo: A column in an index with optional sort order and nulls ordering.
IndexInfo: Index information.
Jsonb: A wrapper type for PostgreSQL JSONB columns.
ListRequest: Request to list rows from a table.
ListResponse: Response from listing rows.
MigrateRequest: Request to run migrations.
MigrateResult: Result of running migrations.
Migration: A registered migration.
MigrationContext: Context passed to migration functions.
MigrationError: Error type for migrations that captures caller location via #[track_caller].
MigrationInfo: Migration status.
MigrationLog: Log message streamed during migration.
MigrationRunner: Runs migrations against a database.
MigrationStatus: Status of a single migration.
MigrationStatusRequest: Request to get migration status.
QueryFile: A query file - top level is a map of declaration names to declarations. Uses Meta<String> as keys to capture doc comments from the styx file.
RanMigration: A migration that was just run.
Row: A row of data as field name → value pairs.
RowField: A single field in a row.
Schema: A complete database schema.
SchemaInfo: The full schema (list of tables).
Sort: A sort clause.
SourceLocation: Source location of a schema element.
SqlError: SQL error with context for rich error display.
SqlErrorContext: Rich SQL error with context for display.
SquelServiceClient: Client for the SquelService service.
SquelServiceDispatcher: Dispatcher for this service.
Table: A database table definition.
TableDef: A registered table definition.
TableDiffInfo: Diff result for a single table.
TableInfo: Schema information for a table.
TracedConn: A wrapper around a database connection that logs all queries via tracing.
TracedObject: A traced connection that owns the underlying connection.
TracedPool: A traced connection pool.
TriggerCheck: Trigger-enforced check definition.
TriggerCheckConstraint: A trigger-enforced invariant check (BEFORE INSERT OR UPDATE).
UpdateRequest: Request to update a row.

Enums§

Attr: Dibs schema attribute types.
ChangeKind: Kind of schema change.
DibsError: Error from the dibs service.
Error
FilterOp: Filter operator for backoffice queries.
LogLevel: Log level.
NullsOrder: Nulls ordering for index columns.
PgType: Postgres column types.
SortDir: Sort direction.
SortOrder: Sort order for index columns.
Value: A runtime value for backoffice queries.

Traits§

Connection: Trait for database connections that can execute queries.
ConnectionExt: Extension trait to get a traced wrapper from a connection.
DibsService: The dibs service trait.
SquelService: The Squel service trait - the data plane.

Functions§

build_queries: Generate query code from a .styx file.
check_constraint_name: Generate a deterministic CHECK constraint name for a table and expression.
dibs_service_service_descriptor
generate_rust_code: Generate Rust code for a query file.
index_name: Generate a standard index name for a table and columns.
parse_query_file: Parse a styx source string into a QueryFile.
quote_ident: Quote a PostgreSQL identifier.
squel_service_service_descriptor
trigger_check_function_name: Derive the trigger function name for a trigger-enforced check.
trigger_check_name: Generate a deterministic trigger name for a trigger-enforced check.
unique_index_name: Generate a standard unique index name for a table and columns.

Type Aliases§

MigrationFn: Type alias for migration functions.
MigrationResult: Result type for migration functions, captures caller location on error.
Result: Result type for dibs operations.

Attribute Macros§

migration: Register a migration function.

Crate dibs

Crate dibs Copy item path

§Naming Convention

§Migrations

Re-exports§

Modules§

Macros§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Crate dibs