Merge pull request #992 from alexted/feature/diesel-async-example

Diesel-async usage example

Author: robjtede

.github/workflows/ci-nightly.yml

@@ -21,16 +21,21 @@ jobs:
         with:
           toolchain: ${{ matrix.version }}
 
+      - name: Install system packages
+        run: |
+          sudo apt-get update
+          sudo apt-get -y install sqlite3
+          sudo apt-get -y install libpq-dev
+
       - name: Install DB CLI tools
         run: |
           cargo install --force sqlx-cli --no-default-features --features=sqlite,rustls
-          cargo install --force diesel_cli --no-default-features --features sqlite
+          cargo install --force diesel_cli --no-default-features --features=sqlite,postgres
 
       - name: Create Test DBs
         env:
           DATABASE_URL: sqlite://./todo.db
         run: |
-          sudo apt-get update && sudo apt-get install sqlite3
           sqlx database create
           chmod a+rwx ./todo.db
           sqlx migrate run --source=./basics/todo/migrations

.github/workflows/ci.yml

@@ -26,16 +26,21 @@ jobs:
         with:
           toolchain: ${{ matrix.version }}
 
+      - name: Install system packages
+        run: |
+          sudo apt-get update
+          sudo apt-get -y install sqlite3
+          sudo apt-get -y install libpq-dev
+
       - name: Install DB CLI tools
         run: |
           cargo install --force sqlx-cli --no-default-features --features=sqlite,rustls
-          cargo install --force diesel_cli --no-default-features --features sqlite
+          cargo install --force diesel_cli --no-default-features --features=sqlite,postgres
 
       - name: Create Test DBs
         env:
           DATABASE_URL: sqlite://./todo.db
         run: |
-          sudo apt-get update && sudo apt-get install sqlite3
           sqlx database create
           chmod a+rwx ./todo.db
           sqlx migrate run --source=./basics/todo/migrations

Cargo.lock

@@ -17,6 +17,7 @@ members = [
   "cors/backend",
   "data-factory",
   "databases/diesel",
+  "databases/diesel-async",
   "databases/mongodb",
   "databases/mysql",
   "databases/postgres",

Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "db-diesel-async"
+version = "1.0.0"
+edition = "2021"
+
+[features]
+postgres_tests = []
+
+[dependencies]
+actix-web.workspace = true
+diesel = { version = "2", default-features = false, features = ["uuid"] }
+diesel-async = { version = "0.5", features = ["postgres", "bb8", "async-connection-wrapper"] }
+serde.workspace = true
+uuid.workspace = true
+dotenvy.workspace = true
+env_logger.workspace = true
+log.workspace = true

databases/diesel-async/Cargo.toml

@@ -0,0 +1,113 @@
+# diesel
+
+Basic integration of [Diesel-async](https://github.com/weiznich/diesel_async) using PostgreSQL for Actix Web.
+
+## Usage
+
+### Install PostgreSQL
+
+```sh
+# on any OS
+docker run -d --restart unless-stopped --name postgresql -e POSTGRES_USER=test-user -e POSTGRES_PASSWORD=password -p 5432:5432 -v postgres_data:/var/lib/postgresql/data postgres:alpine
+```
+make sure it has successfully started up and is running
+```sh
+# on any OS
+docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Status}}\t{{.Ports}}"
+```
+
+### Initialize PostgreSQL Database
+
+```sh
+cd databases/diesel-async
+cargo install diesel_cli --no-default-features --features postgres
+
+echo DATABASE_URL=postgres://test-user:password@localhost:5432/test_db > .env
+diesel setup
+diesel migration run
+```
+
+The database will now be created in your PostgreSQL instance.
+```sh
+docker exec -i postgresql psql -U test-user -c "\l"
+```
+
+### Running Server
+
+```sh
+cd databases/diesel-async
+cargo run
+
+# Started http server: 127.0.0.1:8080
+```
+
+### Available Routes
+
+#### `POST /items`
+
+Inserts a new item into the PostgreSQL DB.
+
+Provide a JSON payload with a name. Eg:
+
+```json
+{ "name": "thingamajig" }
+```
+
+On success, a response like the following is returned:
+
+```json
+{
+  "id": "01948982-67d0-7a55-b4b1-8b8b962d8c6b",
+  "name": "thingamajig"
+}
+```
+
+<details>
+  <summary>Client Examples</summary>
+
+Using [HTTPie]:
+
+```sh
+http POST localhost:8080/items name=thingamajig
+```
+
+Using cURL:
+
+```sh
+curl -S -X POST --header "Content-Type: application/json" --data '{"name":"thingamajig"}' http://localhost:8080/items
+```
+
+</details>
+
+#### `GET /items/{item_uid}`
+
+Gets an item from the DB using its UID (returned from the insert request or taken from the DB directly). Returns a 404 when no item exists with that UID.
+
+<details>
+  <summary>Client Examples</summary>
+
+Using [HTTPie]:
+
+```sh
+http localhost:8080/items/9e46baba-a001-4bb3-b4cf-4b3e5bab5e97
+```
+
+Using cURL:
+
+```sh
+curl -S http://localhost:8080/items/9e46baba-a001-4bb3-b4cf-4b3e5bab5e97
+```
+
+</details>
+
+### Explore The PostgreSQL DB
+
+```sh
+docker exec -i postgresql psql -U test-user -d test_db -c "select * from public.items"
+```
+
+## Using Other Databases
+
+You can find a complete example of Diesel + PostgreSQL at: [https://github.com/TechEmpower/FrameworkBenchmarks/tree/master/frameworks/Rust/actix](https://github.com/TechEmpower/FrameworkBenchmarks/tree/master/frameworks/Rust/actix)
+
+[httpie]: https://httpie.io/cli

databases/diesel-async/README.md

@@ -0,0 +1,9 @@
+# For documentation on how to configure this file,
+# see https://diesel.rs/guides/configuring-diesel-cli
+
+[print_schema]
+file = "src/schema.rs"
+custom_type_derives = ["diesel::query_builder::QueryId", "Clone"]
+
+[migrations_directory]
+dir = "/home/alex/CLionProjects/actix-with-async-diesel/migrations"

databases/diesel-async/diesel.toml

@@ -0,0 +1,6 @@
+-- This file was automatically created by Diesel to setup helper functions
+-- and other internal bookkeeping. This file is safe to edit, any future
+-- changes will be added to existing projects as new migrations.
+
+DROP FUNCTION IF EXISTS diesel_manage_updated_at(_tbl regclass);
+DROP FUNCTION IF EXISTS diesel_set_updated_at();

databases/diesel-async/migrations/.keep

@@ -0,0 +1,36 @@
+-- This file was automatically created by Diesel to setup helper functions
+-- and other internal bookkeeping. This file is safe to edit, any future
+-- changes will be added to existing projects as new migrations.
+
+
+-- Sets up a trigger for the given table to automatically set a column called
+-- `updated_at` whenever the row is modified (unless `updated_at` was included
+-- in the modified columns)
+--
+-- # Example
+--
+-- ```sql
+-- CREATE TABLE users (id SERIAL PRIMARY KEY, updated_at TIMESTAMP NOT NULL DEFAULT NOW());
+--
+-- SELECT diesel_manage_updated_at('users');
+-- ```
+CREATE OR REPLACE FUNCTION diesel_manage_updated_at(_tbl regclass) RETURNS VOID AS
+$$
+BEGIN
+    EXECUTE format('CREATE TRIGGER set_updated_at BEFORE UPDATE ON %s
+                    FOR EACH ROW EXECUTE PROCEDURE diesel_set_updated_at()', _tbl);
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE OR REPLACE FUNCTION diesel_set_updated_at() RETURNS trigger AS
+$$
+BEGIN
+    IF (
+        NEW IS DISTINCT FROM OLD AND
+        NEW.updated_at IS NOT DISTINCT FROM OLD.updated_at
+        ) THEN
+        NEW.updated_at := current_timestamp;
+    END IF;
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;

databases/diesel-async/migrations/00000000000000_diesel_initial_setup/down.sql

@@ -0,0 +1,2 @@
+-- This file should undo anything in `up.sql`
+DROP TABLE IF EXISTS items;

databases/diesel-async/migrations/00000000000000_diesel_initial_setup/up.sql

@@ -0,0 +1,6 @@
+-- Your SQL goes here
+CREATE TABLE IF NOT EXISTS items
+(
+    id uuid DEFAULT gen_random_uuid() PRIMARY KEY,
+    name VARCHAR NOT NULL
+);