1.4. 参考
1.4.1. 通用数据源配置参考
在构建时修复的配置属性 - 所有其他配置属性在运行时可覆盖
配置属性 | 类型 | default |
如果存在 smallrye-health 扩展,是否发布健康检查。 这是一个全局设置,不特定于数据源。
环境变量: | 布尔值 |
|
当存在指标扩展时,数据源指标是否发布。 这是一个全局设置,不特定于数据源。 注意 这与需要在 JDBC 数据源级别上设置的"jdbc.enable-metrics"属性不同,以启用该数据源的指标集合。
环境变量: | 布尔值 |
|
我们要连接到的数据库类型(如 h2、postgresql…)。
环境变量: | string | |
我们要连接的数据库版本(例如'10.0'). 小心
此处设置的版本号应遵循与数据库的 JDBC 驱动程序 作为规则,此处设置的版本应尽可能高,但必须小于或等于应用程序将连接到的任何数据库的版本。 高版本将允许更好的性能和使用更多功能(例如 Hibernate ORM 可能会生成更高效的 SQL,避免临时解决方案和利用更多数据库功能),但是如果它高于您要连接的数据库版本,则可能会导致运行时异常(例如 Hibernate ORM 可能会生成无效的 SQL,您的数据库将拒绝)。 有些扩展(如 Hibernate ORM 扩展)会尝试在启动时根据实际数据库版本检查此版本,从而导致实际版本较低或只是无法访问数据库时启动失败。 此属性的默认值特定于每个扩展; Hibernate ORM 扩展将默认为它所支持的最旧版本。
环境变量: | string | |
如果启用了数据源的常规健康检查,则是否应从健康检查中排除此特定数据源。 默认情况下,健康检查包含所有配置的数据源(如果已启用)。
环境变量: | 布尔值 |
|
此数据源是否应在运行时处于活动状态。 如果数据源不是活跃的,则不会从应用程序开始,访问对应的 Datasource CDI Bean 将失败,这意味着此数据源的用户(如 Hibernate ORM 持久性单元)将无法启动,除非它们也不活跃。
环境变量: | 布尔值 |
|
数据源用户名
环境变量: | string | |
数据源密码
环境变量: | string | |
凭证供应商名称
环境变量: | string | |
凭据 provider bean 名称。
这是实施
对于 Vault,凭据供应商 bean 名称为
环境变量: | string | |
类型 | default | |
此 Dev Service 是否应该以 dev 模式或测试开头。 Dev 服务默认是启用的,除非明确设置了连接配置(如 JDBC URL 或被动客户端 URL)。
环境变量: | 布尔值 | |
基于容器的 Dev Service 供应商的容器镜像名称。 如果提供商不是基于容器的数据库,如 H2 或 Derby,则这无效。
环境变量: | string | |
传递给容器的环境变量。
环境变量: | Map<String,String> | |
为其他容器配置传递的通用属性。 此处定义的属性是特定于数据库,并在每个数据库 dev 服务实现中特别解释。
环境变量: | Map<String,String> | |
添加到数据库连接 URL 中的通用属性。
环境变量: | Map<String,String> | |
dev 服务将侦听的可选固定端口。 如果没有定义,则会随机选择端口。
环境变量: | int | |
容器 start 命令,用于基于容器的 Dev 服务提供程序。 如果提供商不是基于容器的数据库,如 H2 或 Derby,则这无效。
环境变量: | string | |
如果此 Dev Service 支持覆盖它,则使用数据库名称。
环境变量: | string | |
如果此 Dev Service 支持覆盖它,则使用的用户名。
环境变量: | string | |
如果此 Dev 服务支持覆盖密码,则使用密码。
环境变量: | string | |
要从 classpath 加载并应用到 Dev Service 数据库的 SQL 脚本的路径。 如果提供商不是基于容器的数据库,如 H2 或 Derby,则这无效。
环境变量: | string | |
要映射到容器的卷。 map 键对应于主机位置;map 值是容器位置。如果主机位置以 "classpath:" 开头,映射会从 classpath 中加载资源,且具有只读权限。 使用文件系统位置时,卷将生成有读写权限,可能会导致文件系统中的数据丢失或修改。 如果提供商不是基于容器的数据库,如 H2 或 Derby,则这无效。
环境变量: | Map<String,String> | |
是否要在 dev 模式会话或测试套件执行后 保持 Dev Service 容器运行,以便在下一个 dev 模式会话或测试套件中执行中重复使用它们。 在 dev 模式会话或测试套件执行中,只要其配置(用户名、密码、环境、端口绑定、端口绑定、…)的配置不会改变。此功能针对在 Quarkus 没有运行时保持容器保持运行,以便在运行时重复使用它们。 警告
这个功能需要在
默认情况下,此配置属性被设置为
环境变量: | 布尔值 |
|
1.4.2. JDBC 配置参考
在构建时修复的配置属性 - 所有其他配置属性在运行时可覆盖
配置属性 | 类型 | default |
如果我们为此数据源创建 JDBC 数据源。
环境变量: | 布尔值 |
|
数据源驱动程序类名称
环境变量: | string | |
是否要使用常规 JDBC 事务、XA 还是禁用所有事务处理功能。
启用 XA 时,您将需要一个实现
环境变量: | 启用 :将 JDBC 数据源与 Quarkus 的 JTA TransactionManager 集成。这是默认值。
XA :与 disabled :禁用与 Narayana TransactionManager 的 Agroal 集成。这通常是一个好主意,且仅在特殊情况下很有用:请确保在不深入了解影响的情况下不使用此功能。 | enabled |
启用数据源指标集合。如果未指定,则当指标扩展处于活跃状态时,将默认启用收集指标。
环境变量: | 布尔值 | |
启用 JDBC 追踪。默认禁用此选项。
环境变量: | 布尔值 |
|
启用 OpenTelemetry JDBC 检测。
环境变量: | 布尔值 |
|
数据源 URL
环境变量: | string | |
池的初始大小。通常,您要将初始大小设置为至少与最小大小匹配,但这不强制,允许那些希望在引导时对连接的 lazy 初始化的架构,同时在启动时可以保持最小池大小。
环境变量: | int | |
数据源池最小值
环境变量: | int |
|
数据源池最大大小
环境变量: | int |
|
我们在后台验证闲置连接的时间间隔。
设置为
环境变量: |
| |
对闲置时间超过指定间隔的连接执行前台验证。
环境变量: | ||
取消获取新连接前的超时时间
环境变量: |
| |
检查连接泄漏的时间间隔。
环境变量: |
| |
我们试图删除闲置连接的时间间隔。
环境变量: |
| |
连接的最大生命周期。
环境变量: |
| |
事务隔离级别。
环境变量: |
| |
收集并显示泄漏连接中的额外故障排除信息。
环境变量: | 布尔值 |
|
在返回到池后,允许刷新连接。默认情况下不启用。
环境变量: | 布尔值 |
|
启用后,Agroal 能够在不关闭所有打开的声明的情况下,在返回到池时产生警告。这与跟踪打开的连接无关。禁用峰值性能,但仅在有高度信任时不会发生泄漏。
环境变量: | 布尔值 |
|
第一次使用连接时执行的查询。
环境变量: | string | |
执行的查询以验证连接。
环境变量: | string | |
无论空闲状态如何,强制在获取(foreground 验证)前进行连接验证。
由于每次调用时执行验证的开销,建议依赖默认的空闲验证,并把它保留为
环境变量: | 布尔值 |
|
禁用池以防止重复使用连接。当外部池管理 Connections 的生命周期时,请使用此选项。
环境变量: | 布尔值 |
|
在获取连接时需要活跃的事务。建议用于生产环境。警告:一些扩展会获取连接,而无需为 schema 更新和模式验证等操作保留事务。在这些情况下,将此设置设置为 STRICT 可能会导致失败。
环境变量: |
| |
创建新连接时,将传递给 JDBC 驱动程序的其他未指定属性。
环境变量: | Map<String,String> | |
启用 JDBC 追踪。
环境变量: | 布尔值 |
|
只使用活跃 Span 的 trace 调用
环境变量: | 布尔值 |
|
忽略特定查询被追踪
环境变量: | string |
|
启用 OpenTelemetry JDBC 检测。
环境变量: | 布尔值 |
|
要写入持续时间值,请使用标准 java.time.Duration
格式。如需更多信息,请参阅 Duration#parse ()Java API 文档。
您还可以使用简化的格式,从数字开始:
- 如果值只是一个数字,它代表时间(以秒为单位)。
-
如果值为数字,后跟
ms
,代表时间(毫秒)。
在其他情况下,简化的格式被转换为 java.time.Duration
格式以进行解析:
-
如果该值是一个数字,后跟
h
、m
或s
,则前缀为PT
。 -
如果值为数字,后跟
d
,则会以P
为前缀。
1.4.3. JDBC URL 参考
每个支持的数据库都包含不同的 JDBC URL 配置选项。以下部分概述每个数据库 URL 和官方文档的链接。
1.4.3.1. DB2
jdbc:db2://<serverName>[:<portNumber>]/<databaseName>[:<key1>=<value>;[<key2>=<value2>;]]
- Example
-
jdbc:db2://localhost:50000/MYDB:user=dbadm;password=dbadm;
有关 URL 语法和其他支持选项的更多信息,请参阅 官方文档。
1.4.3.2. Derby
jdbc:derby:[//serverName[:portNumber]/][memory:]databaseName[;property=value[;property=value]]
- Example
-
jdbc:derby://localhost:1527/myDB
,jdbc:derby:memory:myDB;create=true
Derby 是一个嵌入式数据库,可作为服务器运行,它基于文件,也可以完全在内存中运行。以上列出了所有这些选项。
如需更多信息,请参阅 官方文档。
1.4.3.3. H2
jdbc:h2:{ {.|mem:}[name] | [file:]fileName | {tcp|ssl}:[//]server[:port][,server2[:port]]/name }[;key=value…]
- Example
-
jdbc:h2:tcp://localhost/~/test
,jdbc:h2:mem:myDB
H2 是一个可在嵌入式或服务器模式下运行的数据库。它可以使用文件存储或完全在内存中运行。以上列出了所有这些选项。
如需更多信息,请参阅 官方文档。
1.4.3.4. MariaDB
jdbc:mariadb:[replication:|failover:|sequential:|aurora:]//<hostDescription>[,<hostDescription>…]/[database][?<key1>=<value1>[&<key2>=<value2>]]
hostDescription:: < host>[:<portnumber>] or address=(host=<host>)[(port=<portnumber>)][(type=(master|slave)
]]
- Example
-
jdbc:mariadb://localhost:3306/test
如需更多信息,请参阅 官方文档。
1.4.3.5. Microsoft SQL 服务器
jdbc:sqlserver://[serverName[\instanceName][:portNumber]][;property=value[;property=value]]
- Example
-
jdbc:sqlserver://localhost:1433;databaseName=AdventureWorks
Microsoft SQL Server JDBC 驱动程序与其他驱动程序的工作方式基本相同。
如需更多信息,请参阅 官方文档。
1.4.3.6. MySQL
jdbc:mysql:[replication:|failover:|sequential:|aurora:]//<hostDescription>[,<hostDescription>…]/[database][?<key1>=<value1>[&<key2>=<value2>]]
hostDescription:: < host>[:<portnumber>] or address=(host=<host>)[(port=<portnumber>)][(type=(master|slave)
]]
- Example
-
jdbc:mysql://localhost:3306/test
如需更多信息,请参阅 官方文档。
1.4.3.6.1. MySQL 限制
当将 Quarkus 应用程序编译到原生镜像时,对 JMX 和 Oracle Cloud Infrastructure (OCI)集成的 MySQL 支持会被禁用,因为它们与 GraalVM 原生镜像不兼容。
- 缺少 JMX 支持是以原生模式运行的自然结果,不太可能被解决。
- 不支持与 OCI 集成。
1.4.3.7. Oracle
jdbc:oracle:driver_type:@database_specifier
- Example
-
jdbc:oracle:thin:@localhost:1521/ORCL_SVC
如需更多信息,请参阅 官方文档。
1.4.3.8. PostgreSQL
jdbc:postgresql:[//][host][:port][/database][?key=value…]
- Example
-
jdbc:postgresql://localhost/test
不同部分的默认值如下:
主机
- localhost
port
- 5432
database
- 与用户名相同
有关附加参数的更多信息,请参阅 官方文档。
1.4.4. Quarkus 扩展和数据库驱动程序参考
下表列出了内置的 db-kind
值、对应的 Quarkus 扩展以及这些扩展使用的 JDBC 驱动程序。
使用其中一个内置数据源类型时,可以自动解析 JDBC 和 Reactive 驱动程序,以匹配这些表中的值。
数据库类型 | Quarkus 扩展 | 驱动程序 |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
数据库类型 | Quarkus 扩展 | 驱动 |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
在大多数情况下,这个自动解析都适用,因此不需要驱动程序配置。
1.4.5. 被动数据源配置参考
在构建时修复的配置属性 - 所有其他配置属性在运行时可覆盖
配置属性 | 类型 | default |
如果我们为此数据源创建一个被动数据源。
环境变量: | 布尔值 |
|
准备语句是否应在客户端上缓存。
环境变量: | 布尔值 |
|
数据源 URL。 如果设置了多个值,此数据源将创建一个包含服务器列表而非单个服务器的池。池在连接建立过程中对服务器选择使用 round-robin 负载均衡。请注意,某些驱动程序可能不适用于此上下文中的多个值。
环境变量: | 字符串列表 | |
数据源池最大大小。
环境变量: | int |
|
创建新连接对象时,池会为其分配事件循环。
当将
环境变量: | int | |
所有服务器证书是否应信任。
环境变量: | 布尔值 |
|
默认禁用 PEM Trust config。
环境变量: | 布尔值 |
|
以逗号分隔的信任证书文件列表(Pem 格式)。
环境变量: | 字符串列表 | |
JKS 配置默认为禁用。
环境变量: | 布尔值 |
|
密钥文件的路径(JKS 格式)。
环境变量: | string | |
密钥文件的密码。
环境变量: | string | |
PFX 配置默认为禁用。
环境变量: | 布尔值 |
|
密钥文件的路径(PFX 格式)。
环境变量: | string | |
密钥的密码。
环境变量: | string | |
默认禁用 PEM Key/cert 配置。
环境变量: | 布尔值 |
|
以逗号分隔的到密钥文件的路径列表(Pem 格式)。
环境变量: | 字符串列表 | |
以逗号分隔的证书文件的路径列表(Pem 格式)。
环境变量: | 字符串列表 | |
JKS 配置默认为禁用。
环境变量: | 布尔值 |
|
密钥文件的路径(JKS 格式)。
环境变量: | string | |
密钥文件的密码。
环境变量: | string | |
PFX 配置默认为禁用。
环境变量: | 布尔值 |
|
密钥文件的路径(PFX 格式)。
环境变量: | string | |
密钥的密码。
环境变量: | string | |
第一次尝试时无法建立池连接的重新连接次数。
环境变量: | int |
|
第一次尝试时无法建立池连接之间的间隔。
环境变量: |
| |
应检查服务器的身份时要使用的主机名验证算法。应为
环境变量: | string |
|
连接在关闭前在池中保持未使用的最长时间。
环境变量: |
| |
连接保留在池中的最长时间,之后将根据需要关闭并替换。
环境变量: |
| |
设置为 true,以在数据源间共享池。当未设置特定名称时,可以按名称区分多个共享池,则使用
环境变量: | 布尔值 |
|
设置池名称,在池在数据源之间共享时使用,否则忽略。
环境变量: | string | |
在启动新连接时,通过 Reactive SQL Client 直接传递给数据库的其他未指定属性。
环境变量: | Map<String,String> | |
类型 | default | |
如果我们为此数据源创建一个被动数据源。
环境变量: | 布尔值 |
|
准备语句是否应在客户端上缓存。
环境变量: | 布尔值 |
|
数据源 URL。 如果设置了多个值,此数据源将创建一个包含服务器列表而非单个服务器的池。池在连接建立过程中对服务器选择使用 round-robin 负载均衡。请注意,某些驱动程序可能不适用于此上下文中的多个值。
环境变量: | 字符串列表 | |
数据源池最大大小。
环境变量: | int |
|
创建新连接对象时,池会为其分配事件循环。
当将
环境变量: | int | |
所有服务器证书是否应信任。
环境变量: | 布尔值 |
|
默认禁用 PEM Trust config。
环境变量: | 布尔值 |
|
以逗号分隔的信任证书文件列表(Pem 格式)。
环境变量: | 字符串列表 | |
JKS 配置默认为禁用。
环境变量: | 布尔值 |
|
密钥文件的路径(JKS 格式)。
环境变量: | string | |
密钥文件的密码。
环境变量: | string | |
PFX 配置默认为禁用。
环境变量: | 布尔值 |
|
密钥文件的路径(PFX 格式)。
环境变量: | string | |
密钥的密码。
环境变量: | string | |
默认禁用 PEM Key/cert 配置。
环境变量: | 布尔值 |
|
以逗号分隔的到密钥文件的路径列表(Pem 格式)。
环境变量: | 字符串列表 | |
以逗号分隔的证书文件的路径列表(Pem 格式)。
环境变量: | 字符串列表 | |
JKS 配置默认为禁用。
环境变量: | 布尔值 |
|
密钥文件的路径(JKS 格式)。
环境变量: | string | |
密钥文件的密码。
环境变量: | string | |
PFX 配置默认为禁用。
环境变量: | 布尔值 |
|
密钥文件的路径(PFX 格式)。
环境变量: | string | |
密钥的密码。
环境变量: | string | |
第一次尝试时无法建立池连接的重新连接次数。
环境变量: | int |
|
第一次尝试时无法建立池连接之间的间隔。
环境变量: |
| |
应检查服务器的身份时要使用的主机名验证算法。应为
环境变量: | string |
|
连接在关闭前在池中保持未使用的最长时间。
环境变量: |
| |
连接保留在池中的最长时间,之后将根据需要关闭并替换。
环境变量: |
| |
设置为 true,以在数据源间共享池。当未设置特定名称时,可以按名称区分多个共享池,则使用
环境变量: | 布尔值 |
|
设置池名称,在池在数据源之间共享时使用,否则忽略。
环境变量: | string | |
在启动新连接时,通过 Reactive SQL Client 直接传递给数据库的其他未指定属性。
环境变量: | Map<String,String> |
要写入持续时间值,请使用标准 java.time.Duration
格式。如需更多信息,请参阅 Duration#parse ()Java API 文档。
您还可以使用简化的格式,从数字开始:
- 如果值只是一个数字,它代表时间(以秒为单位)。
-
如果值为数字,后跟
ms
,代表时间(毫秒)。
在其他情况下,简化的格式被转换为 java.time.Duration
格式以进行解析:
-
如果该值是一个数字,后跟
h
、m
或s
,则前缀为PT
。 -
如果值为数字,后跟
d
,则会以P
为前缀。
1.4.5.1. 被动 MariaDB/MySQL 特定配置
在构建时修复的配置属性 - 所有其他配置属性在运行时可覆盖
配置属性 | 类型 | default |
类型 | default | |
用于连接的 charset。
环境变量: | string | |
连接建议。
环境变量: | string | |
与服务器的连接所需的安全状态。 请参阅 MySQL 参考手册。
环境变量: |
|
|
连接超时(以秒为单位)
环境变量: | int | |
客户端应使用的身份验证插件。默认情况下,它使用初始握手数据包中的服务器指定的插件名称。
环境变量: |
|
|
可管道的最大 inflight 数据库命令数量。默认情况下禁用 pipelining。
环境变量: | int | |
是否返回与 UPDATE 语句中的 WHERE 子句匹配的行数,而不是实际更改的行数。
环境变量: | 布尔值 |
|
1.4.5.2. 特定于被动的 Microsoft SQL 服务器配置
在构建时修复的配置属性 - 所有其他配置属性在运行时可覆盖
配置属性 | 类型 | default |
类型 | default | |
TDS 数据包所需的大小(以字节为单位)。
环境变量: | int | |
是否启用 SSL/TLS。
环境变量: | 布尔值 |
|
1.4.5.3. 被动特定于 Oracle 的配置
在构建时修复的配置属性 - 所有其他配置属性在运行时可覆盖
配置属性 | 类型 | default |
类型 | default |
1.4.5.4. 特定于被动 PostgreSQL 的配置
在构建时修复的配置属性 - 所有其他配置属性在运行时可覆盖
配置属性 | 类型 | default |
类型 | default | |
可管道的最大 inflight 数据库命令数量。
环境变量: | int | |
客户端的 SSL 操作模式。 请参阅在 不同模式中提供的保护。
环境变量: |
|
|
第 7 级代理可以在与实际数据库的多个连接上负载平衡查询。当发生这种情况时,缺少会话关联性和不需要的错误可能会混淆,如 ERROR: unnamed prepared 语句 does not exist (26000)。请参阅使用级别 7 代理
环境变量: | 布尔值 |
|
1.4.6. 被动数据源 URL 参考
1.4.6.1. DB2
db2://[user[:[password]]@]host[:port][/database][?<key1>=<value1>[&<key2>=<value2>]]
- Example
-
db2://dbuser:secretpassword@database.server.com:50000/mydb
目前,客户端支持以下参数键:
-
主机
-
port
-
user
-
password
-
database
在连接 URL 中配置参数会覆盖默认属性。
1.4.6.2. Microsoft SQL 服务器
sqlserver://[user[:[password]]@]host[:port][/database][?<key1>=<value1>[&<key2>=<value2>]]
- Example
-
sqlserver://dbuser:secretpassword@database.server.com:1433/mydb
目前,客户端支持以下参数键:
-
主机
-
port
-
user
-
password
-
database
在连接 URL 中配置参数会覆盖默认属性。
1.4.6.3. MySQL / MariaDB
mysql://[user[:[password]]@]host[:port][/database][?<key1>=<value1>[&<key2>=<value2>]]
- Example
-
mysql://dbuser:secretpassword@database.server.com:3211/mydb
目前,客户端支持以下参数键(不区分大小写):
-
主机
-
port
-
user
-
password
-
schema
-
套接字
-
useAffectedRows
在连接 URL 中配置参数会覆盖默认属性。
1.4.6.4. Oracle
1.4.6.4.1. EZConnect 格式
Oracle:thin:@[[protocol:]//]host[:port][/service_name][:server_mode][/instance_name][?connection properties]
- Example
-
oracle:thin:@mydbhost1:5521/mydbservice?connect_timeout=10sec
1.4.6.4.2. TNS 别名格式
oracle:thin:@<alias_name>[?connection properties]
- Example
-
oracle:thin:@prod_db?TNS_ADMIN=/work/tns/
1.4.6.5. PostgreSQL
postgresql://[user[:[password]]@]host[:port][/database][?<key1>=<value1>[&<key2>=<value2>]]
- Example
-
postgresql://dbuser:secretpassword@database.server.com:5432/mydb
目前,客户端支持:
以下参数键:
-
主机
-
port
-
user
-
password
-
dbname
-
sslmode
-
其他属性,例如:
-
application_name
-
fallback_application_name
-
search_path
-
options
-
在连接 URL 中配置参数会覆盖默认属性。