Spring Boot + GraphQL + PostgreSQL example

GraphQL is a query language that offers an alternative model to developing APIs (REST, SOAP or gRPC) with detailed description.

In this tutorial, we’re gonna build a Spring Boot GraphQL example with PostgreSQL database that will expose CRUD APIs to create, read, update and delete objects with the help of graphql-spring-boot-starter and Spring Data JPA.

Related Post:
– Spring Boot + PostgreSQL example: CRUD Rest API
– Spring Boot, Spring Security, PostgreSQL: JWT Authentication example
– Spring Boot Thymeleaf CRUD example
– Documentation: Spring Boot Swagger 3 example
– Unit Test: @DataJpaTest example for Spring Data Repository
– Caching: Spring Boot Redis Cache example
– Dockerize: Docker Compose: Spring Boot and Postgres example

Spring Boot GraphQL with PostgreSQL example

Overview

We have two data models: Author and Tutorial.

Author {
  id: Long
  name: String
  age: Integer
}

Tutorial {
  id: Long
  title: String
  description: String
  author: Author
}

One Author will have many Tutorials, so it is One-to-Many relationship.

The goal of this example is to build a GraphQL APIs to do CRUD operations with PostgreSQL database using only one endpoint: /apis/graphql.

The Spring Boot GraphQL Starter will make GraphQL server running in a short time.

CRUD GraphQL APIs

– Create an Author:

• GraphQL

mutation {
  createAuthor(
    name: "bezkoder",
    age: 27) {
      id name
  }
}

• Response

{
  "data": {
    "createAuthor": {
      "id": "1",
      "name": "bezkoder"
    }
  }
}

– Create a Tutorial:

• GraphQL: we want response including Tutorial id, title and author (name)

mutation {
  createTutorial (
    title: "Tutorial #1",
    description: "Description for Tut#1"
    author: 1)
    {
      id title author { name }
    }
}

• Response

{
  "data": {
    "createTutorial": {
      "id": "1",
      "title": "Tutorial #1",
      "author": {
        "name": "bezkoder"
      }
    }
  }
}

– Read all Authors:

• GraphQL

{
  findAllAuthors{
    id
    name
    age
  }
}

• Response

{
  "data": {
    "findAllAuthors": [
      {
        "id": "1",
        "name": "bezkoder",
        "age": 27
      },
      {
        "id": "2",
        "name": "zKoder",
        "age": 30
      }
    ]
  }
}

– Read all Tutorials:

• GraphQL

{
  findAllTutorials{
    id
    title
    description
    author{
      id
      name
    }
  }
}

• Response

{
  "data": {
    "findAllTutorials": [
      {
        "id": "1",
        "title": "Tutorial #1",
        "description": "Description for Tut#1",
        "author": {
          "id": "1",
          "name": "bezkoder"
        }
      },
      {
        "id": "2",
        "title": "Tutorial #2",
        "description": "Description for Tut#2",
        "author": {
          "id": "1",
          "name": "bezkoder"
        }
      },
      {
        "id": "3",
        "title": "Tutorial #3",
        "description": "Description for Tut#3",
        "author": {
          "id": "2",
          "name": "zKoder"
        }
      }
    ]
  }
}

– Update a Tutorial:

• GraphQL

mutation {
  updateTutorial (
    id: 2
    description: "updated Desc Tut#2")
    {
      id title description author { name }
    }
}

• Response

{
  "data": {
    "updateTutorial": {
      "id": "2",
      "title": "Tutorial #2",
      "description": "updated Desc Tut#2",
      "author": {
        "name": "bezkoder"
      }
    }
  }
}

– Delete a Tutorial:

• GraphQL

mutation {
  deleteTutorial(id: 1)
}

• Response

{
  "data": {
    "deleteTutorial": true
  }
}

– Count number of Tutorials:

• GraphQL

{
  countTutorials
}

• Response

{
  "data": {
    "countTutorials": 2
  }
}

If you check PostgreSQL database, it will have 2 tables.
The content inside these tables looks like:
– author table

– tutorial table

Build Spring Boot GraphQL APIs with PostgreSQL Database

Technology

Our Spring Boot application will use:

• Java 17 / 11 / 8
• Spring Boot 3 / 2 (with Spring Web, Spring Data JPA)
• graphql-spring-boot-starter 15.0.0
• graphql-java-tools 5.2.4
• Maven 3.6.1
• PostgreSQL

Project Structure

This is folders & files structure for our Spring Boot + GraphQL + PostgreSQL application:

– resources/graphql contains .graphqls files that define GraphQL chemas.
– model holds two Entities: Author and Tutorial.
– repository contains Repository interfaces to interact with PostgreSQL database.
– resolver resolves values for query & mutation requests by implementing some Resolver interfaces from GraphQL Java Tools.
– application.properties configures Spring Datasource, Spring Data JPA and GraphQL base Url.
– pom.xml includes dependencies for the whole project.

Set up the project

Create new Spring Boot project using Spring Tool Suite or going to https://start.spring.io/.

Then add these dependencies to pom.xml file:

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-web</artifactId>
</dependency>

<dependency>
	<groupId>com.graphql-java-kickstart</groupId>
	<artifactId>graphql-spring-boot-starter</artifactId>
	<version>15.0.0</version>
</dependency>

<dependency>
	<groupId>com.graphql-java</groupId>
	<artifactId>graphql-java-tools</artifactId>
	<version>5.2.4</version>
</dependency>

<dependency>
	<groupId>com.graphql-java</groupId>
	<artifactId>graphql-java-extended-scalars</artifactId>
	<version>21.0</version>
</dependency>

<dependency>
	<groupId>org.postgresql</groupId>
	<artifactId>postgresql</artifactId>
	<scope>runtime</scope>
</dependency>

Configure Spring Datasource, JPA, GraphQL

Open application.properties and add the following configuration.

spring.datasource.url= jdbc:postgresql://localhost:5432/testdb
spring.datasource.username= postgres
spring.datasource.password= 123

spring.jpa.properties.hibernate.jdbc.lob.non_contextual_creation= true
spring.jpa.properties.hibernate.dialect= org.hibernate.dialect.PostgreSQLDialect

# Hibernate ddl auto (create, create-drop, validate, update)
spring.jpa.hibernate.ddl-auto= update

# Graphql
graphql.servlet.mapping: /apis/graphql

By default, Spring Boot GraphQL starter exposes the GraphQL Service on /graphql endpoint for HTTP POST requests containing the GraphQL payload. In the code above, we config the endpoint with new base url: /apis/graphql.

Extend Scalars for graphql-java Long type

The implementation of GraphQL Java doesn’t provide a Long scalar type by default. So we need to use the graphql-java-extended-scalars package that provides a GraphQLLong scalar type definition which represents java.lang.Long.

Open SpringBootGraphqlPostgresqlApplication.java and add a Bean named extendedScalarLong():

@SpringBootApplication
public class SpringBootGraphqlPostgresqlApplication {
  // ...

  @Bean
  public graphql.schema.GraphQLScalarType extendedScalarLong() {
    return graphql.scalars.ExtendedScalars.GraphQLLong;
  }
}

Create GraphQL Schema

We’re gonna split up your schema into two .graphqls files. The Spring Boot GraphQL starter will automatically find these schema files.

Under src/main/resources folder, create author.graphqls and tutorial.graphqls files.

author.graphqls

scalar Long

type Author {
	id: ID!
	name: String!
	age: Int
}

# Root
type Query {
	findAllAuthors: [Author]!
	countAuthors: Long!
}

# Root
type Mutation {
	createAuthor(name: String!, age: Int): Author!
}

GraphQL accepts only one root Query and one root Mutation types, so we need to bring all the query and mutation operations into the root Types. But in the schemas above, we want to split the logic for each model. How to do this? We extend the Query and Mutation types.

tutorial.graphqls

type Tutorial {
	id: ID!
	title: String!
	description: String
	author: Author
}

extend type Query {
	findAllTutorials: [Tutorial]!
	countTutorials: Long!
}

extend type Mutation {
	createTutorial(title: String!, description: String, author: ID!): Tutorial!
	updateTutorial(id: ID!, title: String, description: String): Tutorial!
	deleteTutorial(id: ID!): Boolean
}

The “!” at the end of some fields indicates non-nullable type. If we don’t use it, GraphQL accepts null value in the response.

Define Data Models

Now we define twom main models with One-to-Many Relationship in model package:

• Author: id, name, age
• Tutorial: id, title, description, author_id

Author.java

package com.bezkoder.spring.graphql.postgresql.model;

// import javax.persistence.*;
import jakarta.persistence.*; // for Spring Boot 3

@Entity
public class Author {
  @Id
  @GeneratedValue(strategy = GenerationType.AUTO)
  private Long id;

  @Column(name = "name", nullable = false)
  private String name;

  @Column(name = "age")
  private Integer age;

  public Author() {
  }

  public Author(Long id) {
    this.id = id;
  }

  public Author(String name, Integer age) {
    this.name = name;
    this.age = age;
  }

  public Long getId() {
    return id;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public Integer getAge() {
    return age;
  }

  public void setAge(Integer age) {
    this.age = age;
  }

  @Override
  public String toString() {
    return "User [id=" + id + ", name=" + name + ", age=" + age + "]";
  }

}

Tutorial.java

package com.bezkoder.spring.graphql.postgresql.model;

// import javax.persistence.*;
import jakarta.persistence.*; // for Spring Boot 3

@Entity
public class Tutorial {
  @Id
  @GeneratedValue(strategy = GenerationType.AUTO)
  private Long id;

  @Column(name = "title", nullable = false)
  private String title;

  @Column(name = "description")
  private String description;

  @ManyToOne
  @JoinColumn(name = "author_id", nullable = false, updatable = false)
  private Author author;

  public Tutorial() {
  }

  public Tutorial(String title, String description, Author author) {
    this.title = title;
    this.description = description;
    this.author = author;
  }

  public Long getId() {
    return id;
  }

  public String getTitle() {
    return title;
  }

  public void setTitle(String title) {
    this.title = title;
  }

  public String getDescription() {
    return description;
  }

  public void setDescription(String description) {
    this.description = description;
  }

  public Author getAuthor() {
    return author;
  }

  public void setAuthor(Author author) {
    this.author = author;
  }

  @Override
  public String toString() {
    return "Tutorial [id=" + id + ", title=" + title + ", description=" + description + ", author=" + author + "]";
  }

}

Create Repositories

In repository package, create two interfaces that implement JpaRepository.

AuthorRepository.java

package com.bezkoder.spring.graphql.postgresql.repository;

import org.springframework.data.jpa.repository.JpaRepository;

import com.bezkoder.spring.graphql.postgresql.model.Author;

public interface AuthorRepository extends JpaRepository<Author, Long> {

}

TutorialRepository.java

package com.bezkoder.spring.graphql.postgresql.repository;

import org.springframework.data.jpa.repository.JpaRepository;

import com.bezkoder.spring.graphql.postgresql.model.Tutorial;

public interface TutorialRepository extends JpaRepository<Tutorial, Long> {

}

Once we extends the JpaRepository, Spring Data JPA will automatically generate implementation with find, save, delete, count methods for the entities.

Implement GraphQL Root Query Resolver

Every field in the schema root query should have a method in the Query Resolver class with the same name.

Now look back to the schemas we defined above.

# author.graphqls
type Query {
	findAllAuthors: [Author]!
	countAuthors: Long!
}

# tutorial.graphqls
extend type Query {
	findAllTutorials: [Tutorial]!
	countTutorials: Long!
}

This Query class implements GraphQLQueryResolver. We don’t want to use GraphQLLong for countAuthors and countTutorials return type, so we alias it by using newAliasedScalar("Long").

resolver/Query.java

package com.bezkoder.spring.graphql.postgresql.resolver;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import com.bezkoder.spring.graphql.postgresql.model.Author;
import com.bezkoder.spring.graphql.postgresql.model.Tutorial;
import com.bezkoder.spring.graphql.postgresql.repository.AuthorRepository;
import com.bezkoder.spring.graphql.postgresql.repository.TutorialRepository;
import graphql.kickstart.tools.GraphQLQueryResolver;
import graphql.scalars.ExtendedScalars;
import graphql.schema.GraphQLScalarType;

@Component
public class Query implements GraphQLQueryResolver {
  private AuthorRepository authorRepository;
  private TutorialRepository tutorialRepository;

  GraphQLScalarType longScalar = ExtendedScalars.newAliasedScalar("Long")
          .aliasedScalar(ExtendedScalars.GraphQLLong)
          .build();

  @Autowired
  public Query(AuthorRepository authorRepository, TutorialRepository tutorialRepository) {
    this.authorRepository = authorRepository;
    this.tutorialRepository = tutorialRepository;
  }

  public Iterable<Author> findAllAuthors() {
    return authorRepository.findAll();
  }

  public Iterable<Tutorial> findAllTutorials() {
    return tutorialRepository.findAll();
  }

  public long countAuthors() {
    return authorRepository.count();
  }

  public long countTutorials() {
    return tutorialRepository.count();
  }

}

Implement GraphQL Root Mutation Resolver

Mutation class will implement GraphQLMutationResolver.
Just like Query Resolver, every field in the schema mutation query should have a method in the Mutation Resolver class with the same name.

resolver/Mutation.java

package com.bezkoder.spring.graphql.postgresql.resolver;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import com.bezkoder.spring.graphql.postgresql.model.Author;
import com.bezkoder.spring.graphql.postgresql.model.Tutorial;
import com.bezkoder.spring.graphql.postgresql.repository.AuthorRepository;
import com.bezkoder.spring.graphql.postgresql.repository.TutorialRepository;
import graphql.kickstart.tools.GraphQLMutationResolver;
import jakarta.persistence.EntityNotFoundException;

@Component
public class Mutation implements GraphQLMutationResolver {
  private AuthorRepository authorRepository;
  private TutorialRepository tutorialRepository;

  @Autowired
  public Mutation(AuthorRepository authorRepository, TutorialRepository tutorialRepository) {
    this.authorRepository = authorRepository;
    this.tutorialRepository = tutorialRepository;
  }

  public Author createAuthor(String name, Integer age) {
    Author author = new Author();
    author.setName(name);
    author.setAge(age);

    authorRepository.save(author);

    return author;
  }

  public Tutorial createTutorial(String title, String description, Long authorId) {
    Tutorial tutorial = new Tutorial();
    tutorial.setAuthor(new Author(authorId));
    tutorial.setTitle(title);
    tutorial.setDescription(description);

    tutorialRepository.save(tutorial);

    return tutorial;
  }

  public boolean deleteTutorial(Long id) {
    tutorialRepository.deleteById(id);
    return true;
  }

  public Tutorial updateTutorial(Long id, String title, String description) throws EntityNotFoundException {
    Optional<Tutorial> optTutorial = tutorialRepository.findById(id);

    if (optTutorial.isPresent()) {
      Tutorial tutorial = optTutorial.get();

      if (title != null)
        tutorial.setTitle(title);
      if (description != null)
        tutorial.setDescription(description);

      tutorialRepository.save(tutorial);
      return tutorial;
    }

    throw new EntityNotFoundException("Not found Tutorial to update!");
  }

}

Implement GraphQL Field Resolver

For complex fields like author in Tutorial, we have to resolve the value of those fields.
TutorialResolver implements GraphQLResolver interface and has getAuthor() method.

resolver/TutorialResolver.java

package com.bezkoder.spring.graphql.postgresql.resolver;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import com.bezkoder.spring.graphql.postgresql.model.Author;
import com.bezkoder.spring.graphql.postgresql.model.Tutorial;
import com.bezkoder.spring.graphql.postgresql.repository.AuthorRepository;
import graphql.kickstart.tools.GraphQLResolver;

@Component
public class TutorialResolver implements GraphQLResolver<Tutorial> {
  @Autowired
  private AuthorRepository authorRepository;

  public TutorialResolver(AuthorRepository authorRepository) {
    this.authorRepository = authorRepository;
  }

  public Author getAuthor(Tutorial tutorial) {
    return authorRepository.findById(tutorial.getAuthor().getId()).orElseThrow(null);
  }
}

If the client want to get a Tutorial without author field, the GraphQL Server will never do the work to retrieve it. So the getAuthor() method above will never be executed.

Run & Check result

Run Spring Boot application with command: mvn spring-boot:run

Tables will be automatically generated in Database.
If you check PostgreSQL database, you can see them:

testdb=# \d
              List of relations
 Schema |     Name     |   Type   |  Owner
--------+--------------+----------+----------
 public | author       | table    | postgres
 public | author_seq   | sequence | postgres
 public | tutorial     | table    | postgres
 public | tutorial_seq | sequence | postgres
(9 rows)


testdb=# \d author
                      Table "public.author"
 Column |          Type          | Collation | Nullable | Default
--------+------------------------+-----------+----------+---------
 id     | bigint                 |           | not null |
 age    | integer                |           |          |
 name   | character varying(255) |           | not null |
Indexes:
    "author_pkey" PRIMARY KEY, btree (id)
Referenced by:
    TABLE "tutorial" CONSTRAINT "fkjmn3w4clcdfulxllrw6n636qd" FOREIGN KEY (author_id) REFERENCES author(id)


testdb=# \d tutorial
                        Table "public.tutorial"
   Column    |          Type          | Collation | Nullable | Default
-------------+------------------------+-----------+----------+---------
 id          | bigint                 |           | not null |
 description | character varying(255) |           |          |
 title       | character varying(255) |           | not null |
 author_id   | bigint                 |           | not null |
Indexes:
    "tutorial_pkey" PRIMARY KEY, btree (id)
Foreign-key constraints:
    "fkjmn3w4clcdfulxllrw6n636qd" FOREIGN KEY (author_id) REFERENCES author(id)

For checking result, you can use Postman to make HTTP POST request to http://localhost:8080/apis/graphql.

Conclusion

As an alternative approach to REST APIs, GraphQL minimize complexity between client & server.

Today we’ve learned how to use Spring Boot GraphQL Starter and the GraphQL Java Tools to build GraphQL Apis. Our Spring Boot project also can communicate with PostgreSQL database using Spring Data JPA.

Happy learning! See you again.

Further Reading

• GraphQL documentation
• https://www.graphql-java.com/tutorials/getting-started-with-spring-boot/
• graphql-java Github

Source Code

You can find the complete source code for this tutorial on Github.

– Security: Spring Boot, PostgreSQL: JWT Authentication example
– Unit Test: @DataJpaTest example for Spring Data Repository
– Documentation: Spring Boot + Swagger 3 example (with OpenAPI 3)
– Caching: Spring Boot Redis Cache example
– Dockerize: Docker Compose: Spring Boot and Postgres example