DEV Community: Aaron Leopold

Starter Axum, GraphQL and SeaORM Template

Aaron Leopold — Wed, 16 Mar 2022 16:04:04 +0000

👋 Hello! I recently contributed to SeaORM and added a starter template I created for bootstrapping APIs using Axum, GraphQL and SeaORM. I wanted to share this here to:

give SeaORM some more exposure (it's a great ORM!)
help out some people wanting to try this stack
get some feedback to help me grow

In this post I'll give an overview of how to create the template from scratch, however the final template is available here if you'd like to just skip ahead past the "how I made this" part and take a look.

Project Structure 🧬

.
├── Cargo.lock
├── Cargo.toml
├── db
├── entity
│   ├── Cargo.toml
│   └── src
│       ├── lib.rs
│       └── note.rs
├── migration
│   ├── Cargo.lock
│   ├── Cargo.toml
│   ├── README.md
│   └── src
│       ├── lib.rs
│       ├── m20220101_000001_create_table.rs
│       └── main.rs
└── src
    ├── db.rs
    ├── graphql
    │   ├── mod.rs
    │   ├── mutation
    │   │   ├── mod.rs
    │   │   └── note.rs
    │   ├── query
    │   │   ├── mod.rs
    │   │   └── note.rs
    │   └── schema.rs
    └── main.rs

8 directories, 20 file

Prerequisites 🥸

Before we get started, be sure to have rust/cargo properly installed on your machine. Then, we'll install some additional dependencies:

cargo install cargo-watch sea-orm-cli

Note: sea-orm-cli might change soon.

I use cargo-watch on all my rust web projects so that the server restarts/recompiles on file changes. sea-orm-cli is a CLI utility that will help us create our migrations, although there are more functionalities available.

Setup 🔨

As shown in the Project Structure section, this template will have 2 additional crates:

entity: where our database models are defined
migration: where are database migrations are defined

To get started, we will create a barebones Rust project:

cargo new axum-graphql-seaorm

This is just the standard hello world starter template. Now, we want to create the migration and entity crates. We'll start with the migrations.

cd into the project folder and run the following command:

sea-orm-cli migrate init

This will create the migrations directory, with the boilerplate migration structure. To see more information about this, take a look at the corresponding section in the docs.

Now let's create the entity crate:

cargo new --lib entity

We'll want to remove the boilerplate from this and then add the relevant dependencies. Add the following to your Cargo.toml:

[dependencies]
serde = { version = "1", features = ["derive"] }

[dependencies.async-graphql]
version = "3.0.12"

[dependencies.sea-orm]
version = "^0.6.0"
features = [
  "macros",
  "debug-print",
  "runtime-tokio-native-tls",
  "sqlx-sqlite",
]
default-features = false

Notice I am using the sqlx-sqlite feature, for this template I am using sqlite. I typically start with sqlite early on in projects for ease of development, and then transition to MySQL/Postgres later on.

As per SeaORM's suggestion of structuring projects, we will share the sea-orm and async-graphql dependencies to the other crates as to prevent accidental mixing of versions. Add the following to lib.rs:

pub use async_graphql;
pub use sea_orm;

This will allow us pull in those dependencies in our core crate or migration crate like:

use entity::{sea_orm, async_graphql};

Create an entity

The relevant documentation for this section lives here.

Let's create our first entity. The demo API will interact with a simple collection of notes. The note entity will contain title and text fields.

Create a note.rs file with the following content:

use async_graphql::*;
use sea_orm::entity::prelude::*;
use serde::{Deserialize, Serialize};

#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Serialize, Deserialize, SimpleObject)]
#[sea_orm(table_name = "notes")]
#[graphql(concrete(name = "Note", params()))]
pub struct Model {
    #[sea_orm(primary_key)]
    #[serde(skip_deserializing)]
    pub id: i32,
    pub title: String,
    pub text: String,
}

#[derive(Copy, Clone, Debug, EnumIter)]
pub enum Relation {}

impl RelationTrait for Relation {
    fn def(&self) -> RelationDef {
        panic!("No RelationDef")
    }
}

impl ActiveModelBehavior for ActiveModel {}

This will define our Model and Relation for the note entity. Notice the derives throughout the file, but specifically the DeriveEntityModel and SimpleObject.

DeriveEntityModel defines an Entity with associating Model, Column and PrimaryKey.

SimpleObject will directly map the fields of the Model struct to a GraphQL object. You can even skip certain fields using #[graphql(skip)], like if you had a user entity with a password hash, for example.

Our note entity now has the following graphql type definition:

type Note {
  id: Int!
  title: String!
  text: String!
}

Something I like to do is define some utility functions to my entities that don't come default with the Entity struct. Add the following the the bottom of your note.rs file:

note.rs

impl Entity {
    pub fn find_by_id(id: i32) -> Select<Entity> {
        Self::find().filter(Column::Id.eq(id))
    }

    pub fn find_by_title(title: &str) -> Select<Entity> {
        Self::find().filter(Column::Title.eq(title))
    }

    pub fn delete_by_id(id: i32) -> DeleteMany<Entity> {
        Self::delete_many().filter(Column::Id.eq(id))
    }
}

And be sure to add the DeleteMany trait to the sea_orm use statement at the top. What this does is define some extra functions my note::Entity has. I do this mainly to remove code duplication and increase readability.

Add our note entity to our lib.rs file and let's create our first migration.

lib.rs

pub mod note;

Defining our initial migration

We need to add a couple of dependencies to our migration crate. Add the following dependencies to the Cargo.toml file:

dotenv = "0.15.0"
entity = { path = "../entity" }

While we could just hardcode the database URI, I like this little addition of dotenv in my templates to reduce repetition when starting new projects. Create an .env file at the project root, not the migration crate root, with the following line:

DATABASE_URL=sqlite:./db?mode=rwc

The flags at the end are important, as seaorm needs to be to read and write our database file. Now, update your main.rs file in the migration crate to contain the following:

use migration::Migrator;
use sea_schema::migration::*;

#[cfg(debug_assertions)]
use dotenv::dotenv;

#[async_std::main]
async fn main() {
    #[cfg(debug_assertions)]
    dotenv().ok();

    let fallback = "sqlite:./db?mode=rwc";

    match std::env::var("DATABASE_URL") {
        Ok(val) => {
            println!("Using DATABASE_URL: {}", val);
        }
        Err(_) => {
            std::env::set_var("DATABASE_URL", fallback);
            println!("Set DATABASE_URL: {}", fallback);
        }
    };

    cli::run_cli(Migrator).await;
}

All this addition really does is set the env variable if it is not present.

Now that we have that inital set up completed, we can write the actual code for our up and down migrations in the migration file (it will have the migration stamp postfixed with something like create_table.rs). Add the two following utility functions:

fn get_seaorm_create_stmt<E: EntityTrait>(e: E) -> TableCreateStatement {
    let schema = Schema::new(DbBackend::Sqlite);

    schema
        .create_table_from_entity(e)
        .if_not_exists()
        .to_owned()
}

fn get_seaorm_drop_stmt<E: EntityTrait>(e: E) -> TableDropStatement {
    Table::drop().table(e).if_exists().to_owned()
}

I created these to reduce some repetition in my migration files. We are putting them in this migration file, however you can extract them out to a separate file if desired.

Our up migration will have the following content:

    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        let stmts = vec![get_seaorm_create_stmt(note::Entity)];

        for stmt in stmts {
            manager.create_table(stmt.to_owned()).await?;
        }

        Ok(())
    }

I generate a statement vector and loop through it to create each table. I do the same for the down migration:

    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        let stmts = vec![get_seaorm_drop_stmt(note::Entity)];

        for stmt in stmts {
            manager.drop_table(stmt.to_owned()).await?;
        }

        Ok(())
    }

With our up and down migrations created, we can now run a migration to create our table in our database. At the project root, run the following:

sea-orm-cli migrate up

Inspecting the database you should see the notes table!

At this point, we've

created a basic structure for our server
defined a simple note entity
created an initial migration for the database

Next let's create a small Database struct to wrap SeaORM's DatabaseConnection, and then define our GraphQL Schema

Database Struct

I like to wrap SeaORM's DatabaseConnection in my own Database struct. I'll paste it below:

src/db.rs

use entity::sea_orm;
use sea_orm::DatabaseConnection;

pub struct Database {
    pub connection: DatabaseConnection,
}

impl Database {
    pub async fn new() -> Self {
        let connection = sea_orm::Database::connect(std::env::var("DATABASE_URL").unwrap())
            .await
            .expect("Could not connect to database");

        Database { connection }
    }

    pub fn get_connection(&self) -> &DatabaseConnection {
        &self.connection
    }
}

I could just share the DatabaseConnection using OnceCell or directly injecting into the GraphQL context, however I prefer this method in case I want to add any additional functionality to my struct.

Creating the Schema

How you organize your project is entirely up to you, the structure that I have been using is to define a graphql module, that internally has query and mutation submodules, and a schema module. Let's create the files we will be editing, there will be a lot so I will go a little faster here:

mkdir src/graphql
touch src/graphql/mod.rs
touch src/graphql/schema.rs

mkdir src/graphql/query
touch src/graphql/query/mod.rs
touch src/graphql/query/note.rs

mkdir src/graphql/mutation
touch src/graphql/mutation/mod.rs
touch src/graphql/mutation/note.rs

Now that the files are created we will:

create our Query type
create out Mutation type
Define our schema

Create the Query type

Our Query type will have two queries: get all the notes, and get a note by an id. Here you can find more information about SeaORM's select query syntax.

src/graphql/query/note.rs

use async_graphql::{Context, Object, Result};
use entity::{async_graphql, note, sea_orm::EntityTrait};

use crate::db::Database;

#[derive(Default)]
pub struct NoteQuery;

#[Object]
impl NoteQuery {
    async fn get_notes(&self, ctx: &Context<'_>) -> Result<Vec<note::Model>> {
        let db = ctx.data::<Database>().unwrap();

        Ok(note::Entity::find()
            .all(db.get_connection())
            .await
            .map_err(|e| e.to_string())?)
    }

    async fn get_note_by_id(&self, ctx: &Context<'_>, id: i32) -> Result<Option<note::Model>> {
        let db = ctx.data::<Database>().unwrap();

        Ok(note::Entity::find_by_id(id)
            .one(db.get_connection())
            .await
            .map_err(|e| e.to_string())?)
    }
}

We need to use #[Object] to declare our struct as a GraphQL Object. I am using a minimal error handling strategy here, as I didn't want to introduce too many dependencies in this template.

src/graphql/query/mod.rs

use entity::async_graphql;

pub mod note;

pub use note::NoteQuery;

// Add your other ones here to create a unified Query object
// e.x. Query(NoteQuery, OtherQuery, OtherOtherQuery)
#[derive(async_graphql::MergedObject, Default)]
pub struct Query(NoteQuery);

To create a unified Query GraphQL type, I am using #[derive(async_graphql::MergedObject, Default)]. If you had another entity user and created a Query object for it called UserQuery, you would simply just need to add it as shown in the comment examples.

This is the resulting Query type:

type Query {
  getNotes: [Note!]!
  getNoteById(id: Int!): Note
}

Create the Mutation type

Creating the Mutation type will be mostly the same:

src/graphql/mutation/note.rs

use async_graphql::{Context, Object, Result};
use entity::async_graphql::{self, InputObject, SimpleObject};
use entity::note;
use entity::sea_orm::{ActiveModelTrait, Set};

use crate::db::Database;

// I normally separate the input types into separate files/modules, but this is just
// a quick example.

#[derive(InputObject)]
pub struct CreateNoteInput {
    pub title: String,
    pub text: String,
}

#[derive(SimpleObject)]
pub struct DeleteResult {
    pub success: bool,
    pub rows_affected: u64,
}

#[derive(Default)]
pub struct NoteMutation;

#[Object]
impl NoteMutation {
    pub async fn create_note(
        &self,
        ctx: &Context<'_>,
        input: CreateNoteInput,
    ) -> Result<note::Model> {
        let db = ctx.data::<Database>().unwrap();

        let note = note::ActiveModel {
            title: Set(input.title),
            text: Set(input.text),
            ..Default::default()
        };

        Ok(note.insert(db.get_connection()).await?)
    }

    pub async fn delete_note(&self, ctx: &Context<'_>, id: i32) -> Result<DeleteResult> {
        let db = ctx.data::<Database>().unwrap();

        let res = note::Entity::delete_by_id(id)
            .exec(db.get_connection())
            .await?;

        if res.rows_affected <= 1 {
            Ok(DeleteResult {
                success: true,
                rows_affected: res.rows_affected,
            })
        } else {
            unimplemented!()
        }
    }
}

I am only adding a mutation to create and delete a note here, go ahead and try to create an update!

src/graphql/mutation/mod.rs

use entity::async_graphql;

pub mod note;

pub use note::NoteMutation;

// Add your other ones here to create a unified Mutation object
// e.x. Mutation(NoteMutation, OtherMutation, OtherOtherMutation)
#[derive(async_graphql::MergedObject, Default)]
pub struct Mutation(NoteMutation);

Create the Schema

Now that we have defined our Mutation and Query types, let's go ahead and define our schema. To start, add the following to your mod.rs

src/graphql/mod.rs

pub mod mutation;
pub mod query;
pub mod schema;

We won't actually be globally defining our schema in the schema.rs file, instead we will create a helper function that will build and return the schema. To do so, let's create a type for our schema and the function itself:

src/graphql/schema.rs

use async_graphql::{EmptySubscription, Schema};
use entity::async_graphql;

use crate::{
    db::Database,
    graphql::{mutation::Mutation, query::Query},
};

pub type AppSchema = Schema<Query, Mutation, EmptySubscription>;

/// Builds the GraphQL Schema, attaching the Database to the context
pub async fn build_schema() -> AppSchema {
    let db = Database::new().await;

    Schema::build(Query::default(), Mutation::default(), EmptySubscription)
        .data(db)
        .finish()
}

We define the type of our schema according to our Query and Mutation types, and an empty subscription (since we don't have any subscriptions). If you had subscriptions, you would create it similar to how we created the others!

We create a database struct that the schema will manage using the data function call. This will inject the database struct into the GraphQL context. Looking back at either the query or mutation structs, you can see this in action:

let db = ctx.data::<Database>().unwrap();

At this point:

We have our entity defined
We have the connection available, through Database struct
We defined our migration (and ran it!)
We created our Query/Mutation types, and our Schema

That pretty much wraps up everything we need to get started! All that is left is to create the server and test!

Create the Axum server

I chose Axum mostly to learn it, I have also used Rocket in the past. Both are great, choose whichever is your preference. The syntax of Rocket is probably a little better for me personally, however.

This has gotten long, so I'll paste the code below and overview it afterwards 🙂

src/main.rs

mod db;
mod graphql;

use entity::async_graphql;

use async_graphql::http::{playground_source, GraphQLPlaygroundConfig};
use async_graphql_axum::{GraphQLRequest, GraphQLResponse};
use axum::{
    extract::Extension,
    response::{Html, IntoResponse},
    routing::get,
    Router,
};
use graphql::schema::{build_schema, AppSchema};

#[cfg(debug_assertions)]
use dotenv::dotenv;

async fn graphql_handler(schema: Extension<AppSchema>, req: GraphQLRequest) -> GraphQLResponse {
    schema.execute(req.into_inner()).await.into()
}

async fn graphql_playground() -> impl IntoResponse {
    Html(playground_source(GraphQLPlaygroundConfig::new(
        "/api/graphql",
    )))
}

#[tokio::main]
async fn main() {
    #[cfg(debug_assertions)]
    dotenv().ok();

    let schema = build_schema().await;

    let app = Router::new()
        .route(
            "/api/graphql",
            get(graphql_playground).post(graphql_handler),
        )
        .layer(Extension(schema));

    println!("Playground: http://localhost:3000/api/graphql");

    axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
        .serve(app.into_make_service())
        .await
        .unwrap();
}

graphql_handler actually handles the GraphQL requests, invoking the execute function of the schema using the request.

graphql_playground returns the HTML for the GraphQL Playground, this is the fancy looking version, as opposed to the GraphiQL version.

Notice we call the dotenv().ok() here, so the downstream uses, namely in db.rs can use the .env variables. We create the schema using the build_schema utility we built, and then add it as an extension layer to our axum app. I use the /api/graphql prefix for the get and post requests, as my brain prefers the semantics of pinging that instead of /graphql.

Wrapping it all up 🌯

Our application should be all good to run now! Double check you've imported all the required traits and what not, and give it a whirl! If you plan on making changes live and wanted a hot reload, run:

cargo watch -x run

Otherwise just cargo run

Navigate to localhost:3000/api/graphql to get to the playground and test out the API!

createNote

mutation {
  createNote(input:{title:"Noice noice note", text:"This is the note content!"}) {
    id
  }
}

getNotes

query {
  getNotes {
    id
    title
    text
  }
}

getNoteById

query {
  getNoteById(id:1) {
    title
    text
  }
}

Tada! We're done! 🎉

Thanks for bearing with me! Let me know if this was helpful or if you have any notes (I love notes!)

Additionally, if you're looking to dip your toes into a project that uses some of this technology stack, consider contributing to my personal project Stump - A free and open source comic book server with OPDS support, written in Rust and React.

Minimal REST API Template using Express

Aaron Leopold — Mon, 22 Nov 2021 16:45:01 +0000

👋 Hello everybody! I recently helped a friend who is very new to web development get started with creating an express REST API for the mobile application they are creating. I figured I would share how I created the base template I drafted in case it can help anyone else!

Overview ✨

At the end of this, you will have a very minimal template for scaling up your node/express application. Everything will be in JavaScript, however I encourage you to instead consider learning/using TypeScript for the enhanced safety benefits and developer experience. Since this was for an absolute beginner, I omitted TypeScript.

The API we create will be a simple hello world example, however the larger point is to showcase how I typically structure these types of projects to allow for an organized way of scaling it up to something larger. I'm always learning, so please let me know if you have any thoughts throughout this!

Project Structure 🧬

.
├── package.json
├── pnpm-lock.yaml
└── src
    ├── application.js
    ├── controllers
    │   ├── ApiController.js
    │   └── HelloController.js
    ├── endpoints
    │   └── hello
    │       └── helloWorld.js
    └── index.js

4 directories, 7 files

Setup 🔨

Initialize the project

Go ahead and create a new project folder and initialize it with a package.json using your package manager of choice. I've been experimenting with pnpm lately so the commands shown will be using that:

mkdir express-template && cd express-template
pnpm init -y

There are very few dependencies we need, so let's go ahead and install the following:

pnpm add express cors
pnpm add --save-dev nodemon

Now, let's add two scripts to run our application:

"scripts": {
  "dev": "nodemon ./src/index.js",
  "start": "node ./src/index.js"
},

Nodemon allows us restart the server automatically whenever
we make changes to our codebase.

Before we write some code, let's add some of the folder structure to the project:

mkdir src
mkdir src/controllers
mkdir src/endpoints
mkdir src/endpoints/hello

Create the application class

I typically like to wrap my express application in a class that manages the server and database connection. While we won't be connecting a database in this template, we will create an empty function that would contain the connection logic.

create src/application.js and src/index.js and add the following:

// application.js
const express = require("express");
const cors = require("cors");

class Application {
  expressApp;

  async connect() {
    // your database connection code would go here
  }

  init() {
    this.expressApp = express();

    this.expressApp.use(express.json());
    this.expressApp.use(express.urlencoded({ extended: true }));

    const corsOptions = {
      // this allows from all origins, you probably want to restrict this
      origin: "*", // FIXME: change me to fit your configuration
    };

    this.expressApp.use(cors(corsOptions));

    this.expressApp.get("/hello", (_, res) => res.send("Hello World!"));
  }

  start() {
    const PORT = process.env.PORT || 5000;

    this.expressApp.listen(PORT, () => {
      console.log(`Server listening at http://localhost:${PORT}`);
    });
  }
}

module.exports = Application;

// index.js
const Application = require('./application');

async function main() {
  const application = new Application();
  await application.connect();
  application.init();
  application.start();
}

main();

To see that everything is working as expected, go to http://localhost:5000/hello in your browser and you should see 'Hello World' display on your screen.

Create an endpoint function

I like to organize my endpoints in the endpoints folder, nested in a subfolder that matches the controller it belongs to. For this simple application, we will just have a hello folder for the HelloController we will create in the next step.

Let's create a function to send a simple text response:

src/endpoints/hello/helloWorld.js

const helloWorld = async (_req, res) => {
  res.send("Hello World!");
};

module.exports = helloWorld;

Now that we have a simple endpoint function, let's create our controllers to hook this up to our app.

Create the controllers

I usually have one parent controller I call the ApiController, which is then broken up into more controllers. To demonstrate this, create the following files:

src/controllers/ApiController.js

const { Router } = require("express");
const HelloController = require("./HelloController");

const ApiController = new Router();

ApiController.use("/hello", HelloController);

module.exports = ApiController;

This will pass all requests with the /hello prefix to the HelloController.

src/controllers/HelloController.js

const { Router } = require("express");
const helloWorld = require("../endpoints/hello/helloWorld");

const HelloController = new Router();

HelloController.get("/", helloWorld);

module.exports = HelloController;

When a GET request to /hello is made, our helloWorld function will now get run.

Wrapping it all up

To finalize everything, we need to actually use our ApiController in the Application class. We can now replace the inline GET request definition with our controller:

//     this.expressApp.get("/hello", (_, res) => res.send("Hello World!"));

this.expressApp.use("/api", ApiController);

And with that, we're done! You now have a very small, minimal template for getting started with REST APIs using Express. If you go to http://localhost:5000/api/hello in your browser, you should see the 'Hello World!' message.

Let me know if this was helpful or if you have any notes (I love notes - it's how we all get better!)

GraphQL Subscriptions and MikroOrm in 2021

Aaron Leopold — Thu, 14 Oct 2021 20:57:24 +0000

👋 Hello, welcome to my first post! If you're here because you have been trying to get subscriptions working with express and GraphQL, you can go ahead and wipe the tears out of your eyes!

Okay but seriously, if you've fallen down the rabbit hole of Apollo docs pointing you towards one library (subscription-transport-ws) which then points you to another (graphql-ws) , and so on and so forth, then hopefully this helps pull you out.

Overview ✨

At the end of this, you will have a GraphQL server, capable of subscriptions, that uses Mikro-Orm for managing your database.

Buckle in, this will be a long one!

Project Structure 🧬

graphql-mikro-subscriptions
├── db.sqlite
├── package.json
├── src
│   ├── application.ts
│   ├── assets
│   │   └── playground.html
│   ├── entities
│   │   ├── base.entity.ts
│   │   └── message.entity.ts
│   ├── enums
│   │   └── SubscriptionEvent.ts
│   ├── index.ts
│   ├── interfaces
│   │   └── ReqContext.ts
│   └── resolvers
│       └── message.resolver.ts
├── tsconfig.json
└── yarn.lock

6 directories, 12 files

I'll be walking you through how I set up the project, but in case you're antsy 👉 the GitHub link

Setup 🔨

I'll be breaking the setup into multiple steps. Please keep in mind that throughout this tutorial I will be making assumptions about your knowledge. I am assuming you already know the basics of GraphQL, understand express and cors, have familiarity with ORMs in general, know your way around a terminal, etc. If you don't, that's totally okay! I would just suggest you spend some time reading through docs before making your way back here 🙂

Step 1: Initialize the project

Go ahead and create a new project folder and initialize it with a package.json.

mkdir graphql-mikro-subscriptions
cd graphql-mikro-subscriptions && yarn init -y

You'll want to then generate a tsconfig.json

npx tsc --init

This will generate a basic tsconfig with comments for all the available fields. I have pasted my tsconfig below for simplicity:

{
  "compilerOptions": {
    "target": "es2018",
    "module": "commonjs",
    "lib": ["dom", "es6", "es2018", "esnext.asynciterable"],
    "outDir": "./dist",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "allowJs": true,
    "skipLibCheck": true,
    "allowSyntheticDefaultImports": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "isolatedModules": true,
    "sourceMap": true,
    "removeComments": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "noImplicitThis": true
  },
  "exclude": ["node_modules"]
}

At this point, we can go ahead and install all the dependencies we will need for the project. I'll explain a few of these afterwards. Let's start with the normal dependencies:

yarn add @mikro-orm/core @mikro-orm/sqlite @mikro-orm/sql-highlighter apollo-server-express class-validator cors express express-graphql graphql graphql-ws ts-node type-graphql ws

The main thing to point out here is that I am installing the sqlite mikro-orm package. Typically I use postgres, however for the sake of simplicity this project will use sqlite.

Now let's install some devDependencies:

yarn add --dev @types/express @types/node ts-node-dev typescript @types/ws

With the dependencies installed, let's add a quick script to our scripts field in the package.json

"scripts": {
    "dev": "ts-node-dev ./src/index.ts"
  },

Okay, with all that out of the way we can actually write some code - almost. Here's where I put a small disclaimer: the project structure I create is just my preferred structure for an express app. If you don't like it this way, change it! The most important pieces for getting the server running will be in the application.ts file we will create - so take the logic and rearrange it however you're most comfortable.

Step 2: Setup the express server

Make some subdirectories and files to be on our way to start coding!

mkdir src
mkdir src/entities
mkdir src/resolvers
mkdir src/enums
mkdir src/interfaces
mkdir src/assets

touch src/index.ts
touch src/application.ts

# we will talk about this one later
touch src/assets/playground.html

`index.ts`

This will be the entry point to the application. Add the following to index.ts:

import Application from './application';
import 'reflect-metadata';

export const PRODUCTION = process.env.NODE_ENV === 'production';

export let application: Application;

async function main() {
  application = new Application();
  await application.connect();
  // await application.seedDb();
  await application.init();
}

main();

Quick explainer: I have an async function to bootstrap everything. Internally, this will instantiate an Application object, which will handle connecting to the database with Mikro-Orm and then starting up the server. GraphQL depends on the import of reflect-metadata, so I typically do it here at the root.

This will throw some errors since we haven't implemented the import from application.ts, so let's go ahead and do that next.

`application.ts`

I usually opt to wrap my express app in a class. Add the following to application.ts

import express from 'express';
import { createServer, Server } from 'http';
import cors from 'cors';
import { Connection, IDatabaseDriver, MikroORM } from '@mikro-orm/core';

export default class Application {
  public orm!: MikroORM<IDatabaseDriver<Connection>>;
  public expressApp!: express.Application;
  public httpServer!: Server;

  public async connect() {
    // TODO: connect with mikro-orm
  }

  public async seedDb() {
    // TODO: populate database with test data
  }

  public async init() {
    this.expressApp = express();
    this.httpServer = createServer(this.expressApp);

    const corsOptions = {
      origin: '*', // FIXME: change me to fit your configuration
    };

    this.expressApp.use(cors(corsOptions));

    this.expressApp.get('/', (_req, res) => res.send('Hello, World!'));

    const port = process.env.PORT || 5000;
    this.httpServer.listen(port, () =>
      console.log(`httpServer listening at http://localhost:${port}`)
    );
  }
}

To test what we have so far go ahead and run the script you added to the package.json:

yarn dev

This will compile and run the code, and watch for changes. Think of it like nodemon. Go to your browser and load up localhost:5000 and you should now see this:

🎉 We are now one step closer!

Step 3: Configure Mikro-Orm

Remember for this guide we are using sqlite, refer to the official documentation to see instructions for connecting to varying drivers. (P.S. it's one of the best docs I have read through).

Entities

To start, let's create our first entities:

touch src/entities/base.entity.ts
touch src/entities/message.entity.ts

I'll briefly explain the decorators after we create these two entities. Let's start with base.entity.ts, add the following:

import { PrimaryKey, Property } from '@mikro-orm/core';

export default abstract class BaseEntity {
  @PrimaryKey()
  id!: number;

  @Property()
  createdAt = new Date();

  @Property({ onUpdate: () => new Date() })
  updatedAt = new Date();
}

Mini discussion: notice this is an abstract class! The contents of the BaseEntity class you just created could just be dropped into each entity we create, however now we can just have other entity classes extend this one, reducing the repeating code we write. In this regard, base.entity.ts is really optional.

Now, let's add the following to message.entity.ts:

import { Entity, Property } from '@mikro-orm/core';
import BaseEntity from './base.entity';

// the comments are optional and are just for organization :)
@Entity()
export default class Message extends BaseEntity {
  //====== PROPERTIES ======//
  @Property()
  from!: string;

  @Property()
  content!: string;
  //====== RELATIONS ======//
  //====== METHODS ======//
  //====== GETTERS ======//
  //====== MUTATORS ======//
  //====== CONSTRUCTORS ======//
  constructor(from: string, content: string) {
    // call the constructor for BaseEntity
    super();

    // assign the properties
    this.from = from;
    this.content = content;
  }
}

Okay let's discuss. For a more in-depth overview of the decorators, see the documentation. The @Entity() decorator marks the class as being an entity. The @PrimaryKey() decorator identifies the property as being the primary key for this entity. The @Property() decorator defines a property for the entity, which can be thought of as analogous to a database column (in SQL).

You'll notice I passed in additional arguments to the @Property() decorator in the BaseEntity.updatedAt property. This will trigger each time the entity is updated.

For the Message entity constructor, things are a little more straight forward. I assign the properties the values passed to the constructor as you would any other class constructor.

Configure the orm

Now that we have a manageable entity, let's configure the orm in application.ts. Add the following to application.ts:

// Add these imports
import { PRODUCTION } from '.';
import { SqlHighlighter } from '@mikro-orm/sql-highlighter';
import Message from './entities/message.entity';

// Add the following body to the connect method
public async connect() {
  try {
    this.orm = await MikroORM.init({
      entities: [Message],
      type: 'sqlite',
      dbName: 'db',
      debug: !PRODUCTION,
      highlighter: !PRODUCTION ? new SqlHighlighter() : undefined,
    });
  } catch (error) {
    console.error('📌 Could not connect to the database', error);
  }
}

Running the application again, you should see something like this:

Seed the database

Let's create a really small seed function to test that everything is working properly. Add the following to application.ts:

// Add the following body to the seedDb method
public async seedDb() {
  const generator = this.orm.getSchemaGenerator();

  await generator.dropSchema(); // drops all the tables
  await generator.createSchema(); // creates all the tables

  const testMessage = new Message('Aaron', 'Hello, World!');

  await this.orm.em
    .persistAndFlush(testMessage)
    .then(() => console.log('💪 message persisted to database'))
    .catch((err) => console.log('😱 something went wrong!:', err));
}

Save your changes, or rerun the app and you should now see this:

Inspecting the sqlite file with a sqlite database browser, you can see that it worked!

Step 4: Adding GraphQL

Now that we have the express server running and the orm configured, let's set up the GraphQL layer.

Making our entities accessible for GraphQL

In order for GraphQL to generate the schema from our entities, we need to annotate our entity classes with additional decorators from type-graphql. As with the Mikro decorators, I won't go too in-depth in my explanations. Review the type-graphql documentation for a better understanding of what's going on.

In general, for this application we will only need to use ObjectType() and Field decorators from type-graphql. Wherever we have @Entity(), we will be adding @ObjectType(), and wherever we have Property(), we will be adding Field() (unless we didn't want GraphQL to be able to query on certain entity properties, e.g. password hashes). These will automagically create the type-definitions for us.

Since BaseEntity is an abstract class, base.entity.ts should now look like this:

import { PrimaryKey, Property } from '@mikro-orm/core';
import { Field, ID, ObjectType } from 'type-graphql';

@ObjectType({ isAbstract: true })
export default abstract class BaseEntity {
  @Field(() => ID)
  @PrimaryKey()
  id!: number;

  @Field(() => Date)
  @Property()
  createdAt = new Date();

  @Field(() => Date)
  @Property({ onUpdate: () => new Date() })
  updatedAt = new Date();
}

Similarly, message.entity.ts should now look like this:

import { Entity, Property } from '@mikro-orm/core';
import { Field, ObjectType } from 'type-graphql';
import BaseEntity from './base.entity';

@ObjectType()
@Entity()
export default class Message extends BaseEntity {
  //====== PROPERTIES ======//
  @Field()
  @Property()
  from!: string;

  @Field()
  @Property()
  content!: string;
  //====== RELATIONS ======//
  //====== METHODS ======//
  //====== GETTERS ======//
  //====== MUTATORS ======//
  //====== CONSTRUCTORS ======//
  constructor(from: string, content: string) {
    // call the constructor for BaseEntity
    super();

    // assign the properties
    this.from = from;
    this.content = content;
  }
}

GraphQL Resolvers

Now that our entities are GraphQL friendly, let's create a resolver for our Message entity.

touch src/resolvers/message.resolver.ts

Add the following to message.resolver.ts:

import { Resolver, Query } from 'type-graphql';
import { application } from '..';
import Message from '../entities/message.entity';

@Resolver()
export class MessageResolver {
  @Query(() => [Message])
  async getMessages(): Promise<Message[]> {
    return application.orm.em.find(Message, {});
  }
}

The @Resolver() decorator let's GraphQL know that this is a resolver, and, likewise, the @Query() decorator let's it know that the method is a query. Later, we'll add a mutation and subscription.

Run the Apollo Server

Now that we have the entities GraphQL friendly and we have a nice little resolver, we can generate the GraphQL schema needed for the apollo server.

Add the following to application.ts

// new imports
import { buildSchema } from 'type-graphql';
import { MessageResolver } from './resolvers/message.resolver';
import { ApolloServer } from 'apollo-server-express';

// add a new class property
public apolloServer!: ApolloServer;

// the init method should now look like this
public async init() {
  this.expressApp = express();
  this.httpServer = createServer(this.expressApp);

  const corsOptions = {
    origin: '*', // FIXME: change me to fit your configuration
  };

  this.expressApp.use(cors(corsOptions));

  this.expressApp.get('/', (_req, res) => res.send('Hello, World!'));

  // generate the graphql schema
  const schema = await buildSchema({
    resolvers: [MessageResolver],
  });

  // initalize the apollo server, passing in the schema and then
  // defining the context each query/mutation will have access to
  this.apolloServer = new ApolloServer({
    schema,
    context: ({ req, res }) => ({
      req,
      res,
      // I am injecting the entity manager into my context. This will let me
      // use it directly by extracting it from the context of my queries/mutations.
      em: this.orm.em.fork(),
    }),
  });

  // you need to start the server BEFORE applying middleware
  await this.apolloServer.start();
  // pass the express app and the cors config to the middleware
  this.apolloServer.applyMiddleware({
    app: this.expressApp,
    cors: corsOptions,
  });

  const port = process.env.PORT || 5000;
  this.httpServer.listen(port, () =>
    console.log(`httpServer listening at http://localhost:${port}`)
  );
}

Now when you start the app and go to localhost:5000/graphql you should see the GraphQL playground. Run the following query:

query {
  getMessages {
    id
    from
    content
  }
}

🎉 And now GraphQL is added! We are really close to the end (I swear 😭)

Step 5: GraphQL Subscriptions

Adding the websocket server

We use graphql-ws here to add a websocket server to handle our subscriptions. Add the following to your application.ts:

// new imports
import ws from 'ws';
import {useServer} from 'graphql-ws/lib/use/ws';

// add a new class property
public subscriptionServer!: ws.Server;

// the body of the init method should now look like this
public async init() {
  this.expressApp = express();
  this.httpServer = createServer(this.expressApp);

  const corsOptions = {
    origin: '*', // FIXME: change me to fit your configuration
  };

  this.expressApp.use(cors(corsOptions));

  this.expressApp.get('/', (_req, res) => res.send('Hello, World!'));

  // generate the graphql schema
  const schema = await buildSchema({
    resolvers: [MessageResolver],
  });

  // initialize the ws server to handle subscriptions
  this.subscriptionServer = new ws.Server({
    server: this.httpServer,
    path: '/graphql',
  });

  // initalize the apollo server, passing in the schema and then
  // defining the context each query/mutation will have access to
  this.apolloServer = new ApolloServer({
    schema,
    context: ({ req, res }) => ({
      req,
      res,
      // I am injecting the entity manager into my context. This will let me
      // use it directly by extracting it from the context of my queries/mutations.
      em: this.orm.em.fork(),
    }),
    plugins: [
      // we need to use a callback here since the subscriptionServer is scoped
      // to the class and would not exist otherwise in the plugin definition
      (subscriptionServer = this.subscriptionServer) => {
        return {
          async serverWillStart() {
            return {
              async drainServer() {
                subscriptionServer.close();
              },
            };
          },
        };
      },
    ],
  });

  // you need to start the server BEFORE applying middleware
  await this.apolloServer.start();
  // pass the express app and the cors config to the middleware
  this.apolloServer.applyMiddleware({
    app: this.expressApp,
    cors: corsOptions,
  });

  const port = process.env.PORT || 5000;
  this.httpServer.listen(port, () => {
    // pass in the schema and then the subscription server
    useServer({ schema }, this.subscriptionServer);
    console.log(`httpServer listening at http://localhost:${port}`);
  });
}

Set up the new playground

One caveat of subscriptions this way is that GraphQL's playground does not use graphql-ws and so therefore does not work. Thankfully, there is a work around. Copy the contents of this html file to the src/assets/playground.html file we created. Be sure to also change the port in the html file:

// around line 60
const wsClient = graphqlWs.createClient({
  url: 'ws://localhost:5000/graphql',
  lazy: false, // connect as soon as the page opens
});

Then add the following to application.ts:

// new import
import path from 'path'

// add this line to the init method below the test get request
this.expressApp.get('/graphql', (_req, res) => {
      res.sendFile(path.join(__dirname, './assets/playground.html'));
    });

Adding the new line will override apollo's configuration for the /graphql path, so be sure to add it before the apollo server is created.

Now, when you go to localhost:500/graphql and run the same query you should see this:

PubSub Engine

If you're from Florida, no this is not the famous pubsub (although I have been missing those badly)! Tldr; it's a publish/subscribe engine.

For simplicity, we are going to use the default PubSub engine that comes bundled with graphql-subscriptions, however there are other implementations you can use.

Add the following updates to the init method in application.ts:

// create the PubSub (not the sandwich 😩)
const pubSub = new PubSub();

// generate the graphql schema
const schema = await buildSchema({
  resolvers: [MessageResolver],
  pubSub,
});

Creating a subscription

We're close! Before we go back to message.resolver.ts. There are three important things we need to quickly address:

If you look back at the apollo server we created, you'll see we injected the entity manager. Using the @Ctx() decorator, we can now access the entity manager from context rather than importing the application.
To access the PubSub we passed to buildSchema, we can use the @PubSub() decorator. We can then issue publish events!
To access the payloads from publish events, we can use the Root() decorator.

We'll have to type our context in order to access it, so let's create the interface for that:

touch src/interfaces/ReqContext.ts

Add the following to ReqContext.ts

import { Request, Response } from 'express';
import { EntityManager } from '@mikro-orm/sqlite';

export default interface ReqContext {
  req: Request;
  res: Response;
  em: EntityManager;
}

We'll also need to define our subscription events. I typically use an enum for this, with multiple values, so even though there is only one subscription type I'm going to keep that format.

touch src/enums/SubscriptionEvent.ts

And add the following to SubscriptionEvent.ts:

enum SubscriptionEvent {
  NEW_MESSAGE = 'NEW_MESSAGE',
}

export default SubscriptionEvent;

Now we can go to message.resolver.ts and make it look like this:

import { PubSubEngine } from 'graphql-subscriptions';
import {
  Resolver,
  Query,
  Mutation,
  Ctx,
  Subscription,
  Root,
  PubSub,
} from 'type-graphql';
import Message from '../entities/message.entity';
import SubscriptionEvent from '../enums/SubscriptionEvent';
import ReqContext from '../interfaces/ReqContext';

@Resolver()
export class MessageResolver {
  @Query(() => [Message])
  async getMessages(@Ctx() ctx: ReqContext): Promise<Message[]> {
    return ctx.em.find(Message, {});
  }

  @Mutation(() => Message)
  async createMessage(
    @Ctx() ctx: ReqContext,
    @PubSub() pubSub: PubSubEngine
  ): Promise<Message> {
    // grab the entity manager from context
    const { em } = ctx;

    const message = new Message('GraphQL', 'Hello, Aaron!');

    // persist the new message to the database
    await em.persistAndFlush(message);

    // publish the message
    await pubSub.publish(SubscriptionEvent.NEW_MESSAGE, message);

    // return the message
    return message;
  }

  @Subscription(() => Message, { topics: SubscriptionEvent.NEW_MESSAGE })
  async createdMessage(@Root() payload: Message) {
    return payload;
  }
}

Now let's go to localhost:500/graphql and run that same query just to make sure everything is good and you should see....

An error?? Yep. I know I know, not to be that person who intentionally leaves out a key step, but I thought this was important. We provided context for our apollo server, but we didn't do that with our websocket server. Here's the quick fix!

At the end of the init method in application.ts, change the last few lines to this:

this.httpServer.listen(port, () => {
  // pass in the schema and then the subscription server
  useServer(
    { schema, context: { em: this.orm.em.fork() } },
    this.subscriptionServer
  );
  console.log(`httpServer listening at http://localhost:${port}`);
});

Now, retry that query!

Alriiiight! Now let's see what happens we try the new subscription! You'll want to run the subscription in one tab, then run the mutation in a new tab, and then check back to the tab with the subscription:

Tada! We're done! 🎉

Thanks for bearing with me! Let me know if this was helpful or if you have any notes (I love notes!)

Again, here is the GitHub link for everything we just did.