Development Framework

PostGraphile offers an HTTP endpoint for GraphQL queries and mutations as well as a WebSocket endpoint to support GraphQL subscriptions. The setup adds these endpoints to the WebSocket-enabled HTTP server. The GraphQL endpoint is available at the route /graphql. The interactive GraphiQL IDE is added as /graphiql endpoint that allows you to conveniently view your GraphQL schema and execute queries and mutations. This endpoint can be disabled, e.g. for production deployments.

In general, you can tweak every aspect of the GraphQL API generation. The Mosaic framework provides a PostGraphile options builder which contains already reasonable defaults that you can further extend. The options define which plug-ins should be loaded (and in which order), settings on how the GraphQL API should be built, PostgreSQL settings for database queries, parses the HTTP request (e.g. for JWT parsing), etc.

We suggest enabling the following open-source PostGraphile plug-ins:

and the following Mosaic-specific plug-ins:

Based on your database tables, columns, and relationships, PostGraphile automatically creates the GraphQL query and mutation endpoints. If you have a movies table that has a 1:n relation to a table movies_casts, it creates the following query endpoints (when using the default Mosaic settings - this can be fine-tuned):

The GraphQL API allows one to easily traverse the graph. From the movie entity, you can access the cast members that are part of the movie. This connection has again all the filters, sorting, paging, and other functionality to return exactly the data that the frontend needs.

To manipulate the data, PostGraphile generates (by default) the following mutation endpoints:

In addition to the query and mutation endpoints, there is the GraphQL subscription endpoint. If the database is set up to issue change triggers, those are forwarded to the GraphQL subscribers. The endpoint name for all the movie and movie cast-related changes would be movieMutated.

A direct mapping from database tables (and their relations) to GraphQL API endpoints is likely how you will manage most of your GraphQL schema. Please see the Schemas section under Database to find out the best practices to manage your database schema.

PostGraphile generates the GraphQL API based on your PostgreSQL database already in a very useable way. Plugins allow you to further tweak and customize the aspects of how exactly the API should be generated.

The simplest way is to use the PostGraphile makeExtendSchemaPlugin. This allows you to adjust the GraphQL schema, for example, by providing a new query or mutation endpoint and adding corresponding resolvers to it.

Another option is to wrap existing resolvers and add your own logic before or after the resolver is called by utilizing the makeWrapResolversPlugin.

The most powerful, but also a more complex way, to fine-tune every aspect of the generated GraphQL API is to use the hooks. This lets you tweak the fields of GraphQL types, query and mutation operations, adjust input types, and much more.

To accommodate both GraphQL and internal data, Mosaic uses different database schemas and database roles. The ones that are meant to be used in your project are:

To create and maintain your database, you can use any database migration tool or manually create and alter the database. In our template projects, we use the Graphile migrate library for easy and fast development cycles which automatically update the database and the local GraphQL API on every change to the migration SQL file.

Every project has a ./migrations/current.sql file in which you can add your SQL migration code. As the Graphile migrate is a forward only migration and is executed on many times against the local database it must be idempotent. This means, for example, to add a DROP TABLE IF EXISTS app_public.movies CASCADE; before calling the CREATE TABLE app_public.movies (…). When the migration is applied (exactly once) in production, this does not cause any issues. However, it is immensely helpful to have fast development cycles locally.

When your local service runs in the dev mode, it watches for any change to the current.sql file. Whenever you save the file, it is run against your local database. This way, you get immediate feedback if there are any errors in the SQL file. If it can be applied successfully, it automatically triggers a rebuild of the GraphQL API to make the new changes directly available without any manual rebuild/restart. If you use the GraphiQL web IDE, this automatically reloads the schema as well. In summary, this allows to change something in the current.sql file which directly reflects in the GraphiQL web app.

When you are happy with the migration SQL code, you can run the Graphile migrate commit command to freeze the contents of your current.sql file into a committed database migration file. This is a Grapile migration step - not to be confused with GIT commits. After this step, the current.sql file is empty again. If you want to change something in the last committed database migration file, you can run the uncommit command which removes the last commit file and adds the contents back to the current.sql file. This operation must be used only as long as it was never deployed to production!

As a general best practice, the current.sql file should always be empty when you GIT commit code to the master branch.

When the application is deployed to some productive server, it executes all the committed database migration files to the database that were not run so far. The current.sql file is only executed in the DEV mode - not in the production mode.