About

graphback db will create Postgres database with tables and relations from the model

A generalized way to handle changes in data on the server while client was offline without refetching all data after reconnect as well as transparently execute initial data loading without requiring user to have all data locally already for app to function.

I completely understand that this is not a client only feature but this library seemed to be the best place to start a discussion on how we would go about establishing a standardized way to achieve this capability (server to client data replication) when leveraging a graphql backend

Describe the solution you'd like

• Client side API that allows to specify which data should be delta synced from the server to the client and how in a non boilerplate manner
• Server side requirements to support delta sync
• Establish overridable conventions

Describe alternatives you've considered

• AWSAppSync
  • Its AWS only
  • No support for apollo >2.5 local state management and local resolvers
• Custom built on graphql
  • Well ... it would be custom building a central component of what a lot of folks need
• custom build on top of puchdb
  • requires couchdb compatible db on server vs graphql endpoint

Current template is missing tsconfig.json and hence has issues with typescript compilation. Plus resolvers are missing strong typings.

Currently, the generator allows specifying CRUD methods for all types globally.
It will be better to support CRUD methods per each type.

Description

How the cli works with templates

• graphback init --template-name=apollo-typescript --name=test
• cd test/model
• touch Types.grapqhl
• graphback generate(this generates resolvers and schema)
• start command for the template

https://github.com/aerogear/graphql-query-mapper

Background

Currently documentation is done using docsify. Docusaurus.io provides a lot of better features and current documentation has a lot of missing pieces.

Tasks

• refactor from docsify.js to docusaurus
• document missing pieces including cli workflow #64

Learn about typescript usage and strategies of software development.
Read various use cases from official typescript documentation and blogs/articles.

Create graphback command line client.
Initially init method should be supporte that will create empty project

Add support for querying relationships using resolvers.

Motivation

Note: This task is a more generic version of #63

Investigate modular architecture using reusable https://graphql-modules.com modules that provide extensions for Auth/Conflict/Binary etc.

For example for authentication, we can provide the following schema out of the box

type Query {
    me: User
}

type Mutation {
    login(): User
}

extend type User {
    username: String!
}

Then we can wrap schema together with custom resolvers and directives for auth.

Implementation

• Ask user if include model or not
• if yes ask for set of example models present in cmd or github
• bootstrap with example model in init

For generator we need to generate subscriptions:

• ItemCreated
• ItemDeleted
• ItemUpdated

For each type we specify in the model.
We need to add underlying subscription implementation -
We can use Redis for pubsub interface.

Current documentation got outdated and it is missing a lots of details.
Additionally, we should keep the changelog to make sure we track new things apart from commit information that may be more convoluted and not clear to get the context of the job.

The current template-based approach is really limited as it is constructed based on AST, but it will not support many different use cases like Fragments and buffers.

GraphQL compose will allow a more flexible approach and it even has support for plugins: https://graphql-compose.github.io
We should explore using GraphQL compose

We have multi step CLI and ability to run postgress container.
We should be running automated tests for CLI - init/build etc. to make sure that we do not break stuff and extend it over time.

Additionally this will help us to detect breaking changes.

ping @ankitjena

Background

Currently graphback-cli is pretty much strict about postgres as the only database. Database creation in graphback is done using knex which supports a bunch of relational databases.

graphback-cli has currently 3 main commands in it's workflow with other proposed commands yet to be finalized.

• Init creates the project with model and config
• generate generates schema and resolvers
• db creates and manages database resources

Discussion

Currently the moving parts which are dependent on database are the templates, resolver generation and database creation.

The user chooses from templates in the init command which are currently db specific(postgres).

• we can separate templates into different database specific ones, like apollo-typescript-starter to apollo-typescript-pg/apollo-typescript-mongo
• we can modify init command to inject db configs and docker-composes into templates with one skeleton.

The generate command generates schema and resolvers. The resolvers are currently implemented by a Knex resolver instance which generates resolvers which use knex. This is pluggable, so for it to support a no-SQL database like mongoDB would not be difficult.

#47 The db command will create db resources in local development server. Key point is to separate concerns regarding development and production.
Database to be created can be selected as we start to support different databases. But the concern of db command is to create local database.

• we can create a config file during init which store db config and accordingly create a docker-compose. But this will also have template as another moving piece which will be needed to configure.
• we should support addition of new tables, new columns(the current implemetaion of graphback needs to be a modified a bit) but dropping columns is to be debated.

Finally, we should create a graphback migrate command that will generate database definitions.

Points to note

• This is a development workflow. Dealing with production using graphback is to be ideated.

TODO

Provide option in init command to choose from database, and accordingly generate config for it. Current default config are postgres specific.

Tasks

• migrate to apollo-server from voyager-server. Templates using voyager server will have complex use cases.
• change current template from javascript to typescript
• describe template structure

GraphQL js template will be the same as apollo but using graphqljs instead.

There are couple of patterns that we can employ from here:
https://graphql-rules.com/

Let's have a discussion in this thread what patterns we can employ and we can apply them to the generated schema

Background

graphback version 0.3.1 creates database structure for relationships.

TODO

Add relationships in schema and resolvers
For a model

type Note {
    id: ID!
    title: String!
    comments: [Comment!]!
}

type Comment {
    id: ID!
    content: String!
}

we can create the schema with types like

type Note {
    id: ID!
    title: String!
    comments: [Comment]!
}

type Comment {
    id: ID!
    content: String!
    noteId: ID!
}

Not sure how to work with n:m relations for now
Resolvers can be implemented using either

• Dataloader
• Graphql-query-mapper

@wtrocki What should be the methods we should provide for relationships? like findXsOfY for example.

Goals

• Reformating resolvers from older pattern to use graphql-codegen version 1.0.0
• Matching resolvers to schema definition generated. Current implementation missing a lot of stuff.

Init should go thru templates and pick one. Then generate initial project structure. In this stucture, we need to have an example type.
We can reuse example type we have created for example app.

The project should have the ability to generate schema, resolvers and database for specific graphql type. Specifying plain type should generate crud based queries.

Features

• Fragments
• Filtering
• Pagination
• Single edits
• Relationship queries
• Selecting what elements from CRUD can be generated

Allow config to specify additional template sources (github etc.) to enable community templates that are customized towards user needs.

How this could work

User can specify an array of external templates in the config that will be used in CLI.

Having a single resolvers file is probably a bad idea. We should be creating a resolvers ts file per type. Additionally, we can rename the genrated folder to simply resolvers. Users should be able to extend resolvers somehow.

What I think we can do is:

1. Generate resolvers per type

/resolvers/note.ts

2. Generate empty resolvers file that users can build themselves

/resolvers/note.custom.ts

3. Merge resolvers object together by overriding generated ones if possible

4. Wrap all into graphql module with schema for consistency

https://github.com/APIs-guru/graphql-faker

Rewrite resolver format to work with typescript source code format.

ROADMAP

• Work on refining queries and resolver generation.
• Develop CLI for scaffolding project structure with template options.
• Provide OpenShift templates.

ARCHITECTURE

TODO

• Proper architecture for generation of schema, resolvers
• Documentation
• Integration tests
• Release

Target: We do a company wide demo!

Watch command line should watch for changes in graphql files and rebuild the schema, resolvers and db. For the database we should initially drop all tables as altering the tables based on diff will be investigated in other issue

Projects can be deployed by building a docker container and publishing them to the docker hub. This can be kubernetes openshift server etc.
At very minimum we should provide docker-compose/dockerfile for the template projects so they should be easy to manage and deploy after development is ready.

Templates can be used to seed development workflow with different:

Template ideas

• Basic Appollo template (with db)
• RESTFull gateway template

Templates can also be extended by additional capabilities.
For example:

• Authentication and Authorization
• Cloud deployment etc.

Feature proposal

Create a command line client for generating example projects

Proposed commands

graphback init - creates project
graphback target - setup target server/deployment
graphback generate - builds required source code, resolvers, schema ewtc.
graphback deploy - deploys to specified folder
graphback db - creates db instractructure

Generate subscriptions for Creation, Edits and Deletion for each type if user specified that option in cmd.

About

graphback generate will generate schema and resolvers from given model.

Implementation

• Check if a model(graphql) files exists
• separate resolvers and schema creation from db resources creation #50
• generate schema and resolvers using graphback/core
• write them into the generated folder
• provide next instructions

We can use the graphQL code generator to generate client-side typings and queries. Additionally, we can investigate generating react based forms based on schema. For that we can use https://uniforms.tools/

Some of the previous changes made broke our lint configuration.
Our style diverge outside typical typescript standards.
WE should enable linting as soon as possible as things may go into wrong direction really fast.

Separate queries and resolver generation from database resource generation into different methods which can be called in different cli commands.

Sample application to solve a problem statement using Object Oriented Design. Part of #1
Proposed problem:
Design a Coffee machine to brew coffee.

Introduction

The goal of the project is to provide production ready, autoconfigured service that will be using all the AeroGear Voyager Server functionalities and will provide a command line tool for building and extending GraphQL based Node.js server. The client will help with developers getting started by generating standalone Node.js Server that can provide out of the box features for developers looking for RealTime DataBase capabilities.
Command line will consist of separate commands guiding users through the lifecycle of their application and easing development effort required to build and deploy functional server to production.

Toolbox that will generate fully functional server will allow the user to quickstart development. The key features include:

• Real-time Database: The CLI tool will allow users to set up PostgreSQL and voyager-server simplifying the configuration process. The users will just input types and database models will be created for them.

• Default schema and resolvers: The service will generate default schema and resolvers based on the provided types following a schema first approach.

• Complete Production setup: The toolbox will setup production requirements like analytics, audit logs and metrics.

• Easier to manage: The service will come with docker-compose configuration and OpenShift templates designed to deploy it to managed infrastructure without any hassle.

• Well Documented: User documentation is a very necessary aspect of any service. Well-Organized documentation of the usage of the package will be maintained.

Deliverables

• A Toolbox to provide a solid base for kickstarting development without extensive GraphQL knowledge.
• Integrates with OpenShift/Docker natively and provides complete production setup with analytics, metrics etc.
• Built on a set of opinionated GraphQL patterns and provide out of the box auth, subscriptions and sync.

Implementation

The implementation of the project can be divided into three parts:

Part 1

• We will create a basic typescript starter template with Dockerfile and docker-compose files connecting voyager-server, PostgreSQL. We plan the following workflow for this part:
• Generate a express-based starter template with typescript configuration with the voyager-server.
  Connect PostgreSQL database to the template.
• Input types from users and create models and relations accordingly in the PostgreSQL database.
• Provide out of the box capabilities:
  • Integrate authentication with Keycloak using voyager-keycloak provided by the voyager framework which easily integrates with express server
  • metrics and audit logs support using voyager-audit and voyager-metrics.
  • integration with production level metrics like Grafana and Kibana which are open source analytics platforms.

Part 2

• We will be following schema-first approach to generate simple CRUD schema(queries and mutations) along with resolvers.
• Tooling will generate the GraphQL schema and simple CRUD operations on the database based on the types inputted by the user. It will also provide users with a wide array of customizations while writing type definitions.

Part 3

• Deployment of GraphQL servers to managed infrastructure is not an easy task. Container-based deployment is on the up and we will provide docker-compose or OpenShift templates to make it easier for production deployment of the GraphQL server created.

We need another abstraction that will understand how to persist generated resolvers and schema:

Project structure

- generated
|   resolvers.ts
|   schema.graphql
- client
|   typings.ts
- index.ts
- server.ts
- package.json

Templates

• Basic Apollo template (typescript)

Background

We are using graphql-code-generator version 0.18.2 in our code base to help generate the schema. Particularly we are using the method schemaToTemplateContext to parse datamodel file and use handlebars to generate schema.

Version 1.0

graphql-code-generator has released version 1.0.0 which removes the above mentioned method as stated in docs

Remove the old, deprecated code from this repostory (everything related to flattenDocuments and buildSchemaContext).

Current version's method generate string in output file format. Check PR #84

Requirement

• We need to use version 1.0.0 to generate Resolver Typings to generate resolvers(these are generated to an output file)
• Figuring out Schema generation in current version.

• We are missing a disclamer (not production ready. Do not point it to the production database)
• We did not document what watch will do (it recreates database every time we edit data)
• We are missing documentation explaining templates and databases.
  We need to cover more how init works - by the diagram probably and gif.