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.15 中弃用，计划在以后的发行版本中删除。在当前发行生命周期中，红帽将继续对 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.15 中弃用，计划在以后的发行版本中删除。在当前发行生命周期中，红帽将继续对 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 驱动程序的扩展的数据库，您可以使用自定义驱动程序。例如，如果您在项目中使用 OpenTracing JDBC 驱动程序。

如果没有扩展，驱动程序将在 JVM 模式下运行的任何 Quarkus 应用程序中正常工作。但是，当将应用程序编译到原生可执行文件时，驱动程序不太可能正常工作。如果您计划创建原生可执行文件，请使用现有的 JDBC Quarkus 扩展，或为您的驱动程序贡献一个。

警告

OpenTracing 已被弃用，而是使用 OpenTelemetry。如需追踪信息，请检查有关 Datasource tracing, bellow 的相关部分。

使用传统 OpenTracing 驱动程序的自定义驱动程序定义示例：

quarkus.datasource.jdbc.driver=io.opentracing.contrib.jdbc.TracingDriver
Copy to Clipboard Toggle word wrap

定义在 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.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. 激活或停用数据源
复制链接

当数据源在构建时配置时，它在运行时默认处于活动状态。这意味着 Quarkus 将在应用程序启动时启动对应的 JDBC 连接池或被动客户端。

要在运行时取消激活数据源，请将 quarkus.datasource[.optional name].active 设置为 false。然后，quarkus 将在应用程序启动期间跳过启动 JDBC 连接池或被动客户端。在运行时尝试使用已停用的数据源都会导致异常。

当您需要应用程序在运行时从预定义的集合中选择一个数据源时，此功能特别有用。

警告

如果另一个 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 pg-related runtime configuration here, prefixed with "%pg."

%oracle.quarkus.hibernate-orm."oracle".active=true
%oracle.quarkus.datasource."oracle".active=true
# Add any pg-related runtime configuration here, prefixed with "%pg."
Copy to Clipboard Toggle word wrap
提示

定义 CDI bean 生成者 重定向到当前活动数据源，如下所示： 

public class MyProducer {
    @Inject
    DataSourceSupport dataSourceSupport;

    @Inject
    @DataSource("pg")
    AgroalDataSource pgDataSourceBean;

    @Inject
    @DataSource("oracle")
    AgroalDataSource oracleDataSourceBean;

    @Produces
    @ApplicationScoped
    public AgroalDataSource dataSource() {
        if (dataSourceSupport.getInactiveNames().contains("pg")) {
            return oracleDataSourceBean;
        } else {
            return pgDataSourceBean;
        }
    }
}
Copy to Clipboard Toggle word wrap

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 会导致 在第一次 出错事务时记录警告。

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

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

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

让开源更具包容性

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

關於紅帽

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

Theme

© 2025 Red Hat