YAML Configuration

Introduction

YAML configuration provides interaction with ShardingSphere JDBC through configuration files. When used with the governance module together, the configuration of persistence in the configuration center is YAML format.

YAML configuration is the most common configuration mode, which can omit the complexity of programming and simplify user configuration.

Usage

Create Simple DataSource

The ShardingSphereDataSource created by YamlShardingSphereDataSourceFactory implements the standard JDBC DataSource interface.

  1. // Indicate YAML file path
  2. File yamlFile = // ...
  4. DataSource dataSource = YamlShardingSphereDataSourceFactory.createDataSource(yamlFile);

Create Governance DataSource

The GovernanceShardingSphereDataSource created by YamlGovernanceShardingSphereDataSourceFactory implements the standard JDBC DataSource interface.

  1. // Indicate YAML file path
  2. File yamlFile = // ...
  4. DataSource dataSource = YamlGovernanceShardingSphereDataSourceFactory.createDataSource(yamlFile);

Use DataSource

Developer can choose to use native JDBC or ORM frameworks such as JPA or MyBatis through the DataSource.

Take native JDBC usage as an example:

  1. DataSource dataSource = // Use Apache ShardingSphere factory to create DataSource
  2. String sql = "SELECT i.* FROM t_order o JOIN t_order_item i ON o.order_id=i.order_id WHERE o.user_id=? AND o.order_id=?";
  3. try (
  4.         Connection conn = dataSource.getConnection();
  5.         PreparedStatement ps = conn.prepareStatement(sql)) {
  6.     ps.setInt(1, 10);
  7.     ps.setInt(2, 1000);
  8.     try (ResultSet rs = preparedStatement.executeQuery()) {
  9.         while(rs.next()) {
  10.             // ...
  11.         }
  12.     }
  13. }

YAML Configuration Item

schemaName Configuration

This parameter is optional. If it is not configured, logic_db is used as the schemaName by default. schemaName can be understood as the schema in the database, the alias of the datasource in JDBC Through this parameter and the management module, JDBC and PROXY can be online at the same time, and the configuration can be shared.

Configuration Example
  1. schemaName: sharding_db

Data Source Configuration

It is divided into single data source configuration and multi data source configuration. Single data source configuration used for data encryption rules; and multi data source configuration used for fragmentation, readwrite-splitting and other rules. If features such as encryption and sharding are used in combination, a multi data source configuration should be used.

Single Data Source Configuration

Configuration Example
  1. dataSource: !!org.apache.commons.dbcp2.BasicDataSource
  2.   driverClassName: com.mysql.jdbc.Driver
  3.   url: jdbc:mysql://127.0.0.1:3306/ds_name
  4.   username: root
  5.   password: root
Configuration Item Explanation
  1. dataSource: # <!!Data source pool implementation class> `!!` means class instantiation
  2.   driverClassName: # Class name of database driver
  3.   url: # Database URL
  4.   username: # Database username
  5.   password: # Database password
  6.     # ... Other properties for data source pool

Multi Data Source Configuration

Configuration Example
  1. dataSources:
  2.   ds_0: !!org.apache.commons.dbcp2.BasicDataSource
  3.     driverClassName: com.mysql.jdbc.Driver
  4.     url: jdbc:mysql://127.0.0.1:3306/ds_0
  5.     username: sa
  6.     password:
  7.   ds_1: !!org.apache.commons.dbcp2.BasicDataSource
  8.     driverClassName: com.mysql.jdbc.Driver
  9.     url: jdbc:mysql://127.0.0.1:3306/ds_1
  10.     username: sa
  11.     password:
Configuration Item Explanation
  1. dataSources: # Data sources configuration, multiple <data-source-name> available
  2.   <data-source-name>: # <!!Data source pool implementation class> `!!` means class instantiation
  3.     driverClassName: # Class name of database driver
  4.     url: # Database URL
  5.     username: # Database username
  6.     password: # Database password
  7.     # ... Other properties for data source pool

Rule Configuration

Begin to configure with the rule alias to configure multiple rules.

Configuration Example

  1. rules:
  2. -! XXX_RULE_0
  3.   xxx
  4. -! XXX_RULE_1
  5.   xxx

Configuration Item Explanation

  1. rules:
  2. -! XXX_RULE # Rule alias, `-` means can configure multi rules
  3.   # ... Specific rule configurations

Please refer to specific rule configuration for more details.

Properties Configuration

Configuration Example

  1. props:
  2.   xxx: xxx

Configuration Item Explanation

  1. props:
  2.   xxx: xxx # Properties key and value

Please refer to specific rule configuration for more details.

YAML Syntax Explanation

!! means instantiation of that class

! means self-defined alias

- means one or multiple can be included

[] means array, can substitutable with - each other