{"id":101897,"date":"2024-04-26T14:54:23","date_gmt":"2024-04-26T14:54:23","guid":{"rendered":"https:\/\/www.red-gate.com\/simple-talk\/?p=101897"},"modified":"2024-03-25T15:46:17","modified_gmt":"2024-03-25T15:46:17","slug":"building-restful-apis-in-rust-with-actix-and-diesel","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/development\/web\/building-restful-apis-in-rust-with-actix-and-diesel\/","title":{"rendered":"Rust REST API Tutorial: Building with Actix-web and Diesel ORM – Handlers, Models, Migrations, and Database Integration"},"content":{"rendered":"

Rust is a systems programming language that has gained mainstream adoption for web services because of its performance (near-C speeds), memory safety (no garbage collector, no null pointer exceptions, no data races), and growing ecosystem of production-grade web libraries. This article builds a complete REST API in Rust using two cornerstone libraries: (1) Actix-web – the most widely-used Rust web framework, known for exceptional performance (consistently top of TechEmpower benchmarks) and a pragmatic actor-based architecture; (2) Diesel – the mature Rust ORM, providing compile-time-checked query construction, schema migrations, and support for PostgreSQL, MySQL, and SQLite. Walkthrough: (a) Cargo project setup with Actix-web and Diesel dependencies; (b) defining models and deriving Diesel’s table schema; (c) database migrations using the diesel CLI; (d) connection pooling with r2d2; (e) Actix-web route definitions and handler functions; (f) CRUD handlers (GET, POST, PUT, DELETE) with JSON request\/response via serde; (g) error handling patterns using Result and custom error types. Ecosystem note: the Rust web ecosystem has evolved rapidly – Axum (by the Tokio team) has become a popular alternative to Actix-web, SQLx has become a popular alternative to Diesel (async-first, query-time checking rather than compile-time). Actix-web and Diesel remain solid choices and are production-proven; the decision between them vs Axum\/SQLx is largely based on async preferences and compile-time vs runtime check tradeoffs.<\/b><\/p>\n

There are many packages and tools that you can use to facilitate your API development with Rust. Rust has a rich third-party ecosystem of crates for building APIs, including web packages like Actix<\/a> and Rocket<\/a> and ORMs like Diesel<\/a> and SeaORM<\/a>.<\/p>\n

This article delves into using Actix and Diesel to build web applications. You\u2019ll learn by building a CRUD API with persistence through Diesel on a Sqlite<\/a> database.<\/p>\n

Actix is a high-performance web framework that runs on the actor model. It is great at handling concurrent requests with lightweight actors that communicate asynchronously. Actix\u2019s architecture promotes scalability and responsiveness, which is ideal for building performant web apps.<\/p>\n

For data persistence, Diesel is a mature ORM that flexibly acts as a bridge between Rust data types and database tables. You\u2019ll write native Rust programs, and Diesel will create statements and queries to execute on your preferred DBMS.<\/p>\n

Setting up the API Development Environment<\/h2>\n

Setting up a development environment for building REST APIs in Rust is relatively simple. You must download and install<\/a> a recent version of Rust on your computer to get started.<\/p>\n

Run this command on your terminal to verify that you\u2019ve successfully installed Rust and Cargo (Rust\u2019s package management tool).<\/p>\n

rustc --version\r\ncargo --version<\/pre>\n
Next, Run these commands on your terminal to create and initialize a new Rust project on your computer:<\/p>\n
mkdir rusting-actix-diesel && cd rusting-actix-diesel\r\n\r\ncargo init rusting-actix-diesel<\/pre>\n
The cargo init<\/code> command initializes a new Rust project in the specified working directory. The command also creates a cargo.toml<\/code> file in the directory for managing your project\u2019s dependencies.<\/p>\n
You\u2019ll need some form of persistence for your database. In this tutorial, you\u2019ll learn how to use Diesel and an SQL database for persistence for your API. Diesel supports a variety of SQL databases, including Sqlite<\/a>, MySQL<\/a>, and PostgreSQL<\/a>. Install your preferred database management system, and you\u2019re good to go.<\/p>\n
<\/a>Setting Up the Database for Persistence<\/h2>\n
You have to add the diesel<\/code> and dotenv<\/code> crates as project dependencies in the dependencies section of your cargo.toml<\/code> file.<\/p>\n
[dependencies]\r\ndiesel = { version = \"2.1.0\", features = [\"sqlite\"] }\r\ndotenv = \"0.15.0\"<\/pre>\n
Once you\u2019ve added these crates as dependencies, you must install the diesel_cli<\/code> tool to interact with Diesel over the command line for migrations and schema generation.<\/p>\n
Run this command to install the diesel_cli<\/code> tool:<\/p>\n
cargo install diesel_cli<\/pre>\n
You can run the diesel_cli<\/code> tool diesel_cli<\/code> command after installing the tool.<\/p>\n
Next, create an environment variables file and specify your database URL with the DATABASE_URL<\/code> field. Run this command to create and insert the database URL for an in-memory Sqlite database.<\/p>\n
echo DATABASE_URL=database.db > .env<\/pre>\n
Next, run the setup<\/code> command for Diesel to set up a database for your project:<\/p>\n
diesel setup<\/pre>\n
The setup<\/code> command creates a migrations<\/code> directory, the database specified in the DATABASE_URL<\/code>, and runs existing migrations.<\/p>\n
After you\u2019ve set up your database with Diesel, you\u2019ll use the migration generate<\/code> command to generate SQL migration files. You\u2019ll add the name of the migration as an argument to the migration generate<\/code> command:<\/p>\n
diesel migration generate create_humans<\/pre>\n
The command generates two SQL files in the migrations<\/code> directory: up.sql<\/code> and down.sql<\/code>.<\/p>\n
Write SQL for your database table definitions in the up.sql<\/code> file as thus:<\/p>\n
-- up.sql\r\n\r\n-- Your SQL goes here\r\nCREATE TABLE \"human\"\r\n(\r\n    \"id\"         INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,\r\n    \"first_name\" TEXT    NOT NULL,\r\n    \"last_name\"  TEXT    NOT NULL,\r\n    \"age\"        INTEGER NOT NULL\r\n);<\/pre>\n
Then, write the SQL code to drop database tables in the down.sql<\/code> file:<\/p>\n
-- down.sql\r\n\r\n-- This file should undo anything in `up.sql`\r\nDROP TABLE \"human\"<\/pre>\n
After writing the SQL files, run the migration run<\/code> command to apply pending migrations.<\/p>\n
diesel migration run<\/pre>\n
After a successful process, you can use the print-schema<\/code> command to print the schema. The command prints the contents of the schema.rs file.<\/p>\n
diesel print-schema<\/p>\n
The output of the print_schema<\/code> command is Rust code that matches your SQL schema.<\/p>\n
<\/p>\n
Attach the schema.rs<\/code> file to your main.rs<\/code> file with the mod schema<\/code> directive to use the contents of the schema.rs<\/code> file in the main.rs<\/code> file and other parts of your package.<\/p>\n
You must declare structs for data serialization, migrations, and deserialization operations. You can create a models.rs file and add struct definitions to match your database schema.<\/p>\n
Here are the structs for the CRUD operations:<\/p>\n
\/\/ models.rs\r\nuse diesel::prelude::*;\r\nuse serde::{Deserialize, Serialize};\r\nuse crate::schema::human;\r\n#[derive(Queryable, Serialize)]\r\npub struct Human {\r\n    pub id: i32,\r\n    pub first_name: String,\r\n    pub last_name: String,\r\n    pub age: i32,\r\n}\r\n#[derive(Queryable, Insertable, Serialize, Deserialize)]\r\n#[table_name = \"human\"]\r\npub struct NewHuman {\r\n    pub first_name: String,\r\n    pub last_name: String,\r\n    pub age: i32,\r\n}\r\n#[derive(Deserialize, AsChangeset)]\r\n#[table_name = \"human\"]\r\npub struct UpdateHuman {\r\n    first_name: Option<String>,\r\n    last_name: Option<String>,\r\n    age: Option<i32>,\r\n}<\/pre>\n
The request handler functions returns the Student<\/code> struct. You can use the NewStudent<\/code> for data migration and the UpdateStudent<\/code> struct for PUT requests.<\/p>\n
<\/a>Connecting to Your SQL Database With Diesel<\/h3>\n
You\u2019ll use the env<\/code> and Connection<\/code> to connect your SQL database with Diesel.<\/p>\n
Here\u2019s how you can connect to an SQLite database with a function and return a connection instance:<\/p>\n
\/\/ src\/model.rs\r\nuse std::env;\r\nuse diesel::prelude::*;\r\nuse dotenv::dotenv;\r\npub fn establish_connection() -> SqliteConnection {\r\n    dotenv().ok();\r\n    let database_url = env::var(\"DATABASE_URL\").expect(\r\n                  \"DATABASE_URL must be set\");\r\n    SqliteConnection::establish(&database_url)\r\n        .unwrap_or_else(|_| panic!\r\n        (\"Error connecting to the database: {}\",  \r\n                         database_url))\r\n}<\/pre>\n
The establish_connection<\/code> function returns the connection instance struct (SqliteConnection<\/code>). The establish_connection<\/code> loads the environment variables with the ok<\/code> function accesses the database URL with the var<\/code> function, and establishes a connection with the database via the URL with the establish<\/code> function.<\/p>\n
<\/a>Setting Up Actix-web for Routing and Server Operations<\/h2>\n
After setting up the database for persistence, you can set up a server with Actix with routes for your handler functions.<\/p>\n
Here are the contents of the [main.rs<\/code>] file containing the main<\/code> function that handles the routing and starts the server:<\/p>\n
\/\/ main.rs\r\n\/\/ attaches the files in the package to the `main.rs` file \r\nmod database;\r\nmod model;\r\nmod schema;\r\nmod handlers;\r\n\/\/ import the functionality for starting the server\r\nuse actix_web::{web, App, HttpServer};\r\n\/\/ import the handler function\r\nuse crate::handlers::{create_human, delete_human, get_humans, update_human};\r\n#[actix_web::main]\r\nasync fn main() -> std::io::Result<()> {\r\n    HttpServer::new(|| {\r\n        App::new()\r\n            .route(\"\/human\", web::post().to(create_human))\r\n            .route(\"\/humans\", web::get().to(get_humans)) \r\n                      \/\/ changed this route path\r\n            .route(\"\/human\/{id}\", web::put().to(update_human))\r\n            .route(\"\/human\/{id}\", web::delete().to(delete_human))\r\n    })\r\n        .bind(\"127.0.0.1:8080\")?\r\n        .run()\r\n        .await\r\n}<\/pre>\n
The main<\/code> function is an asynchronous function that starts the server with the HttpServer::new<\/code> function that takes in the App::new<\/code> function, which handles the routes. The bind<\/code> function binds the routes to the specified host, and the run<\/code> function runs the server.<\/p>\n
After setting up the server, you can import these functions in your [handlers.rs](<http:\/\/handlers.rs>)<\/code> file, where you\u2019ll specify the handler functions for the API.<\/p>\n
\/\/ handlers.rs\r\n\/\/ import the database connection function\r\nuse crate::database::establish_connection;\r\n\/\/ import necessary actix functionality\r\nuse actix_web::{web, App, HttpResponse, HttpServer, Result};\r\n\/\/ import necessary diesel functionality\r\nuse diesel::{prelude::*, sqlite::SqliteConnection};\r\n\/\/ import the structs from model.rs\r\nuse crate::model::{Human, NewHuman, UpdateHuman};<\/pre>\n
Once you\u2019ve imported the necessary functions and types, you can start writing the handler functions that run when users make API requests to the server.<\/p>\n
<\/a>The POST Request Handler Function<\/h2>\n
The create_human<\/code> function is the POST request handler function. The create_human<\/code> function will retrieve the JSON payload from the request and return a JSON payload containing a success message to the client.<\/p>\n
pub async fn create_human(new_human: web::Json<NewHuman>) -> Result<HttpResponse> {\r\n    use crate::schema::human::dsl::*;\r\n    let mut connection = establish_connection();\r\n\t\t\r\n    diesel::insert_into(human)\r\n        .values(&new_human.into_inner())\r\n        .execute(&mut connection)\r\n        .expect(\"Error inserting new human\");\r\n    Ok(HttpResponse::Ok().json(\r\n                     \"data inserted into the database\"))\r\n}<\/pre>\n
The create_human<\/code> handler function connects to the database with the establish_connection<\/code> function, inserts the new_human<\/code> data from the JSON payload inton the database with the insert_into<\/code> function, and uses the HttpResponse::Ok <\/code>function to return a JSON<\/code> payload after a successful request.<\/p>\n
Here\u2019s a CURL<\/code> request that you can use to test the create_human<\/code> handler function.<\/p>\n
curl -X POST http:\/\/127.0.0.1:8080\/humans -H \"Content-Type: \r\napplication\/json\" -d '{\"first_name\": \"John\", \"last_name\": \r\n\"Doe\", \"age\": 30}'<\/pre>\n
Here\u2019s the result of a successful data insertion operation on the database:<\/p>\n
<\/p>\n
<\/a>The GET Request Handler Function<\/h2>\n
The get_humans<\/code> function is a GET<\/code> request handler function that retrieves all the entries in the database and returns them to the client.<\/p>\n
\/\/ READ ALL\r\npub async fn get_humans() -> Result<HttpResponse> {\r\n    use crate::schema::human::dsl::*;\r\n    let mut connection = establish_connection();\r\n    let humans = human\r\n        .load::<Human>(&mut connection)\r\n        .expect(\"Error loading humans\");\r\n    Ok(HttpResponse::Ok().json(humans))\r\n}<\/pre>\n
After connecting to the database, the get_humans<\/code> handler function uses the load<\/code> function to load all the Human<\/code> entries in the database.<\/p>\n
Here\u2019s a CURL<\/code> request that makes a call to trigger the functionality of the get_humans<\/code> handler function:<\/p>\n
curl http:\/\/127.0.0.1:8080\/humans<\/pre>\n
On sending a GET request to the API via CURL you should expect to retrieve the entries in the database as such:<\/p>\n
<\/p>\n
<\/a>The PUT Request Handler Function<\/h2>\n
The update_human<\/code> function is an asynchronous function that takes the id and a JSON payload from the client\u2019s request and returns the data from the payload after updating the database entry.<\/p>\n
\/\/ UPDATE\r\npub async fn update_human(\r\n    id: web::Path<i32>,\r\n    human_update: web::Json<UpdateHuman>,\r\n) -> Result<HttpResponse> {\r\n    use crate::schema::human::dsl::*;\r\n    let mut connection = establish_connection();\r\n    \/\/ Use the `update` method of the Diesel ORM \r\n    \/\/to update the student's record\r\n    let updated_human = diesel::update(human.find(id))\r\n        .set(&human_update.into_inner())\r\n        .execute(&mut connection)\r\n        .expect(\"Failed to update student\");\r\n    Ok(HttpResponse::Ok().json(updated_human))\r\n}<\/pre>\n
The update_human<\/code> handler function uses the update<\/code> function to update the entry after confirming that the id<\/code> exists with the find<\/code> function.<\/p>\n
Here\u2019s a CURL request that sends a PUT request to the database and triggers the update_human<\/code> function.<\/p>\n
curl -X PUT http:\/\/127.0.0.1:8080\/humans\/{id} -H \r\n\"Content-Type: application\/json\" -d '{\"first_name\": \"Jane\", \r\n\"last_name\": \"Doe\", \"age\": 32}'<\/pre>\n
On sending the CURL<\/code> request, here\u2019s the result of the update operation:<\/p>\n
<\/p>\n
<\/a>The DELETE Request Handler Function<\/h2>\n
The DELETE<\/code> request handler function will retrieve the id<\/code> from the request and delete the row with the id<\/code> from the database.<\/p>\n
\/\/ DELETE\r\npub async fn delete_human(id: web::Path<i32>) -> Result<HttpResponse> {\r\n    use crate::schema::human::dsl::*;\r\n    let mut connection = establish_connection();\r\n    diesel::delete(human.find(id))\r\n        .execute(&mut connection)\r\n        .expect(&format!(\"Unable to find student {:?}\", id));\r\n    Ok(HttpResponse::Ok().json(\"Deleted successfully\"))\r\n}<\/pre>\n
The delete_human<\/code> handler function deletes the entry with the id from the database with Diesel\u2019s delete<\/code> function and returns a string response to confirm the operation’s success.<\/p>\n
Here\u2019s a CURL<\/code> request that seeks to delete the entry having the id<\/code> field of 1 from the database:<\/p>\n
curl -X DELETE http:\/\/127.0.0.1:8080\/humans\/{id}<\/pre>\n
The result from a successful DELETE<\/code> request to the database should have this form:<\/p>\n
<\/p>\n
<\/a>Conclusion<\/h2>\n
This guide explored setting up a RESTful API in Rust using Actix, Diesel, and SQLite. You have learned to define CRUD operations and used CURL<\/code> commands to demonstrate how the API responds to different requests. Rust’s flexibility, combined with Actix’s speed and Diesel’s versatility, makes this stack a powerful choice for backend development.<\/p>\n
As you progress with Rust, you’ll find many more libraries and tools in the Rust ecosystem that you can use to extend and improve your API. You can take the functionality of this API a step further by adding authentication and authorization mechanisms to secure your API and implement logging and error handling to make debugging easier.<\/p>\n
 <\/p>\n","protected":false},"excerpt":{"rendered":"
Building a REST API in Rust using Actix-web as the web framework and Diesel as the ORM – defining routes and handlers, connecting to PostgreSQL with Diesel, running migrations, and implementing CRUD endpoints with JSON serialization via serde. Complete tutorial with project structure.…<\/p>\n","protected":false},"author":340771,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[53,147005],"tags":[159071],"coauthors":[147592],"class_list":["post-101897","post","type-post","status-publish","format-standard","hentry","category-featured","category-web","tag-rust"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/101897","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/users\/340771"}],"replies":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/comments?post=101897"}],"version-history":[{"count":3,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/101897\/revisions"}],"predecessor-version":[{"id":101906,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/101897\/revisions\/101906"}],"wp:attachment":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/media?parent=101897"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/categories?post=101897"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/tags?post=101897"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/coauthors?post=101897"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}