Axum Diesel Real-World Example

A modular Rust backend template designed with a Domain-Driven Design (DDD) approach, powered by the Axum web framework and Diesel ORM. This repository aims to provide a robust starting point for building scalable and maintainable real-world applications in Rust.

Table of Contents

• Introduction
• Features
• Prerequisites
• Getting Started
• Project Structure
• Configuration
• Database Migrations
• Running the Application
• Contributing
• License

Introduction

This repository offers a boilerplate for developing Rust backend applications, emphasizing clean architecture through Domain-Driven Design. It leverages the asynchronous capabilities of Axum for building high-performance web APIs and Diesel for efficient database interaction, primarily with PostgreSQL.

Features

• Domain-Driven Design (DDD): Clear separation of concerns with domain, application, and infrastructure layers.
• Asynchronous API: Built with Axum, leveraging the Tokio runtime.
• Database ORM: Uses Diesel for database operations and migrations.
• Connection Pooling: Integrates deadpool-diesel for managing database connections.
• Configuration Management: Centralized configuration loading.
• Error Handling: Structured application-wide error management.
• Modular Structure: Designed for easy extension and maintainability.
• Logging: Integrated tracing for structured logging.
• (Optional: Authentication modules with OAuth, etc. - can be added as features are developed)

Prerequisites

Before you begin, ensure you have the following installed:

• Rust (latest stable version recommended)
• Diesel CLI (for your specific database, e.g., PostgreSQL):

cargo install diesel_cli --no-default-features --features postgres

• A running PostgreSQL instance (or your database of choice, with adjustments).

Getting Started

• Clone the repository:

git clone https://github.com/Quentin-Piot/axum-diesel-real-world.git
    cd axum-diesel-real-world

• Set up your environment:

Create a .env file in the root of the project by copying the example:

cp .env.example .env

Edit .env and set your DATABASE_URL and other configurations as needed. For example:

DATABASEURL=postgres://user:password@localhost/yourdb_name
    SERVER_HOST=127.0.0.1
    SERVER_PORT=8000
    RUSTLOG=axumdieselrealworld=debug,tower_http=debug

• Setup the database and run migrations:

Ensure your PostgreSQL server is running and the database specified in DATABASE_URL exists.

diesel setup
    diesel migration run

This will create the necessary tables defined in the migrations/ directory.

• Build the project:

cargo build

Project Structure

The project follows a DDD-inspired modular structure:

• src/: Main application source code.

- config.rs: Application configuration loading (e.g., using once_cell). - domain/: Core business logic and domain entities. - models.rs: Domain model structs (distinct from database persistence models if needed). - services/: Domain services. - errors.rs: Custom application-wide error types and conversions. - handlers/: Axum request handlers (controllers in MVC terms). - infra/: Infrastructure concerns like database access, external API clients. - db.rs: Database connection setup, connection pool. - repositories.rs: Implementations of repository patterns for data access. - models.rs: (Could be here or in infra/) Persistence-layer structs, often generated or used by Diesel. - routes.rs: API route definitions. - schema.rs: Auto-generated by Diesel, representing the database schema. - state.rs: Defines AppState shared across handlers. - utils/: Utility functions, custom extractors, etc. - main.rs: Application entry point, server setup.

• migrations/: Diesel database migration files.
• .env.example: Example environment file.
• Cargo.toml: Project dependencies and metadata.

Configuration

Application configuration is managed via environment variables, typically loaded from a .env file using a crate like dotenvy. The src/config.rs module handles loading and providing access to these configurations.

Database Migrations

Diesel is used for managing database schema changes.

• To create a new migration:

diesel migration generate yourmigrationname

• To run pending migrations:

diesel migration run

• To revert the last migration:

diesel migration redo

The application also runs pending migrations automatically on startup.

Running the Application

• Development Mode:

cargo run

The server will typically start on http://127.0.0.1:3000 (or as configured).

• Release Mode:

cargo build --release
    ./target/release/axum-diesel-real-world

Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request.

• Fork the Project
• Create your Feature Branch (git checkout -b feature/AmazingFeature)
• Commit your Changes (git commit -m 'Add some AmazingFeature')
• Push to the Branch (git push origin feature/AmazingFeature)
• Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.