Links

getting-started-with-apollo-server-dataloader-knex.mo

Owner: Thomas Pucci

Prerequisites (~12min)

  • Have Yarn installed (~5min)
  • Have Docker and Docker-compose installed (~5min)
  • Have Postman installed (~2min)

Thanks

Thanks to Tycho Tatitscheff and Yann Leflour for helping me with their great BAM API repo

Context

During this standard, we will create a Heroes graphQL API. We will have a Hero model with superheroes real and hero names. We will add one example of association.
Our API will be lightly protected and use batching to minimise DB round-trips.

Steps (~61min)

Note: You should commit between each step.

Initialise a new project (~6min)

  • Create and go to a new directory for the project: mkdir graphql_formation && cd graphql_formation
  • Init a git repository: git init
  • Create two services with Docker-compose, one postgres database and one node server:
    • For this step, notice that our final folder architecture looks like this:
      📂 graphql_formation
      ├ 📂 api
      │ └ 🗋 Dockerfile
      ├ 📂 db
      │ └ 🗋 Dockerfile
      ├ 🗋 config.env
      └ 🗋 docker-compose.yml
    • Make sure your local 3000 port is available as we will use this port to reach our API
    • In a new api/Dockerfile file, write all the commands to assemble the API image:
    FROM node:8.1.0-alpine
    WORKDIR /usr/src/api
    EXPOSE 3000
    CMD ["yarn", "run", "serve"]
    • In a new db/Dockerfile file, write all the commands to assemble the db image:
    FROM postgres:9.6.3
    • In a new docker-compose.yml file, declare the two services:
    version: '3'
    services:
    api:
    build:
    context: ./api
    image: heroes-api
    env_file: config.env
    volumes:
    - ./api:/usr/src/api
    ports:
    - 3000:3000
    links:
    - db:db
    db:
    build:
    context: ./db
    env_file: config.env
    image: heroes-db
    ports:
    - 5431:5432
    • In a new config.env file, declare your environnement variable for these Docker containers:
    POSTGRES_USER=heroesuser
    POSTGRES_PASSWORD=heroespassword
    POSTGRES_DB=heroesdb
    PGDATA=/data
    DB_HOST=db
  • Build these services with the command: docker-compose build
CHECK 1: Your terminal should prompt successively these lines confirming Docker images have been built:
Successfully tagged heroes-db:latest
Successfully tagged heroes-api:latest

Install nodemon and run our project (~5min)

  • Add this to the project .gitignore: echo "node_modules" > .gitignore
  • In the api folder, interactively create a api/package.json file: cd api && yarn init
  • Add nodemon, babel-cli, babel-plugin-transform-class-properties, babel-preset-flow and babel-preset-es2015 to our dev dependencies: yarn add nodemon babel-cli babel-plugin-transform-class-properties babel-preset-es2015 babel-preset-flow -D
  • In a new api/.babelrc file, write the babel configuration:
    {
    "presets":[
    "es2015",
    "flow"
    ],
    "plugins":[
    "transform-class-properties"
    ]
    }
  • In our api/package.json, write the command to launch the server:
    "scripts": {
    "serve": "nodemon index.js --exec babel-node"
    }
  • Create a new empty file api/index.js
  • Go back to the root of the project: cd ..
  • Run the project: docker-compose up
CHECK 1: You terminal should prompt the logs of the two containers together with two different colors
CHECK 2: From another terminal, you can access the API and see the following folder structure: docker-compose exec api /bin/sh then inside the container: ls -lath;
drwxrwxr-x 3 node node 4.0K Aug 17 12:37 .
-rw-rw-r-- 1 node node 0 Aug 17 12:37 index.js
drwxrwxr-x 222 node node 12.0K Aug 17 12:37 node_modules
-rw-rw-r-- 1 node node 426 Aug 17 12:37 package.json
-rw-rw-r-- 1 node node 66.2K Aug 17 12:37 yarn.lock
-rw-rw-r-- 1 node node 86 Aug 17 12:32 Dockerfile
drwxr-xr-x 3 root root 4.0K Aug 3 11:50 ..
Exit with: CTRL-D
CHECK 3: You can access the db and prompt the PostgreSQL version: docker-compose exec db psql -U heroesuser -d heroesdb then inside the container: select version();
PostgreSQL 9.6.3 on x86_64-pc-linux-gnu, compiled by gcc (Debian 4.9.2-10) 4.9.2, 64-bit
Exit with: CTRL-D

Create a koa server (~3min)

  • Install koa and koa-router in our API: cd api && yarn add koa koa-router
  • In the index.js file, create our server:
import Koa from 'koa';
import koaRouter from 'koa-router';
const app = new Koa();
const router = new koaRouter();
router.get('/', ctx => {
ctx.body = 'Hello World!';
});
app.use(router.routes());
app.use(router.allowedMethods());
app.listen(3000);
console.log('Server is up and running');
CHECK 1: In your terminal which run docker-compose, you should see Server is up and running
CHECK 2: Hitting localhost:3000 should return Hello World!: curl localhost:3000

Create a presentation layer with graphQL (~6min)

This layer will let our API know how to present data: what data one user can query? How should front end query this data (fields, root queries, sub queries...)?
  • Install graphQL, graphQL Server Koa, graphQL tools and Koa body-parser: yarn add graphql graphql-server-koa graphql-tools koa-bodyparser
  • In a new folder api/presentation add a new schema.js file describing a simple graphQL schema:
import { makeExecutableSchema } from 'graphql-tools';
const typeDefs = [`
type Hero {
id: Int!
firstName: String
lastName: String
}
type Query {
heroes: [Hero]
}
schema {
query: Query
}
`];
const resolvers = {
Query: {
heroes: () => ([
{
id: 1,
firstName: 'Clark',
lastName: 'Kent',
},
{
id: 2,
firstName: 'Bruce',
lastName: 'Wayne',
}
]),
},
}
const schema = makeExecutableSchema({ typeDefs, resolvers });
export default schema;
  • In the api/index.js file, add our api endpoint:
import koaBody from 'koa-bodyparser';
import { graphqlKoa } from 'graphql-server-koa';
import schema from './presentation/schema';
...
router.post(
'/api',
graphqlKoa(async ctx => {
return {
schema: schema,
context: {},
debug: true,
};
})
);
...
// Write the following line before all other app.use(...) calls:
app.use(koaBody());
CHECK 1: In Postman, making a POST request to localhost:3000/api which content-type is JSON(application/json) with the following raw body:
{
"query": "{heroes { firstName lastName }}"
}
...should return our two heroes, Clark and Bruce:
  • Install Koa graphiQL: yarn add koa-graphiql
  • In the index.js file, let our API knows it should use Koa-graphiql:
import graphiql from 'koa-graphiql';
...
// Write the following block after others router.verb(...) calls:
router.get('/graphiql', graphiql(async (ctx) => ({
url: '/api',
})));
CHECK 2: Hitting localhost:3000/graphiql should return graphiql interface and show the Docs
CHECK 3: Using graphiql interface with the following query:
{
heroes {
firstName
lastName
}
}
...should return our two heroes, Clark and Bruce:

Create a business layer (~5min)

This layer will contain all business logic: access controll, scoping / whitelisting, batching and caching and computed properties. More explanations can be found here, in the bam-api repo. In this MO, we will only cover access control logic and batching / caching.
  • In a new api/business folder add a new hero.js file describing our class for this business object:
const mockedHeroes = [
{
id: 1,
firstName: 'Clark',
lastName: 'Kent',
},
{
id: 2,
firstName: 'Bruce',
lastName: 'Wayne',
}
];
class Hero {
id: number;
firstName: string;
lastName: string;
constructor(data) {
this.id = data.id;
this.firstName = data.firstName;
this.lastName = data.lastName;
}
static async load(ctx, args) {
const data = mockedHeroes[args.id];
if (!data) return null;
return new Hero(data);
}
static async loadAll(ctx, args) {
const data = mockedHeroes;
return data.map(row => new Hero(row));
}
}
export default Hero;
  • In our previous presentation/schema.js file, modify our mocked resolvers to use our business layer:
+import Hero from '../business/hero';
type Query {
heroes: [Hero]
+ hero(id: Int!): Hero
}
const resolvers = {
Query: {
- heroes: () => ([
- {
- firstName: 'Clark',
- lastName: 'Kent',
- },
- {
- firstName: 'Bruce',
- lastName: 'Wayne',
- }
- ]),
+ heroes: async (_, args, ctx) => Hero.loadAll(ctx, args),
+ hero: async (_, args, ctx) => Hero.load(ctx, args),
}
}
CHECK 1: Using graphiql interface with the following query:
{
heroes {
id
firstName
lastName
}
}
...should return our two heroes, Clark and Bruce.
CHECK 2: Using graphiql interface with the following query:
{
hero(id:0) {
id
firstName
lastName
}
}
...should return Clark Kent with its id: 1.
CHECK 3: Using graphiql interface with the following query:
{
hero(id:1) {
id
firstName
lastName
}
}
...should return Bruce Wayne with its id: 2.

Seed our database (~8min)

  • Install knex and pg at the root of the project: cd .. && yarn add knex pg
  • At the root of our project, add a knexfile.js file:
module.exports = {
development: {
client: 'pg',
connection: {
host: 'localhost',
port: 5431,
user: 'heroesuser',
password: 'heroespassword',
database: 'heroesdb',
},
migrations: {
directory: './api/db/migrations',
},
seeds: {
directory: './api/db/seeds',
},
},
};
  • Create a migration file: yarn knex migrate:make add_heroes_table and complete the new created file with this:
exports.up = function(knex, Promise) {
return knex.schema.createTableIfNotExists('Heroes', function(table) {
table.increments('id');
table.string('firstName');
table.string('lastName');
table.string('heroName');
});
};
exports.down = function(knex, Promise) {
return knex.schema.dropTableIfExists('Heroes');
};
  • Create a seed file: yarn knex seed:make heroes and complete the new created file with this:
exports.seed = function(knex, Promise) {
return knex('Heroes').del()
.then(function () {
return knex('Heroes').insert([
{id: 1, firstName: 'Clark', lastName: 'Kent', heroName: 'Superman'},
{id: 2, firstName: 'Bruce', lastName: 'Wayne', heroName: 'Batman'},
{id: 3, firstName: 'Peter', lastName: 'Parker', heroName: 'Spiderman'},
{id: 4, firstName: 'Susan', lastName: 'Storm-Richards', heroName: 'Invisible Woman'},
]);
});
};
  • Run the migration and the seed: yarn knex migrate:latest && yarn knex seed:run
CHECK 1: You can access the db and prompt content of the Heroes table: docker-compose exec db psql -U heroesuser -d heroesdb then inside the container: select * from "Heroes";;
id | firstName | lastName | heroName
----+-----------+----------------+-----------------
1 | Clark | Kent | Superman
2 | Bruce | Wayne | Batman
3 | Peter | Parker | Spiderman
4 | Susan | Storm-Richards | Invisible Woman
(4 rows)
Exit with: CTRL-D

Create a db layer with knex (~6min)

This layer let our API query the data using knex query builder.
  • Install knex and pg in our API: cd api && yarn add knex pg
  • In the api/db folder add a new index.js file:
import knex from 'knex';
export default knex({
client: 'pg',
connection: {
host: process.env.DB_HOST,
user: process.env.POSTGRES_USER,
password: process.env.POSTGRES_PASSWORD,
database: process.env.POSTGRES_DB,
},
debug: true,
});
  • In a new api/db/queryBuilders subfolder, create a new hero.js file and add these few methods to query our data:
// @flow
import db from '..';
class Hero {
static async getById(id: number) {
return db
.first()
.table('Heroes')
.where('id', id);
}
static async getByIds(ids: Array<number>) {
return db
.select()
.table('Heroes')
.whereIn('id', ids);
}
static async getAll() {
return db
.select()
.table('Heroes');
}
}
export default Hero;
  • Modify the api/db/queryBuilders/hero.js file in our business layer this way:
-const heroes = [
- {
- id: 0,
- firstName: 'Clark',
- lastName: 'Kent',
- },
- {
- id: 1,
- firstName: 'Bruce',
- lastName: 'Wayne',
- }
-];
+import HeroDB from '../db/queryBuilders/hero';
class Hero {
static async load(ctx, args) {
- const data = heroes[args.id];
+ const data = await HeroDB.getById(args.id);
if (!data) return null;
return new Hero(data);
}
static async loadAll({ authToken, dataLoaders }) {
- const data = heroes;
+ const data = await HeroDB.getAll();
return data.map(row => new Hero(row));
}
CHECK 1: Using graphiql interface with the following query:
{
hero(id:1) {
id
firstName
lastName
}
}
...should return Clark Kent with its id: 1.
CHECK 2: Using graphiql interface with the following query:
{
heroes {
id
firstName
lastName
}
}
...should return all 4 heroes of our database.

Add association to our API (~6min)

Association are made both in our db and in our API, in our presentation layer.
  • Create a new migration: cd .. && yarn knex migrate:make add_heroes_enemies
  • Complete the newly created migration file with this:
exports.up = function(knex, Promise) {
return knex.schema.table('Heroes', function(table) {
table.integer('enemyId').references('id').inTable('Heroes');
});
};
exports.down = function(knex, Promise) {
return knex.schema.table('Heroes', function(table) {
table.dropColumn('heroName');
});
};
  • Modify our api/db/seeds/heroes.js seeds:
exports.seed = function(knex, Promise) {
return knex('Heroes').del()
.then(function () {
return knex('Heroes').insert([
{id: 1, firstName: 'Clark', lastName: 'Kent', heroName: 'Superman', enemyId: 2},
{id: 2, firstName: 'Bruce', lastName: 'Wayne', heroName: 'Batman', enemyId: 1},
{id: 3, firstName: 'Peter', lastName: 'Parker', heroName: 'Spiderman'},
{id: 4, firstName: 'Susan', lastName: 'Storm-Richards', heroName: 'Invisible Woman'},
]);
});
};
  • Run these migrations: yarn knex migrate:latest && yarn knex seed:run
  • In our business layer, modify api/business/hero.js this way:
class Hero {
id: number;
firstName: string;
lastName: string;
+ heroName: string;
+ enemyId: number;
constructor(data) {
this.id = data.id;
this.firstName = data.firstName;
this.lastName = data.lastName;
+ this.heroName = data.heroName;
+ this.enemyId = data.enemyId;
}
  • In our API, in our presentation layer, modify our api/presentation/schema.js:
const typeDefs = [`
type Hero {
id: Int
firstName: String
lastName: String
+ heroName: String
+ enemy: Hero
}
...
`];
const resolvers = {
Query: {
...
},
+ Hero: {
+ enemy: async (hero, args, ctx) => Hero.load(ctx, {id: hero.enemyId}),
+ },
}
CHECK 1: Using graphiql interface with the following query:
{
hero(id:1) {
id
firstName
lastName
heroName
enemy {
heroName
}
}
}
...should return Clark Kent with its heroName and its enemy: Batman.

Push your API to the next level: use caching with Dataloader (~6min)

Trying to query heroes and their enemies'heroName will show up a N+1 problem. Indeed, our API make 5 round-trips to our database! Try yourself:
{
"query": "{heroes { id firstName lastName heroName enemy { heroName } }}"
}
We can reduce these calls adding caching to our business layer
  • Install Dataloader: cd api && yarn add dataloader
  • Add a getLoaders method to our api/business/hero.js file in our business layer:
import DataLoader from 'dataloader';
class Hero {
//...
static getLoaders() {
const getById = new DataLoader(ids => HeroDB.getByIds(ids));
const primeLoaders = (heroes) => {
heroes.forEach(hero =>
getById.clear(hero.id).prime(hero.id, hero))
;
};
return { getById, primeLoaders };
}
//...
}
  • In our api/index.js file, add a new dataloader to our context for each query on /api route:
+import Hero from './business/hero';
router.post(
'/api',
graphqlKoa(async ctx => {
return {
schema: schema,
+ context: {
+ dataLoaders: {
+ hero: Hero.getLoaders(),
+ }
+ },
debug: true,
};
})
);
  • Back in our api/business/hero.js business layer file, modify load and loadAll methods to use our dataloader:
static async load(ctx, args) {
+ const data = await ctx.dataLoaders.hero.getById.load(args.id);
if (!data) return null;
return new Hero(data);
}
static async loadAll(ctx, args) {
const data = await HeroDB.getAll();
+ ctx.dataLoaders.hero.primeLoaders(data);
return data.map(row => new Hero(row));
}
  • Protect loader.load() function call if no argument is supplied:
static async load(ctx, args) {
+ if (!args.id) return null;
const data = await ctx.dataLoaders.hero.getById.load(args.id);
if (!data) return null;
return new Hero(data);
}
CHECK 1: Using graphiql interface with the following query:
{
heroes {
id
firstName
lastName
heroName
enemy {
heroName
}
}
}
...should return all heroes and their enemies and your terminal should prompt only one request to the DB.
CHECK 2: Using graphiql interface with the following query:
{
h1: hero(id:1) {
id
firstName
lastName
heroName
enemy {
heroName
}
}
h2: hero(id:2) {
id
firstName
lastName
heroName
enemy {
heroName
}
}
}
...should return Clark Kent and Bruce Wayne; and only one SELECT call should have beeen made to our DB.

Add access control to our API (~5min)

This is a very simple example, for a more advanced solution, prefer using Koa Jwt.
  • In a new api/utils.js file, add these two methods to parse Authorization header and verify token:
export const parseAuthorizationHeader = (req) => {
const header = req.headers.authorization;
if (typeof header === 'undefined' || header === 'null') {
return null;
}
const [, scheme, token] = (/(\w+) ([\w.-]+)/g).exec(header);
return token;
};
// Not production-ready: this is a simple example for the tutorial
export const verifyToken = token => new Promise((resolve, reject) => {
if (token !== 'authorized') {
const error = new Error('UNAUTHORIZED');
error.code = 401;
reject(error);
}
resolve();
});
  • In our api/index.js file, parse authorization header and pass it to our context:
+import { parseAuthorizationHeader } from './utils';
router.post(
'/api',
graphqlKoa(async ctx => {
return {
schema: schema,
context: {
+ authToken: parseAuthorizationHeader(ctx.req),
dataLoaders: {
hero: Hero.getLoaders(),
}
},
debug: true,
};
})
);
  • In our business layer, modify api/business/hero.js:
+import { verifyToken } from '../utils';
static async load(ctx, args) {
+ await verifyToken(ctx.authToken);
static async loadAll(ctx, args) {
+ await verifyToken(ctx.authToken);
CHECK 1: In Postman, making a POST request to localhost:3000/api which content-type is JSON(application/json) with the following raw body:
{
"query": "{hero(id:1) { id firstName lastName heroName }}"
}
...should return UNAUTHORIZED.
CHECK 2: In Postman, making a POST request to localhost:3000/api which content-type is JSON(application/json) with the following raw body:
{
"query": "{heroes { id firstName lastName heroName }}"
}
...should return UNAUTHORIZED.
CHECK 3: In Postman, making a POST request to localhost:3000/api which content-type is JSON(application/json) and Authorization Header is Bearer authorized with the following raw body:
{
"query": "{hero(id:1) { firstName lastName }}"
}
...should return Clark Kent.

Troubleshooting: Accessing data by id in the correct order (~5min)

You should notice that in Postman making a POST request to localhost:3000/api which content-type is JSON(application/json) and Authorization Header is Bearer authorized with the following raw body:
{
"query": "{h1: hero(id:1) { id firstName lastName heroName enemy { heroName } } h2: hero(id:2) { id firstName lastName heroName enemy { heroName } }}"
}
...returns the same than the following request (ids switched):
{
"query": "{h1: hero(id:2) { id firstName lastName heroName enemy { heroName } } h2: hero(id:1) { id firstName lastName heroName enemy { heroName } }}"
}
This is due to our DB query: select * from "Heroes" where "id" in (1, 2) return the same result than: select * from "Heroes" where "id" in (2, 1).
  • In utils.js, add the following method:
export const orderByArgIdsOrder = ids => ("array_position(string_to_array(?, ',')::integer[], id)", ids.join(','));
  • In our db layer, modify api/db/queryBuilders/hero.js like this:
+import { orderByArgIdsOrder } from '../../utils';
class Hero {
static async getByIds(ids: Array<number>): Promise<Array<CostDBType>> {
return db
.select()
.table('Heroes')
+ .whereIn('id', ids)
+ .orderByRaw(orderByArgIdsOrder(ids));
}
CHECK 1: In Postman, making a POST request to localhost:3000/api which content-type is JSON(application/json) and Authorization Header is Bearer authorized with the following raw body:
{
"query": "{h1: hero(id:2) { heroName } h2: hero(id:1) { heroName }}""
}
...should return Batman (as h1) then Superman (as h2).

Next steps

  • Add Koa Jwt
  • Add graphiQL with authorization header (get inspired by BAM API)
Last modified 5yr ago