红帽全球峰会配置数据源
向红帽构建的 Quarkus 文档提供反馈
要报告错误或改进文档，请登录您的红帽 JIRA 帐户并提交问题。如果您没有红帽 JIRA 帐户，系统会提示您创建一个帐户。
流程
- 单击以下链接 来创建 ticket。
- 在 Summary 中输入有关此问题的简单描述。
- 在描述中提供问题或增强功能的详细描述。请包括有问题的文档 URL。
- 点 Submit 创建问题并将其路由到适当的文档团队。
第 1 章 在红帽构建的 Quarkus 中配置数据源
使用统一配置模型为 Java 数据库连接(JDBC)和被动驱动程序定义数据源。
应用使用数据源访问关系数据库。Quarkus 提供了统一的配置模型，用于定义 Java 数据库连接(JDBC)和被动数据库驱动程序的数据源。
Quarkus 使用 Agroal 和 Vert.x 为 JDBC 和被动驱动程序提供高性能、可扩展的数据源连接池。quarkus-jdbc channel 和 quarkus-reactive PlacementBinding-client 扩展提供构建时间优化，并将配置的 datasources 与 Quarkus 功能（如安全、健康检查和指标）集成。
有关消耗和使用被动数据源的更多信息，请参阅 Quarkus 被动 SQL 客户端 指南。
此外，请参阅 Quarkus Hibernate ORM 指南，以了解有关使用 JDBC 数据源的信息。
1.1. 开始在 Quarkus 中配置 数据源
对于熟悉基本用户的用户，本节提供了快速设置数据源的概述和代码示例。
有关更多与示例相关的配置，请参阅 参考。
1.1.1. 开发模式中的零配置设置
Quarkus 通过提供 Dev Services 功能简化数据库配置，启用零配置数据库设置以测试或以开发(dev)模式运行。在 dev 模式中，推荐的方法是使用 DevServices，并让 Quarkus 处理数据库，而用于生产环境模式，您可以提供指向 Quarkus 外部管理的数据库的显式数据库配置详情。
要使用 Dev Services，请将所需的数据库类型的适当驱动程序扩展（如 jdbc-postgresql ）添加到 pom.xml 文件中。在 dev 模式中，如果您不提供任何显式数据库连接详情，Quarkus 会自动处理数据库设置，并在应用程序和数据库之间提供 wiring。
如果您提供用户凭证，底层数据库将配置为使用它们。如果要使用外部工具连接到数据库，这非常有用。
要使用此功能，请确保安装了 Docker 或 Podman 容器运行时，具体取决于数据库类型。某些数据库，如 H2，以内存模式运行，不需要容器运行时。
使用 %prod 为 prod 模式的实际连接详情添加前缀，以确保它们不会以 dev 模式应用。如需更多信息，请参阅"配置参考"指南中的 Profiles 部分。
有关 Dev 服务的更多信息，请参阅 Dev 服务概述。
如需了解更多详细信息和可选配置，请参阅 Dev Services for 数据库。
1.1.2. 配置 JDBC 数据源
为您选择的数据库添加正确的 JDBC 扩展。
-
quarkus-jdbc-db2 quarkus-jdbc-derby注意Apache Derby 数据库在红帽构建的 Quarkus 3.20 中弃用，计划在以后的发行版本中删除。在当前发行生命周期中，红帽将继续对 Apache Derby 提供开发支持。
-
quarkus-jdbc-h2 -
quarkus-jdbc-mariadb -
quarkus-jdbc-mssql -
quarkus-jdbc-mysql -
quarkus-jdbc-oracle -
quarkus-jdbc-postgresql
-
配置 JDBC 数据源：
Copy to clipboardCopiedquarkus.datasource.db-kind=postgresql 1 quarkus.datasource.username=<your username> quarkus.datasource.password=<your password> quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test quarkus.datasource.jdbc.max-size=16- 1
- 只有在 classpath 上有多个数据库扩展时才需要此配置值。
如果只有一个可行的扩展，Quarkus 会假定这是正确的扩展。当您向测试范围添加驱动程序时，Quarkus 会自动包括测试中的指定驱动程序。
1.1.2.1. JDBC 连接池大小调整
要防止数据库在负载高峰期间过载，请调整池的大小以对数据库负载进行调整。最佳池大小取决于多个因素，如并行应用程序用户的数量或工作负载的性质。
请注意，设置池大小太低可能会导致一些请求在等待连接时超时。
有关池大小调整属性的更多信息，请参阅 JDBC 配置参考部分。
1.1.3. 配置被动数据源
为您选择的数据库添加正确的被动扩展。
-
quarkus-reactive-mssql-client -
quarkus-reactive-mysql-client -
quarkus-reactive-oracle-client -
quarkus-reactive-pg-client
-
配置被动数据源：
Copy to clipboardCopiedquarkus.datasource.db-kind=postgresql 1 quarkus.datasource.username=<your username> quarkus.datasource.password=<your password> quarkus.datasource.reactive.url=postgresql:///your_database quarkus.datasource.reactive.max-size=20- 1
- 只有在 classpath 上有多个 Reactive 驱动程序扩展时才需要此配置值。
1.2. 配置数据源
下面的部分描述了单个或多个数据源的配置。为了简单起见，我们将引用单个数据源作为默认（未命名）数据源。
1.2.1. 配置单个数据源
数据源可以是 JDBC 数据源、被动或两者。这取决于配置和项目扩展选择。
使用以下配置属性定义数据源，其中
db-kind定义要连接的数据库平台，如h2：
Copy to clipboardCopiedquarkus.datasource.db-kind=h2Quarkus 丢弃了从
db-kind数据库平台属性的指定的值中需要使用的 JDBC 驱动程序类。注意只有在应用程序依赖于多个数据库驱动程序时，才需要这一步。如果应用程序使用单一驱动程序操作，则会自动检测到这个驱动程序。
Quarkus 目前包括以下内置数据库类型：
-
DB2:
db2 Derby:
derby注意Apache Derby 数据库在红帽构建的 Quarkus 3.20 中弃用，计划在以后的发行版本中删除。在当前发行生命周期中，红帽将继续对 Apache Derby 提供开发支持。
-
H2:
h2 -
MariaDB:
mariadb -
Microsoft SQL Server:
mssql -
mysql:
mysql -
Oracle:
oracle -
PostgreSQL:
postgresql,pgsql或pg 要使用没有内置的数据库类型，请使用
other并明确定义 JDBC 驱动程序注意您可以在 JVM 模式的 Quarkus 应用程序中使用任何 JDBC 驱动程序，如 自定义数据库和驱动程序 中所述。但是，当将应用程序编译到原生可执行文件时，使用非内置数据库类型不太可能正常工作。
对于原生可执行构建，建议使用可用的 JDBC Quarkus 扩展，或为您的特定驱动程序提供自定义扩展。
-
DB2:
配置以下属性以定义凭证：
Copy to clipboardCopiedquarkus.datasource.username=<your username> quarkus.datasource.password=<your password>您还可以将 凭证供应商用于数据源从 Vault 检索密码。
到目前为止，无论您是否使用 JDBC 还是被动驱动程序，配置都相同。当您定义了数据库类型和凭证时，其余则取决于您正在使用的驱动程序类型。可以同时使用 JDBC 和被动驱动程序。
1.2.1.1. JDBC 数据源
JDBC 是最常见的数据库连接模式，通常在与非主动 Hibernate ORM 结合使用时使用。
要使用 JDBC 数据源，请从添加所需依赖项开始：
与内置 JDBC 驱动程序一起使用，请从以下列表中为您的关系数据库驱动程序选择并添加 Quarkus 扩展：
Derby -
quarkus-jdbc-derby注意Apache Derby 数据库在红帽构建的 Quarkus 3.20 中弃用，计划在以后的发行版本中删除。在当前发行生命周期中，红帽将继续对 Apache Derby 提供开发支持。
H2 -
quarkus-jdbc-h2注意H2 和 Derby 数据库可以配置为以"嵌入模式"运行，但 Derby 扩展不支持将嵌入式数据库引擎编译到原生可执行文件中。
使用内存中数据库读取测试，以了解有关集成测试的建议。
-
DB2 -
quarkus-jdbc-db2 -
MariaDB -
quarkus-jdbc-mariadb -
Microsoft SQL Server -
quarkus-jdbc-mssql -
MySQL -
quarkus-jdbc-mysql -
Oracle -
quarkus-jdbc-oracle PostgreSQL -
quarkus-jdbc-postgresql例如，要添加 PostgreSQL 驱动程序依赖项：
Copy to clipboardCopied./mvnw quarkus:add-extension -Dextensions="jdbc-postgresql"注意使用内置 JDBC 驱动程序扩展会自动包含 Agroal 扩展，这是适用于自定义和内置 JDBC 驱动程序的 JDBC 连接池实施。但是，对于自定义驱动程序，需要显式添加 Agroal。
对于自定义 JDBC 驱动程序，请将
quarkus-agroal依赖项添加到项目以及相关数据库驱动程序的扩展：
Copy to clipboardCopied./mvnw quarkus:add-extension -Dextensions="agroal"要将 JDBC 驱动程序用于其他 数据库，请使用没有内置扩展或具有不同驱动程序 的数据库。
通过定义 JDBC URL 属性来配置 JDBC 连接：
Copy to clipboardCopiedquarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test注意注意属性名称中的
jdbc前缀。特定于 JDBC 的所有配置属性都具有jdbc前缀。对于被动数据源，前缀是被动的。
有关配置 JDBC 的更多信息，请参阅 JDBC URL 格式参考 和 Quarkus 扩展和数据库驱动程序参考。
1.2.1.1.1. 自定义数据库和驱动程序
如果 Quarkus 没有为您的数据库提供 JDBC 扩展，或者需要使用不同的 JDBC 驱动程序，如用于 OpenTelemetry 的驱动程序，您可以明确配置 JDBC 驱动程序。
如果没有扩展，则 JDBC 驱动程序将在 JVM 模式下正常工作。但是，当将应用程序编译到原生可执行文件时，它们不太可能正常工作。要构建原生可执行文件，请使用现有的 Quarkus JDBC 扩展，或为您的驱动程序提供新的扩展。
定义在 JVM 模式中没有内置支持的数据库访问的示例：
quarkus.datasource.db-kind=other
quarkus.datasource.jdbc.driver=oracle.jdbc.driver.OracleDriver
quarkus.datasource.jdbc.url=jdbc:oracle:thin:@192.168.1.12:1521/ORCL_SVC
quarkus.datasource.username=scott
quarkus.datasource.password=tiger有关 JDBC 配置选项和配置其他方面的所有详细信息，如连接池大小，请参阅 JDBC 配置参考部分。
1.2.1.1.2. 消耗数据源
使用 Hibernate ORM 时，Hibernate 层会自动获取数据源并使用它。
对于数据源的代码访问，将其作为任何其他 Bean 获取，如下所示：
@Inject
AgroalDataSource defaultDataSource;
在上例中，type 是 AgroalDataSource，它是 javax.sql.DataSource 子类型。因此，您也可以使用 javax.sql.DataSource 作为注入的类型。
1.2.1.1.3. Oracle 注意事项
如 问题 #36265 所述，Oracle 在关闭连接时意外提交未提交的事务。这意味着，当停止 Quarkus 时，即使它们不完整，在进行中的事务中也可能被提交。
因为此行为是意外的，并可能导致数据丢失，所以在关闭连接时，拦截器会回滚任何未完成的事务。但是，如果您使用 XA 事务，事务管理器将处理回滚。
如果 3.18 中引入的行为为您的工作负载造成问题，请通过将 -Dquarkus-oracle-no-automatic-rollback-on-connection-close 系统属性设置为 true 来禁用它。确保在 问题跟踪器 中报告您的用例，以便我们可以在需要时调整此行为，例如，使用更永久的设置。
1.2.1.2. 被动数据源
Quarkus 提供多个被动客户端，用于被动数据源。
在应用程序中添加对应的扩展：
-
mariadb/MySQL:
quarkus-reactive-mysql-client -
Microsoft SQL Server:
quarkus-reactive-mssql-client -
Oracle:
quarkus-reactive-oracle-client postgresql:
quarkus-reactive-pg-client安装的扩展必须与您在数据源配置中定义的
quarkus.datasource.db-kind一致。
-
mariadb/MySQL:
添加驱动程序后，配置连接 URL 并为连接池定义正确的大小。
Copy to clipboardCopiedquarkus.datasource.reactive.url=postgresql:///your_database quarkus.datasource.reactive.max-size=20
1.2.1.2.1. 被动连接池大小调整
要防止数据库在负载高峰期间过载，请调整池的大小以对数据库负载进行调整。正确大小始终取决于多个因素，如并行应用程序用户的数量或工作负载的性质。
请注意，设置池大小太低可能会导致一些请求在等待连接时超时。
有关池大小调整属性的更多信息，请参阅 被动数据源配置参考部分。
1.2.1.3. JDBC 和被动数据源
当包含同一数据库类型的 JDBC 扩展和被动数据源扩展时，将默认创建 JDBC 和被动数据源。
如果您不想同时创建 JDBC 数据源和被动数据源，请使用以下配置：
明确禁用 JDBC 数据源：
Copy to clipboardCopiedquarkus.datasource.jdbc=false明确禁用被动数据源：
Copy to clipboardCopiedquarkus.datasource.reactive=false提示在大多数情况下，上述配置作为 JDBC 驱动程序或被动数据源扩展是可选的，但不能同时存在。
1.2.2. 配置多个数据源
Hibernate ORM 扩展支持使用配置属性定义 持久性单元。对于每个持久性单元，指向您选择的数据源。
定义多个数据源的工作方式类似于定义单个数据源，且有一个重要的更改 - 您必须为每个数据源指定一个名称（配置属性）。
以下示例提供三个不同的数据源：
- 默认
-
名为
users的数据源 -
名为
inventory的数据源
每种配置：
quarkus.datasource.db-kind=h2
quarkus.datasource.username=username-default
quarkus.datasource.jdbc.url=jdbc:h2:mem:default
quarkus.datasource.jdbc.max-size=13
quarkus.datasource.users.db-kind=h2
quarkus.datasource.users.username=username1
quarkus.datasource.users.jdbc.url=jdbc:h2:mem:users
quarkus.datasource.users.jdbc.max-size=11
quarkus.datasource.inventory.db-kind=h2
quarkus.datasource.inventory.username=username2
quarkus.datasource.inventory.jdbc.url=jdbc:h2:mem:inventory
quarkus.datasource.inventory.jdbc.max-size=12
注意 configuration 属性中有一个额外的部分。语法如下： quarkus.datasource.[optional name.][datasource property]。
即使只安装了一个数据库扩展，名为 databases 需要至少指定一个 build-time 属性，以便 Quarkus 可以检测到它们。通常，这是 db-kind 属性，但您也可以指定 Dev Services 属性，根据 Dev Services for Databases 指南创建名为 datasources。
1.2.2.1. 命名数据源注入
使用多个数据源时，每个 DataSource 也具有 io.quarkus.agroal.DataSource qualifier，并将数据源的名称用作值。
通过使用上一节中提到的属性来配置三个不同的数据源，按如下方式注入每个不同的数据源：
@Inject
AgroalDataSource defaultDataSource;
@Inject
@DataSource("users")
AgroalDataSource usersDataSource;
@Inject
@DataSource("inventory")
AgroalDataSource inventoryDataSource;1.2.3. 激活或停用数据源
当数据源在构建时配置，且在运行时设置其 URL 时，它默认处于活动状态。当应用程序启动时，quarkus 会启动对应的 JDBC 连接池或被动客户端。
要在运行时取消激活数据源，请执行以下任一操作：
-
不要设置
quarkus.datasource[.optional name].jdbc.url或quarkus.datasource[.optional name].reactive.url。 -
将
quarkus.datasource[.optional name].active设置为false。
如果数据源未激活：
- 数据源不会在应用程序启动期间尝试连接到数据库。
- 数据源不贡献 健康检查。
-
涉及数据源的静态 CDI 注入点（如
@Inject DataSource ds或@Inject Pool pool），这会导致应用启动失败。 -
数据源的动态检索（如通过
CDI.getBeanContainer （）、Arc.instance （）或注入Instance<DataSource> ）会导致抛出异常。 使用数据源的其他 Quarkus 扩展可能会导致应用程序启动失败。
在这种情况下，您还必须取消激活那些其他扩展。要查看此情境的示例，请参阅 Hibernate ORM 指南中的此部分。
当应用程序在运行时从预定义的集合中选择一个数据源时，此功能特别有用。
为运行时选择配置多个数据源的示例：
quarkus.datasource."pg".db-kind=postgres
quarkus.datasource."pg".active=false
quarkus.datasource."pg".jdbc.url=jdbc:postgresql:///your_database
quarkus.datasource."oracle".db-kind=oracle
quarkus.datasource."oracle".active=false
quarkus.datasource."oracle".jdbc.url=jdbc:oracle:///your_database
在运行时 设置 quarkus.datasource."pg".active=true 只会提供 PostgreSQL 数据源。在运行时设置 quarkus.datasource."oracle".active=true 只会提供 Oracle 数据源。
自定义配置配置文件 简化了此设置。通过将以下特定于配置集的配置附加到以上配置，您可以通过设置 quarkus.profile 在运行时选择持久性单元或数据源。例如，使用 quarkus.profile=prod,pg 或 quarkus.profile=prod,oracle。
%pg.quarkus.hibernate-orm."pg".active=true
%pg.quarkus.datasource."pg".active=true
# Add any PostgreSQL-related runtime configuration here, prefixed with "%pg."
%oracle.quarkus.hibernate-orm."oracle".active=true
%oracle.quarkus.datasource."oracle".active=true
# Add any Oracle-related runtime configuration here, prefixed with "%oracle."
使用这个设置，确保只访问 活跃的 数据源。要做到这一点，注入一个 InjectableInstance<DataSource> 或 InjectableInstance<Pool& gt;，它带有一个 @Any qualifier，并调用 getActive （）。
import io.quarkus.arc.InjectableInstance;
@ApplicationScoped
public class MyConsumer {
@Inject
@Any
InjectableInstance<DataSource> dataSource;
public void doSomething() {
DataSource activeDataSource = dataSource.getActive();
// ...
}
}或者，您可以为默认 数据源定义 CDI bean 生成者。此 bean 生成者重定向到当前活跃的名为 datasource。这允许直接注入它，如下所示：
public class MyProducer {
@Inject
@DataSource("pg")
InjectableInstance<DataSource> pgDataSourceBean; 1
@Inject
@DataSource("oracle")
InjectableInstance<DataSource> oracleDataSourceBean;
@Produces 2
@ApplicationScoped
public DataSource dataSource() {
if (pgDataSourceBean.getHandle().getBean().isActive()) { 3
return pgDataSourceBean.get();
} else if (oracleDataSourceBean.getHandle().getBean().isActive()) { 4
return oracleDataSourceBean.get();
} else {
throw new RuntimeException("No active datasource!");
}
}
}
@ApplicationScoped
public class MyConsumer {
@Inject
DataSource dataSource; 5
public void doSomething() {
// .. just use the injected datasource ...
}
}1.2.4. 在单个事务中使用多个数据源
默认情况下，数据源上的 XA 支持被禁用。因此，事务中不包含多个数据源。在同一个事务中尝试访问多个非 XA datasources 会导致异常类似如下：
...
Caused by: java.sql.SQLException: Exception in association of connection to existing transaction
at io.agroal.narayana.NarayanaTransactionIntegration.associate(NarayanaTransactionIntegration.java:130)
...
Caused by: java.sql.SQLException: Failed to enlist. Check if a connection from another datasource is already enlisted to the same transaction
at io.agroal.narayana.NarayanaTransactionIntegration.associate(NarayanaTransactionIntegration.java:121)
...允许在同一事务中使用多个 JDBC 数据源：
- 确保您的 JDBC 驱动程序支持 XA。所有支持的 JDBC 驱动程序都执行，但其他 JDBC 驱动程序 可能不。
- 确保您的数据库服务器已配置为启用 XA。
-
通过将
quarkus.datasource[.optional name].jdbc.transactions设置为xa，为每个相关数据源启用 XA 支持。
使用 XA 时，一个数据源的回滚将在事务中注册的每个其他数据源中触发回滚。
目前不支持被动数据源上的 XA 事务。
如果您的事务涉及非数据源资源，请注意它们可能不支持 XA 事务，或者可能需要额外的配置。
如果无法为您的其中一个数据源启用 XA ：
- 请注意，仍然通过 Last Resource Commit Optimization (LRCO)支持为所有数据源启用 XA，但仍然通过 Last Resource Commit Optimization (LRCO) 支持。
-
如果您不需要一个数据源的回滚来为其他数据源触发回滚，请考虑将您的代码拆分为多个事务。要做到这一点，请使用
QuarkusTransaction.requiringNew （）/@Transactional (REQUIRES_NEW)或UserTransaction（用于更复杂的用例）。
如果没有其他解决方案正常工作并需要与 Quarkus 3.8 或更早版本兼容，请设置 quarkus.transaction-manager.unsafe-multiple-last-resources，以 允许在多个 非 XA datasources 间启用不安全事务处理。
将此属性设置为 allow 时，事务回滚可能仅适用于最后一个非 XA 数据源，而其他非 XA 数据源则可能已提交其更改。这可能会使系统处于不一致的状态。
或者，允许相同的不安全行为，但在出现时显示警告：
-
将属性设置为
warn-each会记录每个 异常 事务的警告。 -
将 属性设置为
warn-first，会记录 第一个 offending 事务的警告。
我们不推荐使用这个配置属性，并计划在以后删除它。您应该相应地更新您的应用程序。如果您认为您的用例只是保留此选项，请在 Quarkus tracker 中创建一个问题，解释原因。
1.3. 数据源集成
1.3.1. 数据源健康检查
如果您使用 quarkus-smallrye-health 扩展，则 quarkus-agroal 和 reactive 客户端扩展会自动添加就绪度健康检查来验证数据源。
当您访问应用程序的健康状况就绪端点时，/q/health/ready 默认接收有关数据源验证状态的信息。如果您有多个数据源，则会检查所有数据源验证失败，如果发生单一数据源验证失败，其状态将更改为 DOWN。
可以使用 quarkus.datasource.health.enabled 属性禁用此行为。
仅从健康检查中排除特定的数据源：
quarkus.datasource."datasource-name".health-exclude=true1.3.2. 数据源指标
如果您使用 quarkus-micrometer 或 quarkus-smallrye-metrics 扩展，quarkus-agroal 可以为指标 registry 贡献一些与数据源相关的指标。这可以通过将 quarkus.datasource.metrics.enabled 属性设置为 true 来激活。
要使公开的指标包含任何实际值，必须在 Agroal 机制在内部启用指标集合。默认情况下，当存在指标扩展时，所有数据源启用了此指标集合机制，并且启用了 Agroal 扩展的指标。
要禁用特定数据源的指标，请将 quarkus.datasource.jdbc.enable-metrics 设置为 false，或者为命名数据源应用 quarkus.datasource.<datasource.<datasource name>.jdbc.enable-metrics。这会禁用收集指标，并在 /q/metrics 端点中公开指标（如果禁用收集它们的机制）。
相反，将 quarkus.datasource.jdbc.enable-metrics 设置为 true，或 quarkus.datasource.<datasource name>.jdbc.enable-metrics 明确启用了指标集合，即使指标扩展没有使用。如果您需要以编程方式访问收集的指标，这非常有用。在注入的 AgroalDataSource 实例上调用 dataSource.getMetrics （） 后，它们可用。
如果此数据源的指标集合被禁用，则所有值都为零。
1.3.3. 数据源追踪
要将追踪与数据源一起使用，您需要将 quarkus-opentelemetry 扩展添加到项目中。
您不需要声明不同的驱动程序来启用追踪。如果使用 JDBC 驱动程序，则需要遵循 OpenTelemetry 扩展中的说明。
即使所有追踪基础架构都就位，数据源追踪不默认启用，您需要通过设置此属性启用它：
# enable tracing
quarkus.datasource.jdbc.telemetry=true1.3.4. Narayana 事务管理器集成
如果 Narayana JTA 扩展也可用，则集成是自动的。
您可以通过设置 transactions 配置属性来覆盖它：
-
用于默认未命名数据源的
quarkus.datasource.jdbc.transactions -
quarkus.datasource. <datasource-name& gt; .jdbc.transactions用于命名数据源
如需更多信息，请参阅下面的 配置参考部分。
为了便于使用 JDBC 在数据库中存储事务日志，请参阅在 Quarkus 指南中的 配置事务日志以存储在使用事务 的数据源 部分。
1.3.4.1. 名为 datasources
使用 Dev Services 时，将始终创建默认数据源，但要指定命名数据源，您需要至少有一个构建时间属性，以便 Quarkus 能够检测到如何创建数据源。
通常，您可以通过设置 quarkus.datasource."name".devservices.enabled=true 来指定 db-kind 属性或显式启用 Dev Services。
1.3.5. 使用内存数据库进行测试
H2 和 Derby 等数据库通常在 嵌入式模式下 用作快速运行集成测试的工具。
推荐的方法是使用数据库用于生产环境，以尽可能在生产环境上获得结果。这让 Dev 服务 变得更加简单，因为它们不需要配置和启动相对快。但是，在需要运行简单集成测试时，也可以使用 JVM 驱动的数据库。
1.3.5.1. 支持和限制
嵌入式数据库(H2 和 Derby)在 JVM 模式下工作。对于原生模式，有以下限制：
- Derby 无法嵌入到原生模式下的应用程序中。但是，Quarkus Derby 扩展允许原生编译 Derby JDBC 客户端，支持 远程连接。
- 不建议在您的原生镜像中嵌入 H2。例如，请考虑使用到独立数据库的远程连接的替代方法。
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 | |
|
如果启用了数据源的常规健康检查，则是否应从健康检查中排除此特定数据源。 默认情况下，健康检查包含所有配置的数据源（如果已启用）。
环境变量： | 布尔值 |
|
|
此数据源是否应在运行时处于活动状态。
环境变量： | 布尔值 |
|
|
数据源用户名
环境变量： | 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，则这无效。
环境变量： | 字符串列表 | |
|
要映射到容器的卷。 map 键对应于主机位置；map 值是容器位置。如果主机位置以 "classpath:" 开头，映射会从 classpath 中加载资源，且具有只读权限。 使用文件系统位置时，卷将生成有读写权限，可能会导致文件系统中的数据丢失或修改。 如果提供商不是基于容器的数据库，如 H2 或 Derby，则这无效。
环境变量： | Map<String,String> | |
|
是否要在 dev 模式会话或测试套件执行后 保持 Dev Service 容器运行，以便在下一个 dev 模式会话或测试套件中执行中重复使用它们。 在 dev 模式会话或测试套件执行中，只要其配置（用户名、密码、环境、端口绑定、端口绑定、…）的配置不会改变。此功能针对在 Quarkus 没有运行时保持容器保持运行，以便在运行时重复使用它们。 警告
这个功能需要在
默认情况下，此配置属性被设置为
环境变量： | 布尔值 |
|
|
JBoss 日志记录器是否应使用日志。 如果提供商不是基于容器的数据库，如 H2 或 Derby，则这无效。
环境变量： | 布尔值 |
|
1.4.2. JDBC 配置参考
在构建时修复的配置属性 - 所有其他配置属性在运行时可覆盖
| 配置属性 | 类型 | default |
|
激活或禁用 dev ui 页面。
环境变量： | 布尔值 |
|
|
在 Dev UI 页面中允许 sql 查询
环境变量： | 布尔值 |
|
|
将此选项附加到选择以获取表值。例如：LIMIT 100 或 TOP 100
环境变量： | string | |
|
允许的数据库主机。默认情况下，只允许 localhost。此处提供的任何主机都将被允许
环境变量： | string | |
|
如果我们为此数据源创建 JDBC 数据源。
环境变量： | 布尔值 |
|
|
数据源驱动程序类名称
环境变量： | string | |
|
是否要使用常规 JDBC 事务、XA 还是禁用所有事务处理功能。
启用 XA 时，您将需要一个实现
环境变量： | 启用 ：将 JDBC 数据源与 Quarkus 的 JTA TransactionManager 集成。这是默认值。
XA ：与 disabled ：禁用与 Narayana TransactionManager 的 Agroal 集成。这通常是一个好主意，且仅在特殊情况下很有用：请确保在不深入了解影响的情况下不使用此功能。 | enabled |
|
启用数据源指标集合。如果未指定，则当指标扩展处于活跃状态时，将默认启用收集指标。
环境变量： | 布尔值 | |
|
启用 OpenTelemetry JDBC 检测。
环境变量： | 布尔值 |
|
|
数据源 URL
环境变量： | string | |
|
池的初始大小。通常，您要将初始大小设置为至少与最小大小匹配，但这不强制，允许那些希望在引导时对连接的 lazy 初始化的架构，同时在启动时可以保持最小池大小。
环境变量： | int | |
|
数据源池最小值
环境变量： | int |
|
|
数据源池最大大小
环境变量： | int |
|
|
我们在后台验证闲置连接的时间间隔。
设置为
环境变量： |
| |
|
对闲置时间超过指定间隔的连接执行前台验证。
环境变量： | ||
|
取消获取新连接前的超时时间
环境变量： |
| |
|
检查连接泄漏的时间间隔。
环境变量： |
| |
|
我们试图删除闲置连接的时间间隔。
环境变量： |
| |
|
连接的最大生命周期。
环境变量： |
| |
|
事务隔离级别。
环境变量： |
| |
|
收集并显示泄漏连接中的额外故障排除信息。
环境变量： | 布尔值 |
|
|
在返回到池后，允许刷新连接。默认情况下不启用。
环境变量： | 布尔值 |
|
|
启用后，Agroal 能够在不关闭所有打开的声明的情况下，在返回到池时产生警告。这与跟踪打开的连接无关。禁用峰值性能，但仅在有高度信任时不会发生泄漏。
环境变量： | 布尔值 |
|
|
第一次使用连接时执行的查询。
环境变量： | string | |
|
执行的查询以验证连接。
环境变量： | string | |
|
无论空闲状态如何，强制在获取(foreground 验证)前进行连接验证。
由于每次调用时执行验证的开销，建议依赖默认的空闲验证，并把它保留为
环境变量： | 布尔值 |
|
|
禁用池以防止重复使用连接。当外部池管理 Connections 的生命周期时，请使用此选项。
环境变量： | 布尔值 |
|
|
在获取连接时需要活跃的事务。建议用于生产环境。警告：一些扩展会获取连接，而无需为 schema 更新和模式验证等操作保留事务。在这些情况下，将此设置设置为 STRICT 可能会导致失败。
环境变量： |
| |
|
创建新连接时，将传递给 JDBC 驱动程序的其他未指定属性。
环境变量： | Map<String,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> |
要写入持续时间值，请使用标准 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 |
| 没有找到配置属性。 | ||
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 中配置参数会覆盖默认属性。
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}