配置
sqlx 支持零侵入的方式使用，所有功能都可通过配置实现。以下是详细的配置说明和示例。
基本配置
在 application.yml 或 application.properties 中进行配置。
启用 SQLX
sqlx:
enabled: true
sqlx 可以显示的启用和禁用,如果引入了 sqlx-spring-boot-starter jar 包但是没有显示的配置 sqlx.enabled=true 则默认为启用状态。
如果要关闭 sqlx 您可以配置禁用 sqlx.enabled=false. 同时配置文件中可保留原有的数据源配置,这样可做到快速切换。例如:
spring:
datasource:
url: jdbc:h2:mem:~/test1;FILE_LOCK=SOCKET;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=TRUE;AUTO_RECONNECT=TRUE;IGNORECASE=TRUE;
driver-class-name: org.h2.Driver
username: sa
password: pwd
sqlx:
enabled: false
SQL 解析器
sqlx:
enabled: true
sql-parsing:
sql-parser-class: io.github.sqlx.sql.parser.SimpleSqlParser
sqlx 支持使用自定义的 SQL 解析器，通过配置 sqlx.sql-parsing.sql-parser-class 来指定解析器类。如果没有指定默认使用 JSqlParser.
用户自行扩展的 SQL 解析器需要实现 SqlParser 接口或继承 AbstractSqlParser。
SQL 解析失败行为
sqlx:
sql-parsing:
sql-parsing-fail-behavior: warning
当解析 SQL 失败时，可以选择以下行为（默认为 WARNING）：
- IGNORE : 忽略异常,并将 SQL 类型设置为
OTHER类型，把 SQL 视作一条写语句; - WARNING: 输出警告日志，并将 SQL 类型设置为
OTHER类型，把 SQL 视作一条写语句; - FAILING: 抛出
SqlParseException异常，并终止程序运行;
SQL 类型设置为 OTHER 类型会被视为一条写语句，默认路由到写库执行.
负载均衡
sqlx:
clusters:
- name: cluster_0
defaulted: true
read-load-balance-class: io.github.sqlx.loadbalance.WeightRandomLoadBalance
write-load-balance-class: io.github.sqlx.loadbalance.WeightRandomLoadBalance
writable-nodes:
- write_0
readable-nodes:
- read_0
- read_1
针对集群可配置不同的负载均衡策略。如果没有配置默认使用 io.github.sqlx.loadbalance.WeightRandomLoadBalance.
数据源配置
您可以灵活地配置任意多个数据源，以满足不同的应用需求。以下是配置示例:
sqlx:
enabled: true
data-sources:
- name: write_0 # 数据源名称需唯一
weight: 99 # 数据源权重，用于负载均衡
defaulted: true # 是否为默认数据源
data-source-class: com.zaxxer.hikari.HikariDataSource
init-method: # 初始化方法
destroy-method: close # 销毁方法
init-sql-script: classpath:init.sql # 初始化 SQL 脚本
heartbeat-sql: select 1 # 心跳检查 SQL
heartbeat-interval: 3000 # 心跳检查间隔，单位毫秒
props: # 数据源参数配置,参数名称和所使用的数据源类字段名保持一致即可
driverClassName: org.h2.Driver
jdbcUrl: jdbc:h2:mem:~/test1;FILE_LOCK=SOCKET;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=TRUE;AUTO_RECONNECT=TRUE;IGNORECASE=TRUE;
username: sa
password: pwd
minIdle: 5
maxPoolSize: 30
connectionTimeout: 30000
isAutoCommit: false
isReadOnly: false
配置说明
- name: 数据源的唯一标识符。
- weight: 数据源的权重，用于负载均衡。权重越高，被选中的概率越大。
- defaulted: 指定该数据源是否为默认数据源,只允许指定一个。
- data-source-class: 数据源实现类，通常为连接池类。
- init-method: 数据源初始化时调用的方法。
- destroy-method: 数据源销毁时调用的方法。
- init-sql-script: 初始化时执行的 SQL 脚本。
- heartbeat-sql: 心跳检查 SQL, 用于检测数据源是否可用,对于不可用的数据源状态会被标记为
DOWN后不参与负载均衡。 - heartbeat-interval: 心跳检查间隔，单位毫秒。
- props: 数据源的连接参数，需与数据源类的字段名一致。
注意
props 配置中驱动类名称,数据库连接地址,用户,密码配置是必须的,固定使用参数名 driverClassName , jdbcUrl 或 jdbc-url 或 url , username , password.
其他参数名称则保持和您所使用的数据库连接池的实现类字段名一致即可。例如,对于 HikariCP 连接池,参数名称为 driverClassName , jdbcUrl , username , password , minIdle , maxPoolSize , connectionTimeout , isAutoCommit , isReadOnly 等。
对于 Druid 连接池,参数名称为 initialSize , minIdle , timeBetweenEvictionRunsMillis , minEvictableIdleTimeMillis , validationQuery , testWhileIdle , testOnBorrow , testOnReturn , poolPreparedStatements 等。
如果您发现您所使用的数据库连接池的参数没有被正确设置,可以通过扩展 io.github.sqlx.integration.datasource.DataSourceInitializer 接口
自行初始化数据源，并将其注册到 Spring 容器中即可。
集群配置
您可以灵活地配置任意多个集群，以满足不同的应用需求。集群配置并不是必须的,当您的多个数据源之间不存在关联关系时您可以不配置集群.
以下是配置示例:
sqlx:
enabled: true
clusters: # 集群配置
- name: cluster_0 # 集群名称需唯一
defaulted: true # 当存在多个集群时指定是否是默认集群
writable-nodes:
- write_0
readable-nodes:
- read_0
- read_1
- write_0
- name: cluster_1
writable-nodes:
- write_0
readable-nodes:
- read_1
注意:
- 集群中必须包含至少一个可写数据源和一个可读数据源。
- 集群中的数据源使用的数据库必须是相同类型的。
- 当您的应用中配置了多个集群时，必须指定默认集群。
监控配置
SQLX 提供了丰富的监控功能，可以通过以下配置启用和管理：
sqlx:
enabled: true
metrics:
enabled: true # 是否启用监控功能
username: admin # 监控用户名
password: adminpw # 监控密码
enable-routing-metrics: true
enable-sql-metrics: true
enable-transaction-metrics: true
collect-scope: SLOW # 监控采集范围, 支持 SLOW (只采集慢SQL和慢事务)、ALL (采集所有)
slow-sql-millis: 300 # 慢 SQL 阈值，单位为毫秒
slow-transaction-millis: 3000 # 慢事务阈值，单位为毫秒
file-directory: /usr/local/sqlx-metrics # 保存采集数据的文件目录
data-retention-duration: 2h # 数据保留时长，支持 s、m、h、d、w、M、y
#collect-mode: ASYNC # 采集方式，支持 SYNC (同步)、ASYNC (异步)
#collect-core-pool-size: 10
# collect-max-pool-size: 30
# collect-keep-alive-millis: 10000
# collect-queue-capacity: 3000
配置说明
- enabled: 是否启用监控功能。设置为 true 启用监控。
- username: 监控系统的用户名，用于访问监控数据。
- password: 监控系统的密码，用于访问监控数据。
- enable-routing-metrics: 是否启用路由监控功能。
- enable-sql-metrics: 是否启用 SQL 监控功能。
- enable-transaction-metrics: 是否启用事务监控功能。
- collect-scope: 监控采集范围。可以设置为 SLOW（只采集慢 SQL 和慢事务）或 ALL（采集所有 SQL 和事务）。
- slow-sql-millis: 慢 SQL 的阈值，单位为毫秒。超过此时间的 SQL 将被标记为慢 SQL。
- slow-transaction-millis: 慢事务的阈值，单位为毫秒。超过此时间的事务将被标记为慢事务。
- file-directory: 保存采集数据的文件目录。监控数据将被存储在此目录中。
- data-retention-duration: 数据保留时长。支持的单位包括秒（s）、分钟（m）、小时（h）、天（d）、周（w）、月（M）、年（y）。
可选配置
- collect-mode: 采集方式，支持 SYNC（同步）和 ASYNC（异步）。异步采集可以提高性能。
- collect-core-pool-size: 异步采集的核心线程池大小。
- collect-max-pool-size: 异步采集的最大线程池大小。
- collect-keep-alive-millis: 线程池中空闲线程的存活时间，单位为毫秒。
- collect-queue-capacity: 异步采集队列的容量。
注意
默认采用同步收集，收集范围只针对 SLOW 采集范围和异常采集范围。不建议您进行全量采集，因为这样会导致大量数据写入，影响性能同时占用更多磁盘空间。
SQL 路由配置
SQLX 提供了灵活的 SQL 路由功能，允许您通过切入点表达式来定义 SQL 的路由规则。通过以下配置，您可以指定哪些 SQL 语句应该路由到哪个集群和节点：
sqlx:
enabled: true
pointcuts:
- expression: "execution(* com.foo.ServiceA.fun1())" # 切入点表达式，支持 Spring AOP 的切入点表达式
cluster: cluster_0 # 集群名称
nodes: # 节点名称
- write_0
- read_0
propagation: true # 是否接受上层方法传播
配置说明
- expression: 切入点表达式，用于匹配方法调用。支持 Spring AOP 的切入点表达式语法。通过这种方式，您可以精确地指定哪些方法调用会触发 SQL 路由。
- cluster: 指定 SQL 语句应该路由到的集群名称。集群是由多个数据源节点组成的逻辑分组。
- nodes: 指定 SQL 语句应该路由到的节点名称列表。当配置了 cluster 时，nodes 必须是该集群中的节点。
- propagation: 指定是否接受上层方法的传播。如果设置为 true，则当前方法的 SQL 路由规则会继承自调用它的上层方法。
注意事项
-
确保切入点表达式准确无误，以避免不必要的 SQL 路由。
-
在配置多个集群时，确保每个集群的节点配置正确，并且集群中至少包含一个可写数据源。
-
使用 propagation 时，注意方法调用链的传播影响，以避免意外的 SQL 路由行为。
-
通过这些配置，您可以灵活地管理 SQL 路由功能，确保在不同的操作场景下使用合适的集群和节点，从而提高应用的性能和可靠性。
通过以上配置，您可以灵活地管理和使用 sqlx 的多数据源和 SQL 路由功能。如果需要更多帮助，请参考官方文档或联系社区支持。