Spring Data YugabyteDB – Getting Started!

Ecosystem Software Engineer

September 2, 2021

Spring Data modules are widely used Spring Framework projects for implementing database access in Java applications. Spring Data provides consistent and familiar APIs for querying the data by supporting Data Repository and Template methods, reducing the boilerplate code required for establishing database connection and queries.

For developers and architects, the standard set of APIs provided by Spring Data abstracts away the need to learn the database-specific query language, reducing ramp-up time and increasing developer velocity. Hence it made perfect sense for us in the Yugabyte Ecosystem engineering team to collaborate with Spring Data Engineering to deliver native support for YugabyteDB to Spring Developers.

We are excited to announce the GA release of the Spring Data YugabyteDB project during the Spring One Conference and Spring Data YugabyteDB project is now available under the community modules of Spring Data Project.

The Spring Data YugabyteDB YSQL module provides first-class support for YugabyteDB Distributed SQL (YSQL) API to build modern cloud-native applications. For application developers, Spring Data YugabyteDB will bridge the gap for learning the distributed SQL concepts with familiarity and ease of Spring Data APIs.

Spring Data Yugabyte YSQL

Key features of Spring Data YugabyteDB include:

Consistent and familiar CRUD operations for YugabyteDB with reduced boilerplate code using YugabyteDB templates and repositories
Annotation based configuration support for enabling YugabyteDB YsqlRepository
Support for ACID transactions using the YugabyteDB transaction manager
Cluster-aware Yugabyte Smart Driver that eliminates the need for a load balancer for scaling relational workloads
Topology-awareness that enables geo-distributed applications to achieve low latency by connecting to nodes closest to them
Lightweight ORM support based on Spring Data Relational ORM

Getting Started

Spring Boot applications configured to use YugabyteDB database have to bring down the following maven dependencies:

<dependency>
  <groupId>com.yugabyte</groupId>
  <artifactId>spring-data-yugabytedb-ysql</artifactId>
  <version>2.3.0</version>
</dependency>
<dependency>
  <groupId>com.yugabyte</groupId>
  <artifactId>jdbc-yugabytedb</artifactId>
  <version>42.2.7-yb-5.beta.5</version>
</dependency>

Spring Data YugabyteDB YSQL Configuration

Spring Data YugabyteDB provides an AbstractYugabyteJDBCConfiguration class for configuring YugabyteDB specific YsqlTemplate and YugabyteTransactionManager, which extends the Spring Data transaction implementation to support Yugabyte specific ACID transaction semantics.

YBClusterAwareDataSource – enables ClusterAwareness and TopologyAwareness in Spring Boot applications.
@EnableYsqlRepositories – configures Spring Boot application to find YsqlRepostories

Spring Data YugabyteDB (SDYB) supports two different data sources, YBClusterAwareDataSource in addition to generic PgSimpleDataSource. By default, Spring Data YugabyteDB uses YBClusterAwareDataSource in order to enable Load Balancing and Topology Awareness in Spring Boot applications.

With YBClusterAwareDataSource, Spring Boot applications will evenly distribute the query load across all the available servers in the cluster. Also, they will be able to establish connections when new nodes are added to the cluster on scale up.

@Configuration
@EnableYsqlRepositories
public class YsqlConfig extends AbstractYugabyteJdbcConfiguration {
   @Bean
   DataSource dataSource() {
     Properties poolProperties = new Properties();
     poolProperties.setProperty("dataSourceClassName",
                   "com.yugabyte.ysql.YBClusterAwareDataSource");
     poolProperties.setProperty("dataSource.serverName", hostName);
     poolProperties.setProperty("dataSource.portNumber", port);
     poolProperties.setProperty("dataSource.user", "yugabyte");
     poolProperties.setProperty("dataSource.password", "");
     poolProperties.setProperty("dataSource.loadBalance", "true");
     HikariConfig hikariConfig = new HikariConfig(poolProperties);
     DataSource ybClusterAwareDataSource = new HikariDataSource(hikariConfig);
     return ybClusterAwareDataSource;
   }
}

Configuration Properties

In addition to all the PostgreSQL specific DataSource properties, Spring Data YugabyteDB supports these smart driver properties for load balancing and topology awareness.

dataSource.loadBalance – It takes ‘true’ or ‘false’ as valid values. By default it is ‘false’ for now.
dataSource.topology-keys – It takes comma separated geo-location values. The geo-location can be given as ‘cloud:region:zone’.

Additional Documentation on YugabyteDB JDBC Smart Driver can be found here.

Spring Data Yugabyte Templates and Query Options

Spring Data YugabyteDB module provides YsqlTemplate with QueryOptions for enabling Yugabyte YSQL specific operations.

YsqlTemplate extends the JDBCAggregateTemplate operations to support all the PostgreSQL specific operations. In addition to those, YsqlTemplate has a custom count() implementation for enabling SERIALIZABLE, READ ONLY, DEFERRABLE transaction for executing the count * queries. YsqlTemplate has required plumbing for enabling follower-read queries. Once the feature lands on the YugabyteDB Database (under active development), YsqlTemplate and YsqlRepositories will support reading data from Follower copies, considerably increasing the throughput of Spring applications.

QueryOptions supports tuning of various query options applicable to YugabyteDB YSQL per request level. Currently, QueryOptions provides support for configuring Deferrable transactions, follower-reads(under development). QueryOptions will be constantly improved to provide a programmatic way of configuring YugabyteDB Specific features in Spring Boot application.

YsqlTemplate ysqlTemplate = applicationContext.getBean("ysqlTemplate", YsqlTemplate.class);
QueryOptions queryOptions = QueryOptions
                             .builder()
                             .deferrable(true)
                             .build();
ysqlTemplate.count(Visit.class, queryOptions));

Ysql Repository

Spring Data YugabyteDB YSQL project provides implementation for YsqlRepository and @EnableYsqlRepositories. YsqlRepositories automagically provides CRUD implementation for Domain classes for querying the corresponding tables in the YugabyteDB Database.

When YsqlRepository is configured with YBClusterAwareDataSource, all the queries will be load balanced across the available nodes in the YugabyteDB Cluster thus increasing the performance of the spring boot APIs under heavy traffic.

public interface VisitRepository extends YsqlRepository<Visit, Integer> {
    Visit save(Visit visit) throws DataAccessException;

    @Query("select * from visit where pet_id = :petId")
    List<Visit> findByPetId(@Param("petId") Integer petId);
}

Sample Application: Spring Petclinic with Spring Data YugabyteDB

Spring Petclinic application is a popular application in the Spring Developer community which demonstrates the use of the Spring Data repository pattern with different database providers. We refactored the Spring Petclinic application to use Spring Data YugabyteDB and Smart JDBC Driver. This implementation of Spring Petclinic application can be downloaded from the following git repo.

Spring-Data-YugabyteDB-Petclinic-Image