diesel-rs/diesel
github.com/diesel-rs/diesel ↗ · 2273 files · 8.4 MB
A safe, extensible ORM and Query Builder for Rust API Documentation: latest release – main branch Homepage Diesel gets rid of the boilerplate for database interaction and eliminates runtime errors without sacrificing performance.
Overview
Diesel is a Rust ORM and typed SQL query builder for PostgreSQL, SQLite, MySQL, and MariaDB, accompanied by a database-management CLI and migration libraries. It serves application developers who want schema-aware queries, model conversion, associations, and explicit database execution through mutable connections. This pinned revision also includes runtime schemas, view nullability inference, Rust migration callbacks, and SQLite examples targeting WebAssembly and embedded hardware.
System map
The workspace separates typed query execution, code generation, database tooling, and migration management into cooperating crates. Applications link Diesel directly, while the diesel executable supplies operational commands. Backend features select native drivers and dialect implementations, with additional SQLite platform support. Distribution and developer verification are implemented through cargo-dist, xtask, and GitHub Actions.
- The root workspace includes diesel, diesel_cli, diesel_derives, diesel_migrations, diesel_dynamic_schema, diesel_infer_query, parser crates, examples, and xtask; its shared baseline is Rust 1.88.0 and edition 2024.
- The actual diesel and diesel_cli package versions are 2.3.13; the CLI manifest declares the diesel binary at src/main.rs.
- diesel/src/lib.rs exposes associations, expressions, query_builder, query_dsl, serialization, rows, migrations, and feature-gated backend modules; query construction and driver execution are separate module boundaries.
- diesel_derives is a procedural-macro crate depending on shared attribute/table parsers and dsl_auto_type; diesel_attribute_parser explicitly identifies itself as internal.
- Backend features connect PostgreSQL through pq-sys, MySQL/MariaDB through mysqlclient-sys, and SQLite through target-specific libsqlite3-sys or sqlite-wasm-rs dependencies.
- PgConnection owns a statement cache, PostgreSQL metadata cache, raw connection, transaction state, and instrumentation; persisted migration versions belong to __diesel_schema_migrations in the database.
- cargo xtask is a Cargo alias for the xtask package, whose commands include run-tests, clippy, tidy, and semver-checks; CONTRIBUTING.md directs contributors to run-tests and tidy.
- cargo-dist targets five macOS/Linux/Windows architectures with shell and PowerShell installers, bundled CLI dependencies, SBOMs, and attestations; release publication is gated by the workflow's publishing output.
Feature catalog
Diesel's primary interface is a Rust API for composing and executing queries against typed schemas. The CLI adds database setup, migration lifecycle commands, schema generation, and shell completions. Supporting libraries offer runtime schema names, custom type conversion, and several migration sources. Examples demonstrate associations, authenticated blog operations, and embedded SQLite.
- Query composition includes filtering, selection, ordering, limits, and association-based subqueries; construction remains separate from load execution.
- The DSL exports insert_into, update, delete, insert_or_ignore_into, replace_into, select, and sql_query; execute returns affected-row counts, while get_result returns the first row or Error::NotFound.
- Associations support belonging_to and grouped_by, while joins support related and nullable records; the PostgreSQL relations example demonstrates one-to-many and many-to-many traversal.
- CLI commands are migration, setup, database/db, completions, and print-schema; migration dispatch implements run, revert, redo, list, pending, and generate.
- Schema configuration supports documentation, table filters, column order, schema namespaces, patches, imported/custom types, Rust enums, views, and experimental view-nullability inference.
- Migration generation can compare a Rust schema with the live database to produce up/down SQL; migration libraries additionally support filesystem SQL, embedded SQL, and Rust callbacks or TypedMigration implementations.
- diesel_dynamic_schema constructs tables and columns at runtime with explicit selections; custom Rust values can implement ToSql and FromSql, as illustrated by the Language enum.
- The advanced blog example offers paginated posts/comments, registration, post creation/editing/publishing, and comment creation/editing; the embedded SQLite example repeatedly queries both static and dynamic schemas.
Data flow
Library input becomes a typed query representation before a backend serializes binds and executes SQL. Connections own runtime caches and transaction state, while row conversion produces application values. CLI input combines arguments, environment variables, and TOML configuration before accessing databases or filesystem outputs. Migration state and generated schema files are separate persistence boundaries.
- QueryFragment::walk_ast defines AST-node behavior; to_sql performs a SQL-generation pass, while bind values are serialized separately from SQL placeholders.
- LoadQuery requires backend-compatible result types, converts the source through as_query, obtains a connection cursor, and maps each row through U::build_from_row with DeserializationError conversion.
- PostgreSQL collect_binds produces raw byte values and type metadata; with_prepared_query passes metadata to the statement cache and values separately to execution.
- The statement cache checks query cache safety, reuses occupied entries, registers newly prepared statements when capacity permits, and prepares uncached statements for unsafe or capacity-limited cases.
- CLI database URLs prefer explicit options over DATABASE_URL; config paths prefer arguments over DIESEL_CONFIG_FILE, and migration paths prefer arguments, MIGRATION_DIRECTORY, configuration, then ancestor discovery.
- SchemaResolverImpl owns catalog-result caching and a recursive resolution chain; requested tables load catalog metadata, views invoke load_view_data, and cycles return CyclicViewDefinition.
- Generated schema data passes through relation/custom-type formatting, rustfmt, and optional diffy patch application; print-schema writes to its output writer, while regeneration writes configured files or compares them in locked mode.
- SQL migration files are read into strings and passed to batch_execute; successful application inserts a version record, successful reversal deletes it, and applied versions are read in descending order.
Behavior traces
The inspected flows cover CLI startup, database setup, migration application, schema printing, query execution, and example operations. Each trace follows named functions across their implementation boundaries. Migration application reaches both SQL execution and version bookkeeping before optional schema regeneration. PostgreSQL query tracing distinguishes cached named statements from uncached parameterized execution.
- Startup: main calls inner_main, which initializes DIESEL_LOG tracing, invokes dotenvy::dotenv, tolerates a missing dotenv file, parses Cli, and dispatches; returned errors are printed before exit code 1.
- Setup: run_setup_command calls create_migrations_dir and create_config_file, then setup_database resolves the URL, creates the database if needed, optionally creates default migrations, and invokes schema-table setup/migration execution.
- Migration run: run_migration_command calls conn_and_migration_dir, which establishes InferConnection and validates FileBasedMigrations; run_migrations_with_output delegates to HarnessWithOutput::run_pending_migrations, then regenerates schema unless --no-schema.
- Migration persistence: run_pending_migrations calls pending_migrations, removes already applied versions and sorts remaining versions ascending, then run_migration executes SQL and inserts bookkeeping inside a transaction when metadata permits.
- Print schema: run_infer_schema establishes a connection, reads/overrides configuration, computes multi-schema context, and calls run_print_schema; output_schema discovers relations and foreign keys, resolves metadata, formats/patches Rust, then writes stdout.
- PostgreSQL load: RunQueryDsl::load calls internal_load and collects results; internal_load calls connection.load, which uses with_prepared_query, inner_load, Statement::execute, and the selected loading mode's cursor before row deserialization.
- PostgreSQL execution branch: Statement::execute builds parameter pointers/lengths, rejects counts or sizes exceeding i32, sends named statements through send_query_prepared or unnamed SQL through send_query_params, optionally enables row-by-row mode, and retrieves a result.
- Blog create-post: run_cli establishes PgConnection, current_user delegates to current_user_from_env/find_user and Argon2 verification, editor::edit_string round-trips a temporary file through an external editor, then insert_into returns the post ID.
Testing signals
Tests and CI were inspected, not executed; no passing result or measured coverage is asserted. The repository combines Rust runtime tests, compile-failure diagnostics, procedural-macro snapshots, CLI subprocess tests, and fuzzing workflows. The inspected tests verify concrete database and generated-code behavior, with backend-specific conditions. This inventory is bounded and does not establish exhaustive coverage or whole-repository test gaps.
- diesel_tests registers integration modules for CRUD, associations, joins, raw SQL, transactions, migrations, instrumentation, types, views, and window functions, with some modules gated by backend features.
- Transaction tests inspect cross-connection visibility and rollback on returned errors; the visibility test explicitly excludes SQLite because it requires a file-backed database, and the rollback-error test is SQLite-specific.
- Despite its trybuild.rs filename, the compile-failure harness uses ui_test against tests/fail, normalizes diagnostic paths/text, and enables output blessing whenever BLESS exists; an inspected fixture rejects integer/string comparisons.
- Procedural-macro tests expand tokens, parse the result with syn, apply FixupVisitor, format through prettyplease, and assert insta snapshots; these assertions check generated text rather than database execution.
- CLI tests register database and migration command suites; migration_run_runs_pending_migrations checks command success, emitted migration output, and actual table creation.
- Schema tests compare CLI/config-generated output with insta snapshots and conditionally compile it in a temporary Cargo project; check_compile=false deliberately skips that compilation assertion for selected cases.
- CI defines a four-backend, five-platform stable matrix plus Linux beta/nightly entries, invokes cargo xtask run-tests, skips doctests/example-schema checks outside Linux, and uploads coverage outside merge_group events.
- Fuzz CI runs harness tests on PRs/pushes, but cargo-fuzz target execution is workflow_dispatch-only; separate ClusterFuzzLite PR jobs specify address sanitization and 600 seconds, while audit CI runs cargo deny check.
Risk map
These findings describe source-level trust boundaries and review hotspots, not runtime-confirmed vulnerabilities. Database operations can mutate remote databases or local files, and raw SQL reduces compile-time validation. Migration commits and schema-file verification occur at different stages. The advanced blog example contains security-relevant teaching shortcuts and an update target that warrants focused review.
- Source observation: EditComment loads a comment scoped to the current user, but executes diesel::update(comments) without a filter or identified-record target; the update construction does not preserve the preceding ownership selection.
- Source observation: blog registration hashes passwords with Argon2 using a constant salt; the implementation explicitly warns against this pattern in real applications.
- Operational boundary: database reset calls drop before setup; server backends execute DROP DATABASE, while SQLite drop removes an existing path supplied as database_url.
- Source observation: --locked-schema validation runs after migrations; a schema mismatch returns SchemaWouldChange, and the inspected dispatch provides no enclosing rollback around migration execution and file comparison.
- Migration metadata read/parse errors are discarded by unwrap_or_default; transaction-disabled migrations execute SQL and insert bookkeeping without the harness transaction wrapper.
- Raw SqlQuery binds cannot validate SQL placeholder types or parameter counts, and dynamic schemas cannot verify runtime table/column existence or declared types; these are documented reductions in static guarantees.
- Native PostgreSQL execution crosses unsafe libpq boundaries for connection pointers and parameter arrays; Statement::execute includes explicit i32 conversion checks, so preserving ownership and bounds behavior is essential when editing this code.
- External trust boundaries include PATH-resolved rustfmt, VISUAL/EDITOR-selected subprocesses, temporary editor files, and configured schema/patch paths; relative paths are joined to the config directory without a repository-containment check in the inspected code.
Extension points
Extensions primarily enter through Rust traits, procedural macros, configuration fields, and explicit CLI dispatch. Backend support separates dialect metadata from connection implementation. Applications can add custom value conversion, query fragments, instrumentation, and migration sources. Internal extension interfaces sometimes require an explicit feature acknowledging compatibility risk.
- Custom Backend implementations supply QueryBuilder, RawValue, BindCollector, SqlDialect, TypeMetadata, and SQL-type mappings; access requires the third-party-backend opt-in feature.
- Custom connections implement Connection with backend and transaction-manager ownership; the documentation also calls for backend-specific FromSql/ToSql conversions and gates implementations through ConnectionSealed.
- New query AST nodes implement QueryFragment::walk_ast, which supplies SQL-generation and other AST-pass behavior; execution/loading requires appropriate QueryFragment and QueryId implementations.
- Custom SQL value types implement ToSql and FromSql and derive expression/row support; the Language example serializes enum variants as PostgreSQL bytes and rejects unknown variants during decoding.
- Instrumentation extensions implement on_connection_event or use a closure, can be installed per connection, and can register a global constructor for future connections when std is enabled.
- Migration extensions implement Migration, MigrationMetadata, and MigrationSource; RustMigrationSource additionally registers callbacks, functions, RustMigration values, or custom TypedMigration implementations.
- CLI additions enter DieselCliCommand or MigrationCommand and their dispatch matches; schema customization enters PrintSchema configuration and the Config::read/update path.
- SchemaResolver is exported for SQL/view inference, and SchemaResolverImpl adapts CLI catalog metadata to it; table_proc routes table macro expansion into query_source_macro, while view declarations use the corresponding generated schema model.
Contributor handoff
Use the pinned manifests and affected crate implementation as the starting context, because the supplied inventory contains simplified version and backend information. Tests and CI were inspected, not executed, and this brief covers a bounded set of source paths. Future implementation work should preserve backend gates and use dedicated test databases before authorizing execution. Public API changes, generated diagnostics, schema snapshots, and embedded migration rebuilds require special attention.
- Read Cargo.toml and the affected crate manifest first: Rust 1.88.0/edition 2024, Diesel 2.3.13, four backend features, and target-specific SQLite dependencies are concrete constraints in this revision.
- For query-runtime changes, follow RunQueryDsl::load, LoadQuery::internal_load, backend LoadConnection, statement preparation, and row decoding before choosing an edit boundary.
- For CLI/schema work, read cli.rs, main.rs, config.rs, and print_schema.rs together; configuration overrides, relative paths, multi-schema context, patches, and locked-file handling all affect observable output.
- The inspected test sources and workflow declarations describe intended checks, not execution results: review CLI schema snapshots/compilation, migration assertions, compile-failure diagnostics, and CI configuration before planning validation.
- In authorized implementation work, start with the affected backend/test and use cargo xtask run-tests for broader checks; xtask resolves backend-specific database variables, runs migrations first, and invokes nextest with coordinated crate features.
- Preserve compile-error and snapshot expectations deliberately: BLESS presence rewrites ui_test outputs, while CONTRIBUTING.md calls for reviewing insta changes; tidy and semver-checks are existing tooling entrypoints.
- Embedded migrations have a documented rebuild trap: changes only to migration files may not rerun the procedural macro, and consuming applications should use build.rs rerun-if-changed declarations.
- Contribution conventions require minimal, reviewed, verified changes and AI-use disclosure; the guide reserves mentoring/good-first-issue work from AI use and asks authors to write their own PR descriptions.
Languages
| Language | Files | Share of source |
|---|---|---|
| Rust | 898 | 61% |
| SQL | 446 | 30% |
| TOML | 135 | 9% |
| Markdown | 23 | docs/config |
| YAML | 20 | docs/config |
| HTML | 1 | docs/config |
| JavaScript | 1 | 0% |
| Python | 1 | 0% |
Start reading here
Probable source entrypoint: Cargo.toml — inferred from the directory tree and manifest, not the upstream docs.
Source roots
diesel/ (308 files)
Repository structure
| Top-level path | Files |
|---|---|
diesel_cli/ | 782 |
diesel_compile_tests/ | 378 |
diesel/ | 308 |
examples/ | 237 |
diesel_derives/ | 141 |
migrations/ | 132 |
diesel_tests/ | 67 |
fuzz/ | 47 |
Docs found: CONTRIBUTING.mdREADME.md
Package
Cargo.toml — , 0 declared dependencies.
CI & config entrypoints
README.md— Repository readmeexamples/sqlite/relations/src/main.rs— Rust binary entrypointexamples/sqlite/embedded/src/main.rs— Rust binary entrypointexamples/postgres/relations/src/main.rs— Rust binary entrypointexamples/postgres/custom_types/src/main.rs— Rust binary entrypointexamples/postgres/advanced-blog-cli/src/main.rs— Rust binary entrypointdiesel_cli/src/main.rs— Rust binary entrypoint.github/workflows/release.yml— GitHub Actions workflow.github/workflows/cflite_prune.yml— GitHub Actions workflow.github/workflows/metrics.yml— GitHub Actions workflow
Structural health signals
Average score 7.7/10 across 96 analyzed source files; 21 hotspots surfaced.
diesel/src/sqlite/connection/mod.rs— 1284 lines, score 4 (Large file, Deep nesting)diesel/src/sqlite/connection/sqlite_value.rs— 931 lines, score 4 (Large file, Deep nesting)diesel/src/sqlite/connection/pragmas.rs— 1333 lines, score 4 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
5cdf54e1434b2026-10-02 — Merge pull request #5261 from malandrina/lw-local-mysql-version69f8b047fb842026-10-02 — Merge pull request #5258 from Samyra312007/miri-ffi-tests2d66feaa58652026-10-02 — Merge pull request #5170 from LucaCappelletti94/mysql-negative-time298d0fcb14412026-10-02 — Post merge fixes7146c77e45062026-10-02 — Merge remote-tracking branch 'upstream/main' into miri-ffi-tests