Appendix: and the Evolution of the Apache ShardingSphere Open Source Community

Reading this book, you're probably at least intrigued by Apache ShardingSphere and eager to gain a better understanding of this open source project. If you are browsing this appendix after completing the previous chapters, then it means that you have officially reached the end of this book and are ready to master Apache ShardingSphere and take any database to which you apply ShardingSphere to the next level.

If you haven't gone through this book in a linear fashion and have jumped to the appendix first, you are in the right place too.

To make the book informative, we provided plenty of information concerning project descriptions, configuration, tests, and use cases, for both beginners and advanced learners.

The previous 12 chapters were divided into three main parts. Except for the first four chapters, you can choose to read or revisit the following chapters independently, depending on your interests and time:

• In Chapters 1-4, we introduced the basics of Apache ShardingSphere.
• In Chapters 5-7, we discussed the common but classic applications of Apache ShardingSphere.
• In Chapters 8-12, we shared the advanced applications for Apache ShardingSphere.

This book covered all the basic aspects of Apache ShardingSphere as inclusively as possible, making it a great way to understand its technology. To help you further study Apache ShardingSphere, we also provided advanced applications, test cases, and use cases for your reference.

Although Apache ShardingSphere is updated very quickly, and this book is based on version 5.0.0 to enhance your understanding and use of the product – its inclusive community, plugin-oriented architecture, and ecosystem-supporting concept will never change.

This chapter will guide you through the following topics:

• How to leverage the project documentation
• How to use the example projects we offer on GitHub
• More information on Apache ShardingSphere's source code, license, and version
• An overview of our open source community and how you can join us

By the end of this chapter, you will have fully assimilated everything there is to know about Apache ShardingSphere, and you'll be able to start your open source journey.

How to leverage the documentation to find answers to your questions

This book organizes Apache ShardingSphere's concepts to help you to master all aspects from various perspectives. Let's recall the key points of each chapter.

Let's start with the basics. Chapters 1-4 help you gain an understanding of the current industry status, its evolution, why Apache ShardingSphere was first conceived, and where it fits in the database landscape.

The second section of the book, including Chapters 5-7, moved you on to getting started with ShardingSphere Proxy and JDBC adaptors, configurations, their mixed deployment, and more.

The third section, from Chapters 8-10 (once you assimilated the features, clients, and their configurations), introduced you to the concept of Database Plus and the advanced use of Apache ShardingSphere.

The final section of the book (Chapters 11 and 12) was all about putting theory to practice. In the chapters in this section, you were able to apply your ShardingSphere knowledge with some advanced examples. The examples reviewed in this section are all borne out of real enterprise scenarios, thanks to the feedback we collected from our enterprise users.

Now that we have reviewed the overall content of each section, helping you tie the chapters together, we should cover some auxiliary content that you will find useful. In the following section, we start by exploring the shardingsphere-example project.

Example project introduction

shardingsphere-example is an independent Maven project in the -examples directory of the Apache ShardingSphere project. The link to the Maven project is https://github.com/apache/shardingsphere/tree/master/examples.

The shardingsphere-example project contains multiple modules providing use cases for ShardingSphere-JDBC, ShardingSphere-Proxy, and ShardingSphere-Parser, for instance:

• shardingsphere-jdbc-example: This project gives you usages and configuration examples of functions such as data sharding, read/write splitting, encryption, shadow databases, distributed governance, and distributed transactions, as well as access methods such as Java API, YAML, Spring Boot, and Spring Namespace.

You can refer to the directory structure as follows:

├── mixed-feature-example

│   └── sharding-readwrite-splitting-example

├── single-feature-example

│   ├── cluster-mode-example

│   ├── encrypt-example

│   ├── extension-example

│   ├── readwrite-splitting-example

│   ├── shadow-example

│   ├── sharding-example

│   ├── target

│   └── transaction-example

• shardingsphere-proxy-example: ShardingSphere-Proxy shows you how to configure server.yaml and schema rules in ShardingSphere-Proxy. Since the configuration formats of data sources and rules are consistent with ShardingSphere-JDBC, they are not repeated in the project. Instead, we demonstrate the unique Proxy functions such as DistSQL and SQL Hint.

The directory structure you'll be presented with is as follows:

├── shardingsphere-proxy-boot-mybatis-example

├── shardingsphere-proxy-distsql-example

└── shardingsphere-proxy-hint-example

• other-example: The other-example project contains use cases of SQLParserEngine, of which you have learned the concepts in the previous chapters of this book. It is the SQL parsing engine, which is customized by Apache ShardingSphere and fundamental to features of ShardingSphere-JDBC and ShardingSphere-Proxy. With SQLParserEngine, a SQL statement can be parsed into an abstract syntax tree, which allows programmers to develop various advanced features.

The directory structure is as follows:

└── shardingsphere-parser-example

Now that you have an overview of the shardingsphere-example project, let's explore how you can make the best use of it.

How to use the example project section

In this section, we give several typical examples to show you how to configure and run shardingsphere-example.

Though there are many modules in the shardingsphere-example project, we can only introduce some of the most popular application scenarios of ShardingSphere-JDBC.

In the following section, you will find a preparation phase that you can commonly refer to, followed by the steps that are specific to the example you are interested in. You will find that we have prepared and divided the steps into subsections according to the cases, including sharding-springboot-mybatis and readwrite-splitting-raw-jdbc.

Preparation

Maven is the project's build tool for shardingsphere-example. So, please set up Maven first before proceeding to the following step:

1. Prepare Apache ShardingSphere. If you have not configured Apache ShardingSphere yet, please clone and compile it first. You can use the following code to perform this step:

   Bash

   ## Clone Apache ShardingSphere

   git clone https://github.com/apache/shardingsphere.git

   ## Compile

   cd shardingsphere

   mvn clean install -Prelease

   Note

   If you see the Filename too long warning when cloning a project in a Windows environment, please refer to this solution: https://shardingsphere.apache.org/document/5.0.0/en/reference/faq/#22-other-in-windows-environmentwhen-cloning-shardingsphere-source-code-through-git-why-prompt-filename-too-long-and-how-to-solve-it.

2. Import the shardingsphere-example project to your IDE.
3. Prepare a manageable database environment, such as local MySQL examples.
4. If you need to test read/write splitting, please make sure that your primary-replica synchronization is running properly.
5. Execute the init database script: examples/src/resources/manual_schema.sql.

This concludes the preparation phase; let's now move on to the actual examples.

Scenarios and examples

In this section, we will go over various examples and scenarios. The first example includes data sharding, while the second refers to the read/write splitting feature.

sharding-spring-boot-mybatis-example

This example shows you the application of ShardingSphere-JDBC in combination with SpringBoot and MyBatis to perform sharding. The goal is to shard one table's data into four tables evenly and store them in two different databases.

The path is as follows:

examples/shardingsphere-jdbc-example/single-feature-example/sharding-example/sharding-spring-boot-mybatis-example

Let's get prepared for our goal:

1. Configure application.properties.
2. Set spring.profiles.active as sharding-databases-tables.
3. Configure application-sharding-databases-tables.
4. Change jdbc-url with your database location and set up your user ID, password, and so on.
5. Set the attribute of spring.shardingsphere.props.sql-show as true.

See more details in Chapter 5, Exploring ShardingSphere Adaptors.

Now, let's run the ShardingSpringBootMybatisExample.java startup.

Now, you can observe the routing of all SQL statements in Logic SQL and Actual SQL logs and understand how sharding works.

readwrite-splitting-raw-jdbc-example

This example shows how you can use YAML and configure the feature read/write splitting of ShardingSphere-JDBC. The goal is to separate one writing database and two reading databases.

The path is as follows:

examples/shardingsphere-jdbc-example/single-feature-example/readwrite-splitting-example/

readwrite-splitting-raw-jdbc-example

Let's get prepared for our goal:

1. Configure resources/META-INF/readwrite-splitting.yaml.
2. Change jdbc-url with your database location and set up your user ID, password, and so on.
3. Set props.sql-show as true.

See more details in Chapter 5, Exploring ShardingSphere Adaptors.

Now, run the ReadwriteSplittingRawYamlConfigurationExample.java startup.

Now, you can observe the routing of all SQL expressions in Logic SQL and Actual SQL logs and understand how read and write splitting works.

Note

When primary-replica database synchronization fails, there will be query errors.

The shardingsphere-example project includes examples such as the ones introduced in this section, but also many more. It is a community-driven effort, and you will find other useful examples on the Apache ShardingSphere GitHub repository if you'd like to browse additional examples.

Source code, license, and version

Let's start by reviewing the source code and some common terminology. You can leverage the following section as a glossary. We have classified the terms according to their respective modules.

In the following two subsections, we will proceed to review the current version and the Apache ShardingSphere license.

shardingsphere-kernel

The shardingsphere-kernel module consists of authority, single-table, and transaction. When using ShardingSphere, you will become pretty accustomed to these terms and components. The following is a refresher of the definitions that we covered in the previous chapters of this book:

The authority module is used to allocate and manage user authority. It includes submodules of api and core:

• api provides a universal interface for authority configuration items and relevant authorities.
• The core module provides authority verification, authority algorithm, and authority rules among other implementation items.

The single-table module is responsible for the use of single-table databases, and it includes api and core:

• The api module provides default configuration items of a single table.
• The core module can implement functions such as single-table rule loading, metadata loading, and single-table routing.

The transaction module is used for managing transactions. It includes api, core, and type:

• The api module provides the default configuration item of the transaction.
• The core module can implement event rules, transaction manager, and transaction functions.
• The type module includes base and xa:
  • The base module includes seata-at: The seata-at module provides the transaction manager of the seata-at mode and enables the implementation of relevant functions of the seata-at mode.
  • The xa module includes core, provider, and spi:
    • The core module: This module enables the implementation and abstraction of xa transaction functions.
    • The provider module includes atomikos, bitronix, and narayana: The atomikos module can implement atomikos transactions. The bitronix module can implement bitronix transactions. The narayana module enables relevant implementation of the narayana transaction.
    • The spi module provides an SPI loading interface of xa transactions, enabling users to implement xa transactions themselves.

shardingsphere-infra

The following list is a refresher of the shardingsphere-infra module, which contains binder, common, context, datetime, executor, merge, optimize, parser, rewrite, and route:

• binder is mainly used to set context information in SQL statements.
• common contains the abstraction and relevant port definition of general functions of ShardingSphere. More specifically, it has functions such as algorithm definition, mode definition, rule definition, database configuration, metadata information, event delivery, abnormality, and YAML configuration conversion.
• context mainly provides functions such as kernel execution process management and metadata refresh.
• datetime provides database time and system time.
• executor provides relevant functions to execute SQL, such as SQL checker and execution engine.
• merge provides relevant functions for merging SQL result sets by way of stream result set merger and memory result set merger.
• optimize provides relevant functions of the query optimizer. It is mainly used to support and optimize complex SQL.
• parser provides the function of parsing SQL statements and can improve parsing performance by its caching capability.
• rewrite provides the function of rewriting SQL statements and provides universal, basic components for rewriting sharding, encryption, and decryption functions.
• route provides the function of SQL routing, constituting a universal, basic component of SQL routing.

shardingsphere-jdbc

The shardingsphere-jdbc module provides a ShardingSphere API that has reached JDBC standard, and provides an easy project access way that can use the Spring framework:

• shardingsphere-jdbc-core provides a ShardingSphere API that has reached JDBC standard.
• shardingsphere-jdbc-spring provides Spring Namespace and Spring Boot Starter.
• shardingsphere-jdbc-transaction-spring implements the aspect-oriented programming (AOP) processing logic of ShardingSphere transactional annotation.
• shardingsphere-jdbc-core-spring provides Spring Namespace processing logic and Spring Boot Starter automatic configuration logic.
• shardingsphere-jdbc-spring-infra provides the tools needed for Spring access.

shardingsphere-db-protocol

The shardingsphere-db-protocol module defines message formats of various database protocols:

• shardingsphere-db-protocol-core defines constants and interfaces related to database protocols.
• shardingsphere-db-protocol-mysql defines the MySQL protocol message format.
• shardingsphere-db-protocol-postgresql defines the PostgreSQL protocol message format.
• shardingsphere-db-protocol-opengauss defines the openGauss protocol message format.

shardingsphere-proxy

The shardingsphere-proxy module contains protocol implementation of MySQL, PostgreSQL, and openGauss databases, which are supported by ShardingSphere-Proxy, and the logic of real database interaction:

• shardingsphere-proxy-backend provides the logic of interactions between ShardingSphere-Proxy and real databases.
• shardingsphere-proxy-bootstrap is responsible for configuration loading in launching ShardingSphere-Proxy.
• shardingsphere-proxy-frontend implements the interaction between database protocols and is responsible for the interaction with the client ends.
• shardingsphere-proxy-frontend-spi defines an SPI related to protocol implementation.
• shardingsphere-proxy-frontend-core is responsible for the universal logic of interaction with client ends.
• shardingsphere-proxy-frontend-mysql implements the logic of the interaction with the MySQL protocol.
• shardingsphere-proxy-frontend-postgresql implements the logic of the interaction with the PostgreSQL protocol.
• shardingsphere-proxy-frontend-opengauss implements the logic of the interaction with the openGauss protocol.

shardingsphere-mode

The shardingsphere-mode module provides support for ShardingSphere's running mode. The running mode is a new concept introduced in Version 5.0.0, providing you with options including the memory mode, the standalone mode, and the cluster mode to meet your needs in various application scenarios.

The structure of the module is as follows:

  ├──shardingsphere-mode-core                                                 # Table Structure Configuration

  ├──shardingsphere-mode-type

  ├    ├──shardingsphere-cluster-mode

  ├    ├     ├──shardingsphere-cluster-mode-core

  ├    ├     ├──shardingsphere-cluster-mode-repository

  ├    ├     ├     ├──shardingsphere-cluster-mode-repository-api

  ├    ├     ├     ├──shardingsphere-cluster-mode-repository-provider

  ├    ├     ├     ├     ├──shardingsphere-cluster-mode-repository-etcd

  ├    ├     ├     ├     ├──shardingsphere-cluster-mode-repository-zookeeper-curator

  ├    ├──shardingsphere-memory-mode

  ├    ├     ├──shardingsphere-memory-mode-core

  ├    ├──shardingsphere-standalone-mode

  ├    ├     ├──shardingsphere-standalone-mode-core

  ├    ├     ├──shardingsphere-standalone-mode-repository

  ├    ├     ├     ├──shardingsphere-standalone-mode-repository-api

  ├    ├     ├     ├──shardingsphere-standalone-mode-repository-provider

  ├    ├     ├     ├     ├──shardingsphere-standalone-mode-repository-file

The shardingsphere-mode-core module provides core and universal functions for different running modes, such as metadata persistence service and managing the context of metadata.

Three running modes are implemented under shardingsphere-mode-type module, and they are as follows:

Java

shardingsphere-cluster-mode    cluster mode

shardingsphere-memory-mode     memory mode

shardingsphere-standalone-mode  standalone mode

Since the memory mode does not require metadata persistence, its implementation is the simplest. It only includes the shardingsphere-memory-mode-core module and can create a context of metadata under the memory mode.

The cluster and stand-alone modes have similar module components, which are core and repository modules:

• core has the same positioning as the memory module and it is responsible for creating metadata context. Besides providing metadata persistence, the cluster mode also needs to support distributed governance function. Therefore, the core module also contains processing logic for cluster synchronization events, ensuring the dynamic online upgrading of metadata.
• The repository module defines the persistence plan under the current running mode, the api module defines necessary SPI access, and the provider module defines a detailed persistence solution. ShardingSphere has built-in persistence solutions for different modes, allowing you to use them by adding configuration. The cluster mode provides default implementation based on etcd and ZooKeeper, and the stand-alone mode provides implementation based on local documents.

shardingsphere-features

Let us look at the modules that are classified according to their features in the ShardingSphere ecosystem. You will find database discovery, encryption, read/write splitting, shadow, sharding, agent, DistSQL, SPI, and test and distribution features.

db-discovery

The shardingsphere-db-discovery module contains api, core, distsql, and spring:

• api provides rule configuration and SPI access for database discovery.
• core provides the implementation of the database discovery rule, heartbeat detection at a regular time, validator, and routing rules.
• The distsql module includes handler, parser, and statement:
  • handler is responsible for processing relevant distsql module of database discovery, including showing and modifying database discovery.
  • parser is responsible for parsing related distsql module of database discovery.
  • statement contains items of the distsql parsing results.
• The spring module contains spring-boot-starter and spring-namespace:
  • spring-boot-starter provides access to the relevant configuration of database discovery based on Spring Boot.
  • spring-namespace provides access to the relevant configuration of database discovery based on XML.

encrypt

The shardingsphere-encrypt module contains api, core, distsql, and spring:

• api includes rule configuration and SPI access to the encryption algorithm and decryption algorithm.
• core contains the implementation of the AES, MD5, and RC4 algorithms, validator, encryption rule, encrypted table metadata loading, rewriting encryption and decryption, and merging encryption and decryption results.
• distsql includes handler, parser, and statement:
  • handler is responsible for processing distsql module related to encrypt, including showing and modifying encryption rules.
  • parser is responsible for parsing distsql related to encrypt.
  • statement contains items of the distsql parsing results.
• The spring module contains spring-boot-starter and spring-namespace:
  • spring-boot-starter provides access to configurations related to encrypt based on spring-boot-starter.
  • spring-namespace provides access to configurations related to encrypt based on spring-namespace.

read/write-splitting

The shardingsphere-readwrite-splitting module contains api, core, distsql, and spring:

• api provides read/write splitting rule configuration and SPI access to the load balancing algorithm.
• core provides the implementation of read/write splitting rule and the load balancing algorithm, including the implementation of validator and routing rules.
• distsql contains handler, parser, and statement:
  • handler is responsible for processing distsql related to read/write splitting, including showing and modifying read/write splitting rules.
  • parser is responsible for parsing distsql related to read/write splitting.
  • statement contains items of the distsql parsing results.
• spring contains spring-boot-starter and spring-namespace:
  • spring-boot-starter provides access to relevant configurations of read/write splitting based on spring-boot-starter.
  • spring-namespace provides access to relevant configurations of read/write splitting based on spring-namespace.

shadow

The shardingsphere-shadow module contains api, core, distsql, and spring:

• api provides shadow database rule configuration and SPI access to the shadow algorithm.
• core provides the shadow database rule and the implementation of the shadow algorithm, including the implementation of routing rules and validator.
• distsql includes handler, parser, and statement:
  • handler is responsible for processing distsql related to the shadow database, including showing and modifying shadow rules.
  • parser is responsible for parsing distsql related to the shadow database.
  • statement contains items of the distsql parsing results.
• spring contains spring-boot-starter and spring-namespace:
  • spring-boot-starter provides access to relevant configurations of the shadow database based on spring-boot-starter.
  • spring-namespace provides access to relevant configurations of the shadow database based on spring-namespace.

sharding

The shardingSphere-sharding module contains api, core, distsql, and spring:

• api contains relevant configuration items of sharding rules, strategy, and type, as well as generates SPI access for the sharding algorithm and primary key.
• core mainly provides the implementation of the algorithm, validator, and rules. It also provides the implementation of loading, routing, rewriting, and merging metadata.
• distsql contains handler, parser, and statement:
  • handler is responsible for processing distsql related to sharding, including showing and modifying sharding rules and algorithms.
  • parser is responsible for parsing distsql related to sharding.
  • statement contains items of the distsql parsing results.
• spring contains spring-boot-starter and spring-namespace:
  • spring-boot-starter provides access to relevant sharding configurations based on spring-boot-starter.
  • spring-namespace provides access to relevant sharding configurations based on spring-namespace.

shardingsphere-agent

shardingSphere-agent includes api, core, plugins, bootstrap, and distribution:

• api provides kernel interface and abstraction items used by the agent, as well as universal configuration items.
• core module encapsulates the general capabilities of bytecode injection and provides a loading and configuration process for agent plugins, which is the basis for the work of the agent module. It also provides loading for plugin configuration and JAR add-on files.
• plugins includes logging, metrics, and tracing. It implements data gathering of observable indicators based on core modules:
  • logging provides a simple function to intercept and input log.
  • metrics implements the function of gathering often-used metrics with observability based on prometheus.
  • tracing implements the function of link data gathering based on Zipkin, Jaeger, OpenTelemetry, and SkyWalking OpenTracing. The tracing-test module is a framework providing a unit testing function for the tracing module.
• bootstrap mainly provides integration for Java agent and agent access.
• distribution provides the function of packaging. shardingsphere-agent packaging files will be output to the target directory of this module.

shardingsphere-sql-parser

The shardingsphere-sql-parser module contains dialect, engine, spi, and statement:

• dialect provides parsing for various database dialects such as MySQL, openGauss, Oracle, PostgreSQL, SQL Server, and other database dialects that use SQL92 syntax.
• engine provides an SQL parsing engine, which can parse SQL, and contains a cached syntax tree that can be used to improve performance.
• spi provides abstraction access for parser and visitor, as well as SPI access for the implementation of parsing other database dialects.
• statement provides various segments for storing parsing results, and provides some universal solutions for receiving parsed segments.

shardingsphere-distsql

In Apache ShardingSphere, the shardingsphere-distsql module provides basic functions of DistSQL, including a DistSQL syntax definition document, parsing capability, and parsed statement objects corresponding to the syntax. It mainly includes the following modules:

• shardingsphere-distsql-parser: This module provides the DistSQL syntax definition and the capability of parsing DistSQL. shardingsphere-distsql-parser provides unified parsing access for any DistSQL statement input. Different types of DistSQL will be routed to different parsers, generating statement objects.
• shardingsphere-distsql-statement: This module provides objects corresponding to DistSQL type, and it will process DistSQL according to statement objects.

shardingsphere-spi

In Apache ShardingSphere, the shardingsphere-spi module provides all SPI access and the capability of loading an SPI, representing the foundation of Apache ShardingSphere's pluggable capability. The module does not have classifications and only divides an SPI in Apache ShardingSphere into optional, ordered, required, singleton, and typed, according to their packages. The detailed structure is as follows:

├── exception

├── optional

├── ordered

├── required

├── singleton

└── typed

shardingsphere-test

The shardingsphere-test module provides integrated testing support for the function points and the application scenarios of multiple functions of ShardingSphere:

shardingsphere-test                              

   ├──shardingsphere-integration-agent-test

   ├    ├──shardingsphere-integration-agent-test-plugins

   ├    ├     ├──shardingsphere-integration-agent-test-metrics

   ├    ├     ├──shardingsphere-integration-agent-test-common

   ├    ├     ├──shardingsphere-integration-agent-test-zipkin

   ├    ├     ├──shardingsphere-integration-agent-test-jaeger

   ├    ├     ├──shardingsphere-integration-agent-test-opentelemetry                                                

   ├──shardingsphere-integration-driver-test

   ├──shardingsphere-integration-scaling-test

   ├    ├──shardingsphere-integration-scaling-test-mysql

   ├──shardingsphere-integration-test

   ├    ├──shardingsphere-integration-test-fixture

   ├    ├──shardingsphere-integration-test-suite

   ├──shardingsphere-optimize-test

   ├──shardingsphere-parser-test

   ├──shardingsphere-pipeline-test

   ├──shardingsphere-rewrite-test

   ├──shardingsphere-test-common

Let us look at the applications of these functions:

• shardingsphere-integration-agent-test: Provides integrated testing for shardingsphere-agent
• shardingsphere-integration-driver-test: Provides integrated testing for ShardingSphere's support for different databases and connection pools
• shardingsphere-integration-scaling-test: Provides integrated testing for shardingsphere-data-pipeline
• shardingsphere-integration-test: Provides integrated testing for single function and function combinations of shardingsphere-features
• shardingsphere-optimize-test: Provides integrated testing for shardingsphere-infra-federation-optimizer
• shardingsphere-parser-test: Provides integrated testing for shardingsphere-sql-parser
• shardingsphere-pipeline-test: Provides integrated testing for shardingsphere-data-pipeline
• shardingsphere-rewrite-test: Provides integrated testing for shardingsphere-infra-rewrite
• shardingsphere-test-common: Contains MockedDataSource, and is the common toolkit for all tests that need a mocked data source

shardingsphere-distribution

The shardingsphere-distribution module is used to create source code packages and ShardingSphere-JDBC and ShardingSphere-Proxy binary distribution packages:

• shardingsphere-jdbc-distribution will create a tar.gz package out of the JAR of relevant modules of ShardingSphere-JDBC (except for reliance on a third party).
• shardingsphere-proxy-distribution will create a tar.gz package out of the JAR of relevant modules of ShardingSphere-Proxy and reliance on a third party.
• shardingsphere-src-distribution will create a .zip package out of ShardingSphere project source codes (except for documents, examples, and CI configuration).

This concludes your overview of ShardingSphere's source code modules. The next two sections will give you a brief overview of ShardingSphere's license and introduction.

License introduction

ShardingSphere uses the Apache Software Foundation's license. The Foundation offers multiple licenses to distribute both software and documentation, while our community uses what is known as the Apache License 2.0.

This license was approved by the Foundation in 2004 and is part of what is known as permissive licenses, as opposed to copyleft licenses.

Copyleft licenses are so called because they require any code that is built as derivative work of the copyleft licensed software to be released under the same license as the original software.

On the other hand, permissive licenses, such as the Apache License 2.0, do not have any such requirement. This means that as a user using software such as ShardingSphere, you can do nearly anything with the code. Examples include sublicensing the code, including it in a commercial product you're building, distributing any copies or modifications of the code, or simply altering the code.

For a complete copy of the Apache License 2.0, you can consult the official Foundation's website at the following link: https://www.apache.org/licenses/LICENSE-2.0.

Version introduction

This book is based on Apache ShardingSphere version 5.0.0. The road to arriving at this version has been a long one, full of efforts, volunteer dedication, and sheer passion for open source software.

By the time this book will be released, our community will probably have released version 5.1.1. This is because, since the end of 2021, our community has opted to increase the frequency of releases.

If you consult our official website, you will see that the time period between releases has significantly been shortened. We have collectively opted for the path of frequent iteration in order to better absorb community feedback, and better share the workload across the community.

Version 5.0.0 is an especially important one, as it marked Apache ShardingSphere's evolution from middleware to a fully-fledged ecosystem capable of satisfying any database requirement and enhancing it with new features. We strive to maintain complete and historically-accurate documentation, and you will be able to find documentation for all of ShardingSphere's legacy versions on our official website.

Considering that you may or may not visit our website and GitHub repository in the future, we believe that you might want to take the leap and become an open source contributor. The next section will give you an overview of our open source community and our history, and introduce you to open source contributions in general.

Open source community

As a community, we take pride in our history, as relatively short as it may be. Our open source project may indeed be relatively young if compared to other Apache projects, but we believe that the successes we have achieved in such a short time stand as a testament to our commitment and dedication to open source.

You can trace our roots to 2015 when the JDBC project was first started. Since then, we introduced the project to the Apache Software Foundation's incubator in 2018 and quickly graduated as an Apache Top-Level Project in 2020.

The following list provides you with an overview of some important dates for our community:

• October 2015: Sharding-JDBC project initiation.
• January 18, 2016: Sharding-JDBC officially open sourced.
• May 10, 2015: Renamed as ShardingSphere.
• November 10, 2018: ShardingSphere project enters the Apache incubator.
• December 21, 2018: The first Apache ShardingSphere (incubating) process and project management committee (PPMC) meeting.
• April 21, 2019: Apache ShardingSphere version 1.0.
• April 16, 2020: ShardingSphere crowned Apache Top-Level Project.
• June 2020: ElasticJob becomes a subproject.
• June 19, 2021: ShardingSphere 5.0.0-beta version.
• July 6, 2021: ElasticJob 3.0 version.
• September 17, 2021: Four awards are given by CAICT at OSCAR Open Source Industry Conference.
• October 12, 2021: ElasticJob 3.0.1 version.
• November 10, 2021: ShardingSphere 5.0.0 GA version.
• November 13, 2021: China ShardingSphere open source community launched.
• December 11, 2021: The first Apache ShardingSphere dev meetup.
• February 16, 2022: Apache ShardingSphere 5.1.0 version.

As you can see, the development has been fairly fast. For a more extensive roadmap, you can consult our official website. The next list provides you with some of our community milestones:

• 2016: 1.x Version Enhanced Database Driver | 1,455 Stars | 7 Contributors
• 2017: 2.x Version Distributed Governance | 3,134 Stars | 15 Contributors
• 2018: 3.x Version Database Proxy & ShardingSphere Project Enters the Apache Incubator | 5,992 Stars | 44 Contributors
• 2020: 4.x Version Became One of the Top-Level Apache Projects | 12,964 Stars | 208 Contributors
• 2021: 5.x Version To Pluggable and The Database Plus Concept is Born | 14,612 Stars | 302 Contributors
• 2023: 6.x Version To Developer Simplified SPI Makes it Easier for Developers to Contribute and Use ShardingSphere
• 2025: 7.x Version To Ecosystem Provide More Functions and Support More Databases Build Upper-Level Ecosystem and Standard for Heterogeneous Database

Our community is focused on expanding and continuously improving. For these reasons, we keep an up-to-date milestones list on our GitHub page if you want the latest updates.

Open source contribution

Contributing to open source is certainly an opportunity you should consider. The advantages it entails are many and include learning or improving your skills, connecting with great people from all over the world, and raising your professional profile. In fact, it was open source that brought the three authors of this book together and created the professional opportunities we are currently working on.

You can contribute by submitting your code to the ShardingSphere repository on GitHub, but there are other contribution avenues as well. You can contribute with documentation writing or translation, website building or design, community building efforts, social media management, and more. We believe that the focus should not be placed on what someone contributes – for us, first and foremost, what matters is the passion for open source. Being interested in our project and dedicating some of your precious time to making our community better, and ultimately advancing the project, makes you a contributor. It can range from asking questions, to providing new features as code patches. Contributions can be made in many ways.

The first step is to get involved. Dive into the Apache ShardingSphere concept, say hi to the community, and then get to action by either working on the documentation or contributing code supporting other users.

You might just be surprised how welcoming and open folks are in the open source world or the ShardingSphere community. You will soon find that the more visible and engaged you are in a project, the more fun you will have and the more access you will have to valuable advice and feedback.

The community's structure is very flat, although you will see that we have a project management committee (PMC), which can be accessed by nomination and voting once you get selected to rank up from simple contributor to committer.

As a community, we follow the Apache community's process for accepting a new committer. The contributors that are most active get invited by the PMC and other committers to become a committer. The perks associated with being a committer include the ability to write access to the project repository and resources, not just read source code files.

A committer has the privilege to write and commit code and create pull requests to the default branch of the repository and, in most cases, reviewers are also committers, as you need to understand the code to review a pull request. In other words, a committer is authorized to merge user contributions into the project.

Website and documentation

In this section, we will provide you with a series of useful links and resources to consult or join our community and more. We are constantly expanding the resources available online to the community to facilitate the understanding of what Apache ShardingSphere is and are constantly expanding the ways we engage as a community. For example, most recently, we are starting to gather both virtually and in person as a community for developer meetups.

Websites

If you search for Apache ShardingSphere on the most popular search engines, you will find that we are expanding across multiple platforms and websites – after all, this book is the perfect example of our community-building efforts.

You will also find some websites that are in various languages, and if interested, feel free to start your own in your preferred language. Nevertheless, for the official channels operated directly by our community, you can refer to the following list:

• Apache ShardingSphere official website: https://shardingsphere.apache.org
• GitHub official repository: https://github.com/apache/shardingsphere
• ShardingSphere's official blog: https://shardingsphere.apache.org/blog/en/material/
• ShardingSphere's official medium blog: https://shardingsphere.medium.com

Channels

If you'd like to connect with us, and we sincerely hope that you do, you can find us and other community members on these channels. We keep in touch on social media and have recently started an official Slack Community channel for quicker discussions or troubleshooting:

• Twitter: @ShardingSphere
• LinkedIn: https://www.linkedin.com/showcase/apache-shardingsphere
• Slack community: https://apacheshardingsphere.slack.com/join/shared_invite/zt-sbdde7ie-SjDqo9~I4rYcR18bq0SYTg#/shared-invite/email

Concluding note

We hope that this appendix will prove useful to you in the future to support you in operating Apache ShardingSphere, and ultimately, that this open source project will allow you to get the best out of your databases.

If what you are looking for cannot be found in this appendix, you can drop a line to any of us or reach out to our community.