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

1. Clone the repository:

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

2. 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:

   DATABASE_URL=postgres://user:password@localhost/your_db_name
   SERVER_HOST=127.0.0.1
   SERVER_PORT=8000
   RUST_LOG=axum_diesel_real_world=debug,tower_http=debug

3. 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.

4. 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 your_migration_name

• 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.

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

License

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