Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

1.2. 配置数据源

下面的部分描述了单个或多个数据源的配置。为了简单起见，我们将引用单个数据源作为默认（未命名）数据源。

1.2.1. 配置单个数据源
复制链接

数据源可以是 JDBC 数据源、被动或两者。这取决于配置和项目扩展选择。

  1. 使用以下配置属性定义数据源，其中 db-kind 定义要连接的数据库平台，如 h2 ： 

    quarkus.datasource.db-kind=h2
    Copy to Clipboard Toggle word wrap

    Quarkus 丢弃了从 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 扩展，或为您的特定驱动程序提供自定义扩展。

  2. 配置以下属性以定义凭证： 

    quarkus.datasource.username=<your username>
quarkus.datasource.password=<your password>
    Copy to Clipboard Toggle word wrap

    您还可以将 凭证供应商用于数据源从 Vault 检索密码。

到目前为止，无论您是否使用 JDBC 还是被动驱动程序，配置都相同。当您定义了数据库类型和凭证时，其余则取决于您正在使用的驱动程序类型。可以同时使用 JDBC 和被动驱动程序。

1.2.1.1. JDBC 数据源
复制链接

JDBC 是最常见的数据库连接模式，通常在与非主动 Hibernate ORM 结合使用时使用。

  1. 要使用 JDBC 数据源，请从添加所需依赖项开始：

    1. 与内置 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 驱动程序依赖项： 

        ./mvnw quarkus:add-extension -Dextensions="jdbc-postgresql"
        Copy to Clipboard Toggle word wrap
        注意

        使用内置 JDBC 驱动程序扩展会自动包含 Agroal 扩展，这是适用于自定义和内置 JDBC 驱动程序的 JDBC 连接池实施。但是，对于自定义驱动程序，需要显式添加 Agroal。

    2. 对于自定义 JDBC 驱动程序，请将 quarkus-agroal 依赖项添加到项目以及相关数据库驱动程序的扩展： 

      ./mvnw quarkus:add-extension -Dextensions="agroal"
      Copy to Clipboard Toggle word wrap

      要将 JDBC 驱动程序用于其他 数据库，请使用没有内置扩展或具有不同驱动程序 的数据库。

  2. 通过定义 JDBC URL 属性来配置 JDBC 连接： 

    quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test
    Copy to Clipboard Toggle word wrap
    注意

    注意属性名称中的 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
Copy to Clipboard Toggle word wrap

有关 JDBC 配置选项和配置其他方面的所有详细信息，如连接池大小，请参阅 JDBC 配置参考部分。

1.2.1.1.2. 消耗数据源
复制链接

使用 Hibernate ORM 时，Hibernate 层会自动获取数据源并使用它。

对于数据源的代码访问，将其作为任何其他 Bean 获取，如下所示： 

@Inject
AgroalDataSource defaultDataSource;
Copy to Clipboard Toggle word wrap

在上例中，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 提供多个被动客户端，用于被动数据源。

  1. 在应用程序中添加对应的扩展：

    • 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 一致。

  2. 添加驱动程序后，配置连接 URL 并为连接池定义正确的大小。 

    quarkus.datasource.reactive.url=postgresql:///your_database
quarkus.datasource.reactive.max-size=20
    Copy to Clipboard Toggle word wrap
1.2.1.2.1. 被动连接池大小调整
复制链接

要防止数据库在负载高峰期间过载，请调整池的大小以对数据库负载进行调整。正确大小始终取决于多个因素，如并行应用程序用户的数量或工作负载的性质。

请注意，设置池大小太低可能会导致一些请求在等待连接时超时。

有关池大小调整属性的更多信息，请参阅 被动数据源配置参考部分。

1.2.1.3. JDBC 和被动数据源
复制链接

当包含同一数据库类型的 JDBC 扩展和被动数据源扩展时，将默认创建 JDBC 和被动数据源。

  • 同时使用 JDBC 和 被动 数据源： 

    %prod.quarkus.datasource.reactive.url=postgresql:///your_database
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test
    Copy to Clipboard Toggle word wrap

如果您不想同时创建 JDBC 数据源和被动数据源，请使用以下配置：

  • 明确禁用 JDBC 数据源： 

    quarkus.datasource.jdbc=false
    Copy to Clipboard Toggle word wrap

  • 明确禁用被动数据源： 

    quarkus.datasource.reactive=false
    Copy to Clipboard Toggle word wrap
    提示

    在大多数情况下，上述配置作为 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
Copy to Clipboard Toggle word wrap

注意 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;
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

在运行时 设置 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."
Copy to Clipboard Toggle word wrap

使用这个设置，确保只访问 活跃的 数据源。要做到这一点，注入一个 InjectableInstance<DataSource&gt; 或 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();
        // ...
    }
}
Copy to Clipboard Toggle word wrap

或者，您可以为默认 数据源定义 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 ...
    }
}
Copy to Clipboard Toggle word wrap
1
不要直接注入 DataSource 或 AgroalDatasource。注入不活跃的 Bean 会导致启动失败。相反，注入 InjectableInstance<DataSource> 或 InjectableInstance<AgroalDataSource>。
2
声明 CDI 生成者方法来定义默认数据源。它根据哪个 PostgreSQL 或 Oracle 选择 PostgreSQL 或 Oracle。
3 4
在检索 bean 前，检查 bean 是否处于活动状态。
5
注入唯一的活动数据源。

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)
        ...
Copy to Clipboard Toggle word wrap

允许在同一事务中使用多个 JDBC 数据源：

  1. 确保您的 JDBC 驱动程序支持 XA。所有支持的 JDBC 驱动程序都执行，但其他 JDBC 驱动程序 可能不。
  2. 确保您的数据库服务器已配置为启用 XA。
  3. 通过将 quarkus.datasource[.optional name].jdbc.transactions 设置为 xa，为每个相关数据源启用 XA 支持。

使用 XA 时，一个数据源的回滚将在事务中注册的每个其他数据源中触发回滚。

注意

目前不支持被动数据源上的 XA 事务。

注意

如果您的事务涉及非数据源资源，请注意它们可能不支持 XA 事务，或者可能需要额外的配置。

如果无法为您的其中一个数据源启用 XA ：

Important

如果没有其他解决方案正常工作并需要与 Quarkus 3.8 或更早版本兼容，请设置 quarkus.transaction-manager.unsafe-multiple-last-resources，以 允许在多个 非 XA datasources 间启用不安全事务处理。

将此属性设置为 allow 时，事务回滚可能仅适用于最后一个非 XA 数据源，而其他非 XA 数据源则可能已提交其更改。这可能会使系统处于不一致的状态。

或者，允许相同的不安全行为，但在出现时显示警告：

  • 将属性设置为 warn-each 会记录每个 异常 事务的警告。
  • 将 属性设置为 warn-first，会记录 第一个 offending 事务的警告。

我们不推荐使用这个配置属性，并计划在以后删除它。您应该相应地更新您的应用程序。如果您认为您的用例只是保留此选项，请在 Quarkus tracker 中创建一个问题，解释原因。

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat