Overview

Starter project for backend development of Graphql APIs hooked into Typeorm and embedded Postgraphile infrastructure.

Alternatives: Graphql API with typescript via Prisma OR GraphQL API with typescript via TypeGraphQL

Features:

• Provides great development experience similar to Prisma, including code generation of query bindings, Graphql API schema, etc..
• Does not require separate running proxy process, like Prisma or Postrgaphile server. All GraphQL queries are wired directly to the connection with the database.
• Server is powered by Apollo Server 2.0
• Flexible and powerful schema definitions by Typeorm decorators
• Fine control for database migrations using Typeorm features, including:
  • Automated generation of migration queries based on introspection of source code models and state of the database
  • Run of the migrations on application's launch or manually via command line
  • Revert of the migrations via command line
• Separate configurations and scripts for development, stage and production environment
• Typescript and TSLint enabled
• Build script creates distributable folder without dependencies to local node_modules folder
• GraphQL playground server for experimenting with application's GraphQL API and with Postgraphile's GraphQL API
• Implement resolvers using Typeorm queries or wire to embedded Postgraphile binding queries.

Getting started

1. Run yarn install
2. Edit config.dev.json database connection settings (uses Typeorm connection configuration options)
3. Launch everything in development watch mode: yarn start - it will run the initial database setup (the first database schema migrations script) and will start development environment. Check terminal output for served endpoints and ports.
4. Play with example queries saved in examples.graphql file
5. Build everthing into self contained distributable folder: yarn build

Schema migration workflow

1. Edit src/entity/** files to match your data model. It uses Typeorm to define the database model.
2. Run yarn migrations:generate, review and modify if necessary the generated migration script. In most cases you do not need to modify it, Typeorm does nice job generating migration scripts.
3. Run yarn migrations:run or just start the application's server to deploy the migrations
4. Run yarn postgraphile:generate to generate postgraphile bindings and internal GraphQL schema for querying the database with the latest schema (code generation steps are explained here)
5. Wire Application's GraphQL API calls to Postgraphile API calls as it is required by your business logic: see src/resolvers/** scripts for example.

Commands

• yarn start starts GraphQL server in watch mode and Playground server
• yarn watch starts GraphQL server in watch mode
• yarn build builds self contained distributable folder with production build
• yarn playground opens the GraphQL Playground for the projects from .graphqlconfig.yml
• yarn postgraphile:serve runs Postgraphile server targeting development database. It is only for development and usage in playground. Postgraphile server is not required in production.
• yarn migrations:generate generates database schema migration queries
• yarn migrations:run, yarn migrations:run:stage and yarn migrations:run:prod deployes all pending schema migrations targeting development, stage and production databases accordingly
• yarn migrations:revert deployes all pending schema migrations

Check other commands in the package.json file. They are all self explanatory.

Project structure

File name	Description
config.*.json	Datebase connection settings for dev, stage and production environments
scripts/**	Build and code generation scripts invoked by npm/yarn commands
src/entity/**	Definition of the database model
src/migrations/**	Generated or manually prepared database schema migrations scripts
src/generated/**	Code automatically generated for quering the database via Postgraphile rendered queries
src/resolvers/**	Implementation of your application's GraphQL API resolvers
└──Mutation/auth.ts	Example of implementing GraphQL resolvers using Typeorm queries
└──Mutation/post.ts	Example of implementing GraphQL resolvers using transparent proxing to Postgraphile queries resolver
docker-compose.yaml	Config for launching Postgres database locally via docker-compose up -d

Subscription to database changes

This feature is intentionally not added to the starter project for few reasons:

1. Subscriptions, based on Postgraphile or Typeorm subscriptions, do not scale beyong a single process. If you still prefer this there are many examples and blogs how Typeorm subscriptions can be wired to GraphQL subscription endpoint. Postgraphile also has got subscriptions support via additional plugin. As Postgraphile or Typeorm notifications are not caused by the database itself, you will need to wire both libraries for notifications or pick only one for invoking database mutations.
2. Better subscriptions are based on Postgres triggers raising notifications on row updates. This will scale better but require selective choice of what triggers to place. If you prefer this approach: create new database migration script which will add Postgres notification TRIGGER on create/update/delete AND subscribe to these notification using plaing pg driver.
3. Even better use some message queue, like Kafka for resilient, scalable, distributed notifications. But this goes beyond of this project boilerplate.

Enjoy!

License

MIT License

Copyright (c) 2018 Andrey Konstantinov & Contributors