返回指南
编辑此页面

在 Quarkus 中配置数据源

使用统一的配置模型来定义 Java 数据库连接 (JDBC) 和响应式驱动程序的数据源。

应用程序使用数据源来访问关系数据库。Quarkus 提供了一个统一的配置模型来定义 Java 数据库连接 (JDBC) 和响应式数据库驱动程序的数据源。

Quarkus 使用 Agroal 和 Vert.x 为 JDBC 和响应式驱动程序提供高性能、可扩展的数据源连接池。quarkus-jdbc-* 和 quarkus-reactive-*-client 扩展提供了构建时优化，并将配置的数据源与 Quarkus 的功能（如安全性、运行状况检查和指标）集成。

有关使用响应式数据源的更多信息，请参阅 Quarkus 响应式 SQL 客户端指南。

此外，请参阅 Quarkus Hibernate ORM 指南，以获取有关使用 JDBC 数据源的信息。

开始在 Quarkus 中配置 datasources

对于熟悉基本原理的用户，本节提供了概述和代码示例，以快速设置数据源。

有关带有示例的更高级配置，请参阅 参考。

开发模式下的零配置设置

Quarkus 通过提供 Dev Services 功能简化了数据库配置，从而可以为在开发 (dev) 模式下进行测试或运行实现零配置数据库设置。在开发模式下，建议的方法是使用 DevServices 并让 Quarkus 为您处理数据库，而在生产模式下，您提供显式的数据库配置详细信息，指向在 Quarkus 外部管理的数据库。

要使用 Dev Services，请将适当的驱动程序扩展（例如 jdbc-postgresql）添加到 pom.xml 文件中，以用于所需的数据库类型。在开发模式下，如果您不提供任何显式的数据库连接详细信息，Quarkus 会自动处理数据库设置并提供应用程序和数据库之间的连接。

如果您提供用户凭据，则将配置底层数据库以使用这些凭据。如果您想使用外部工具连接到数据库，这将非常有用。

要使用此功能，请确保安装了 Docker 或 Podman 容器运行时，具体取决于数据库类型。某些数据库（如 H2）以内存模式运行，不需要容器运行时。

为确保实际连接详细信息不会在开发模式下应用，请在生产模式下实际连接详细信息前加上 %prod.。有关更多信息，请参阅“配置参考”指南的 配置文件部分。

有关 Dev Services 的更多信息，请参阅 Dev Services 概述。

有关更多详细信息和可选配置，请参阅 数据库的 Dev Services。

配置 JDBC 数据源

  1. 为您选择的数据库添加正确的 JDBC 扩展。

    • quarkus-jdbc-db2

    • quarkus-jdbc-derby

    • quarkus-jdbc-h2

    • quarkus-jdbc-mariadb

    • quarkus-jdbc-mssql

    • quarkus-jdbc-mysql

    • quarkus-jdbc-oracle

    • quarkus-jdbc-postgresql

  2. 配置您的 JDBC 数据源

    quarkus.datasource.db-kind=postgresql (1)
quarkus.datasource.username=<your username>
quarkus.datasource.password=<your password>

quarkus.datasource.jdbc.url=jdbc:postgresql://:5432/hibernate_orm_test
quarkus.datasource.jdbc.max-size=16
    1 只有当类路径上有多个数据库扩展时，才需要此配置值。

如果只有一个可行的扩展可用，Quarkus 会假定这是正确的扩展。当您将驱动程序添加到测试范围时，Quarkus 会自动将指定的驱动程序包含在测试中。

JDBC 连接池大小调整

为了防止数据库在高负载期间过载，请适当地调整池的大小以限制数据库负载。最佳池大小取决于许多因素，例如并行应用程序用户的数量或工作负载的性质。

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

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

配置响应式数据源

  1. 为您选择的数据库添加正确的响应式扩展。

    • quarkus-reactive-db2-client

    • quarkus-reactive-mssql-client

    • quarkus-reactive-mysql-client

    • quarkus-reactive-oracle-client

    • quarkus-reactive-pg-client

  2. 配置您的响应式数据源

    quarkus.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 只有当类路径上有多个响应式驱动程序扩展时，才需要此配置值。

配置数据源

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

配置单个数据源

数据源可以是 JDBC 数据源、响应式数据源或两者都有。这取决于配置和项目扩展的选择。

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

    quarkus.datasource.db-kind=h2

    Quarkus 从 db-kind 数据库平台属性的指定值推断出它需要使用的 JDBC 驱动程序类。

    只有当您的应用程序依赖于多个数据库驱动程序时，才需要执行此步骤。如果应用程序使用单个驱动程序运行，则会自动检测到此驱动程序。

    Quarkus 目前包括以下内置数据库类型

    • DB2: db2

    • Derby: 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>

    您还可以通过 使用凭据提供程序 来为您的数据源从 Vault 检索密码。

到目前为止，无论您使用的是 JDBC 驱动程序还是响应式驱动程序，配置都相同。当您定义了数据库类型和凭据后，其余取决于您使用的是哪种类型的驱动程序。可以同时使用 JDBC 和响应式驱动程序。

JDBC 数据源

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

  1. 要使用 JDBC 数据源，请首先添加必要的依赖项

    1. 对于与内置 JDBC 驱动程序一起使用，请从以下列表中选择并添加适用于您的关系数据库驱动程序的 Quarkus 扩展

      • Derby - quarkus-jdbc-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

      • 其他 JDBC 扩展，例如 SQLite 及其 文档，可以在 Quarkiverse 中找到。

        例如，要添加 PostgreSQL 驱动程序依赖项

        ./mvnw quarkus:add-extension -Dextensions="jdbc-postgresql"

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

    2. 要与自定义 JDBC 驱动程序一起使用，请将 quarkus-agroal 依赖项与关系数据库驱动程序的扩展一起添加到您的项目中

      ./mvnw quarkus:add-extension -Dextensions="agroal"

      要使用另一个数据库的 JDBC 驱动程序，请使用没有内置扩展或具有不同驱动程序的数据库。

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

    quarkus.datasource.jdbc.url=jdbc:postgresql://:5432/hibernate_orm_test

    请注意属性名称中的 jdbc 前缀。特定于 JDBC 的所有配置属性都有 jdbc 前缀。对于响应式数据源，前缀为 reactive。

有关配置 JDBC 的更多信息，请参阅 JDBC URL 格式参考 和 Quarkus 扩展和数据库驱动程序参考。

自定义数据库和驱动程序

如果 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 配置参考部分。

使用数据源

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

对于数据源的内部代码访问，请按以下方式将其作为任何其他 bean 获取

@Inject
AgroalDataSource defaultDataSource;

在上面的示例中，类型为 AgroalDataSource，它是 javax.sql.DataSource 子类型。因此，您也可以使用 javax.sql.DataSource 作为注入类型。

Oracle 注意事项

如 issue #36265 中所述，Oracle 在关闭连接时会意外提交未提交的事务。这意味着在停止 Quarkus 时，即使未完成，正在进行的事务也可能会被提交。

由于此行为是意外的，并且可能导致数据丢失，因此拦截器会在关闭连接时回滚任何未完成的事务。但是，如果您使用 XA 事务，事务管理器将处理回滚。

如果 3.18 中引入的行为给您的工作负载带来了问题，请通过将 -Dquarkus-oracle-no-automatic-rollback-on-connection-close 系统属性设置为 true 来禁用它。请务必在我们的 问题跟踪器 中报告您的用例，以便我们可以根据需要调整此行为，例如使用更永久的设置。

响应式数据源

Quarkus 提供了几个响应式客户端，用于响应式数据源。

  1. 将相应的扩展添加到您的应用程序

    • DB2: quarkus-reactive-db2-client

    • 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
响应式连接池大小调整

为了防止数据库在高负载期间过载，请适当地调整池的大小以限制数据库负载。适当的大小始终取决于许多因素，例如并行应用程序用户的数量或工作负载的性质。

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

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

JDBC 和响应式数据源同时

当包含同一数据库类型的 JDBC 扩展和响应式数据源扩展时，默认情况下将创建 JDBC 和响应式数据源。

  • 要同时使用 JDBC 和 响应式 数据源

    %prod.quarkus.datasource.reactive.url=postgresql:///your_database
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://:5432/hibernate_orm_test

如果您不想同时创建 JDBC 数据源和响应式数据源，请使用以下配置。

  • 要显式禁用 JDBC 数据源

    quarkus.datasource.jdbc=false

  • 要显式禁用响应式数据源

    quarkus.datasource.reactive=false

    在大多数情况下，以上配置将是可选的，因为将存在 JDBC 驱动程序或响应式数据源扩展，而不是两者都存在。

配置多个数据源

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

请注意，配置属性中有一个额外的部分。语法如下：quarkus.datasource.[可选名称.][数据源属性]。

即使只安装了一个数据库扩展，命名的数据库也需要指定至少一个构建时属性，以便 Quarkus 可以检测到它们。通常，这是 db-kind 属性，但您也可以指定 Dev Services 属性以根据 数据库的 Dev Services 指南创建命名的数据源。

命名的数据源注入

当使用多个数据源时，每个 DataSource 也有 io.quarkus.agroal.DataSource 限定符，并将数据源的名称作为值。

通过使用上一节中提到的属性来配置三个不同的数据源，按如下方式注入每个数据源

@Inject
AgroalDataSource defaultDataSource;

@Inject
@DataSource("users")
AgroalDataSource usersDataSource;

@Inject
@DataSource("inventory")
AgroalDataSource inventoryDataSource;

激活或停用数据源

当在构建时配置数据源，并且在运行时设置其 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:thin:@localhost:1521/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."

通过此设置，请确保仅访问 活动的 数据源。为此，请注入带有 @Any 限定符的 InjectableInstance<DataSource> 或 InjectableInstance<Pool> 并调用 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 生产者重定向到当前活动的命名数据源。这允许直接注入它，如下所示

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()) { (3)
            return oracleDataSourceBean.get();
        } else {
            throw new RuntimeException("No active datasource!");
        }
    }
}

@ApplicationScoped
public class MyConsumer {
    @Inject
    DataSource dataSource; (4)

    public void doSomething() {
        // .. just use the injected datasource ...
    }
}
1 不要直接注入 DataSource 或 AgroalDatasource。注入不活动的 bean 会导致启动失败。相反，注入 InjectableInstance<DataSource> 或 InjectableInstance<AgroalDataSource>。
2 声明一个 CDI 生产者方法来定义默认数据源。它根据哪个数据源处于活动状态来选择 PostgreSQL 或 Oracle。
3 在检索 bean 之前，请检查 bean 是否处于活动状态。
4 注入唯一活动的数据源。

在单个事务中使用多个数据源

默认情况下，数据源上的 XA 支持处于禁用状态。因此，一个事务最多只能包含一个数据源。尝试在同一事务中访问多个非 XA 数据源会导致类似于以下的异常

...
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 数据源

  1. 请确保您的 JDBC 驱动程序支持 XA。所有 支持的 JDBC 驱动程序都支持，但 其他 JDBC 驱动程序 可能不支持。

  2. 确保您的数据库服务器已配置为启用 XA。

  3. 通过将 quarkus.datasource[.optional name].jdbc.transactions 设置为 xa 来显式为每个相关数据源启用 XA 支持。

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

目前不支持响应式数据源上的 XA 事务。

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

如果无法为您的数据源之一启用 XA

如果没有其他解决方案可行，并且需要与 Quarkus 3.8 或更早版本兼容，请将 quarkus.transaction-manager.unsafe-multiple-last-resources 设置为 allow，以启用跨多个非 XA 数据源的不安全事务处理。

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

或者，允许相同的不安全行为，但在发生时发出警告

  • 将属性设置为 warn-each 会记录 每个 违规事务的警告。

  • 将属性设置为 warn-first 会记录 第一个 违规事务的警告。

我们不建议使用此配置属性，并计划在将来删除它。您应该相应地更新您的应用程序。如果您认为您的用例证明保留此选项是合理的，请在 Quarkus 跟踪器 中打开一个问题，解释原因。

数据源集成

数据源运行状况检查

如果您使用 quarkus-smallrye-health 扩展，则 quarkus-agroal 和响应式客户端扩展会自动添加就绪运行状况检查以验证数据源。

当您访问应用程序的运行状况就绪端点（默认为 /q/health/ready）时，您会收到有关数据源验证状态的信息。如果您有多个数据源，则会检查所有数据源，如果发生单个数据源验证失败，则状态会更改为 DOWN。

可以使用 quarkus.datasource.health.enabled 属性禁用此行为。

要仅从运行状况检查中排除特定数据源

quarkus.datasource."datasource-name".health-exclude=true

数据源指标

如果您使用 quarkus-micrometer 或 quarkus-smallrye-metrics 扩展，则 quarkus-agroal 可以将一些数据源相关指标贡献给指标注册表。可以通过将 quarkus.datasource.metrics.enabled 属性设置为 true 来激活此功能。

为了使公开的指标包含任何实际值，必须通过 Agroal 机制在内部启用指标收集。默认情况下，当存在指标扩展时，此指标收集机制对所有数据源启用，并且启用了 Agroal 扩展的指标。

要禁用特定数据源的指标，请将 quarkus.datasource.jdbc.enable-metrics 设置为 false，或者为命名的数据源应用 quarkus.datasource.<数据源名称>.jdbc.enable-metrics。如果禁用收集它们的机制，这将禁用收集指标并在 /q/metrics 端点中公开它们。

相反，将 quarkus.datasource.jdbc.enable-metrics 设置为 true，或者为命名的数据源显式启用指标收集 quarkus.datasource.<数据源名称>.jdbc.enable-metrics，即使未使用指标扩展也是如此。如果您需要以编程方式访问收集的指标，这将非常有用。在对注入的 AgroalDataSource 实例调用 dataSource.getMetrics() 后，它们可用。

如果禁用此数据源的指标收集，则所有值都将为零。

数据源跟踪

要将跟踪与数据源一起使用，您需要将 quarkus-opentelemetry 扩展添加到您的项目中。

您不需要声明不同的驱动程序来启用跟踪。如果您使用 JDBC 驱动程序，则需要按照 OpenTelemetry 扩展中的说明 进行操作。

即使所有跟踪基础设施都已就位，默认情况下也不会启用数据源跟踪，您需要通过设置此属性来启用它

# enable tracing
quarkus.datasource.jdbc.telemetry=true

Narayana 事务管理器集成

如果 Narayana JTA 扩展也可用，则集成是自动的。

您可以通过设置 transactions 配置属性来覆盖此设置

  • quarkus.datasource.jdbc.transactions 用于默认的未命名数据源

  • quarkus.datasource.<数据源名称>.jdbc.transactions 用于命名的数据源

当数据源启用了 XA（通过将 quarkus.datasource[.optional name].jdbc.transactions to xa) 设置为 xa）并且事务恢复系统已启用（通过将属性 quarkus.transaction-manager.enable-recovery 设置为 true）时，数据源会自动注册以进行恢复。这是一个安全的默认设置，但您可以通过设置 quarkus.datasource.jdbc.enable-recovery/quarkus.datasource."datasource-name".jdbc.enable-recovery 为 false，按每个数据源覆盖此行为。仅对高级用例使用此功能，如果您知道不需要恢复，否则可能会导致数据丢失和/或数据不可用，因为资源可能会无限期锁定。

有关更多信息，请参阅下面的 配置参考 部分。

为了方便使用 JDBC 将事务日志存储在数据库中，请参阅 在 Quarkus 中使用事务 指南的 配置要存储在数据源中的事务日志 部分。

命名的数据源

当使用 Dev Services 时，将始终创建默认数据源，但是要指定命名的数据源，您需要至少一个构建时属性，以便 Quarkus 可以检测如何创建数据源。

您通常会指定 db-kind 属性或通过设置 quarkus.datasource."name".devservices.enabled=true 来显式启用 Dev Services。

使用内存数据库进行测试

某些数据库（如 H2 和 Derby）通常在 嵌入模式 下使用，作为一种快速运行集成测试的工具。

建议的方法是使用用于生产的数据库，以获得尽可能接近生产环境的结果。通过 Dev Services 可以更容易地实现这一点，因为它们不需要配置并且启动速度相对较快。但是，也可以在需要运行简单集成测试的情况下使用 JVM 驱动的数据库。

支持和限制

嵌入式数据库（H2 和 Derby）在 JVM 模式下工作。对于本机模式，以下限制适用

  • Derby 无法在本机模式下嵌入到应用程序中。但是，Quarkus Derby 扩展允许本机编译 Derby JDBC 客户端，支持 远程 连接。

  • 不建议在本机镜像中嵌入 H2。考虑使用替代方法，例如，使用与单独数据库的远程连接。

运行集成测试

  1. 添加对以下 Maven 坐标下的额外工具提供的工件的依赖

    • io.quarkus:quarkus-test-h2 用于 H2

    • io.quarkus:quarkus-test-derby 用于 Derby

      这将允许您测试您的应用程序，即使它被编译为本机可执行文件，而数据库将作为 JVM 进程运行。

  2. 在集成测试中的任何类上添加以下特定注释，以便在 JVM 或本机可执行文件中运行集成测试

    • @QuarkusTestResource(H2DatabaseTestResource.class)

    • @QuarkusTestResource(DerbyDatabaseTestResource.class)

      这可确保测试套件启动和终止托管数据库，如测试执行所需，在一个单独的进程中。

      H2 示例
      package my.app.integrationtests.db;

import io.quarkus.test.common.QuarkusTestResource;
import io.quarkus.test.h2.H2DatabaseTestResource;

@QuarkusTestResource(H2DatabaseTestResource.class)
public class TestResources {
}

  3. 配置与托管数据库的连接

    quarkus.datasource.db-kind=h2
quarkus.datasource.jdbc.url=jdbc:h2:tcp:///mem:test

参考

通用数据源配置参考

构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖

配置属性

类型

默认

quarkus.datasource.health.enabled

如果存在 smallrye-health 扩展，是否发布健康检查。

这是一个全局设置，不特定于数据源。

环境变量：QUARKUS_DATASOURCE_HEALTH_ENABLED

显示更多

布尔值

true

quarkus.datasource.metrics.enabled

如果存在指标扩展，是否发布数据源指标。

这是一个全局设置，不特定于数据源。

这不同于“jdbc.enable-metrics”属性，该属性需要在 JDBC 数据源级别设置才能为该数据源启用指标收集。

环境变量：QUARKUS_DATASOURCE_METRICS_ENABLED

显示更多

布尔值

false

quarkus.datasource.db-kind

quarkus.datasource."数据源名称".db-kind

我们将连接到的数据库的种类（例如，h2、postgresql…​）。

环境变量：QUARKUS_DATASOURCE_DB_KIND

显示更多

字符串

quarkus.datasource.db-version

quarkus.datasource."数据源名称".db-version

我们将连接到的数据库的版本（例如，“10.0”）。

此处设置的版本号应遵循与数据库 JDBC 驱动程序的 java.sql.DatabaseMetaData#getDatabaseProductVersion() 返回的字符串相同的编号方案。此编号方案可能与数据库最流行的编号方案不同；例如，Microsoft SQL Server 2016 将是版本 13。

通常，此处设置的版本应尽可能高，但必须低于或等于应用程序将连接到的任何数据库的版本。

较高的版本可以实现更好的性能并使用更多功能（例如，Hibernate ORM 可能会生成更高效的 SQL，避免解决方法并利用更多数据库功能），但如果它高于您要连接的数据库的版本，则可能会导致运行时异常（例如，Hibernate ORM 可能会生成您的数据库将拒绝的无效 SQL）。

某些扩展（例如 Hibernate ORM 扩展）将尝试在启动时针对实际数据库版本检查此版本，如果实际版本较低，则会导致启动失败，或者在无法访问数据库时发出警告。

此属性的默认值特定于每个扩展；Hibernate ORM 扩展将默认为它支持的最旧版本。

环境变量：QUARKUS_DATASOURCE_DB_VERSION

显示更多

字符串

quarkus.datasource.health-exclude

quarkus.datasource."数据源名称".health-exclude

如果启用了数据源的常规运行状况检查，是否应将此特定数据源从运行状况检查中排除。

默认情况下，运行状况检查包括所有配置的数据源（如果已启用）。

环境变量：QUARKUS_DATASOURCE_HEALTH_EXCLUDE

显示更多

布尔值

false

quarkus.datasource.active

quarkus.datasource."数据源名称".active

此数据源在运行时是否应处于活动状态。

请参阅 文档的此部分。

环境变量：QUARKUS_DATASOURCE_ACTIVE

显示更多

布尔值

如果设置了 URL，则为 `true`，否则为 `false`

quarkus.datasource.username

quarkus.datasource."数据源名称".username

数据源用户名

环境变量：QUARKUS_DATASOURCE_USERNAME

显示更多

字符串

quarkus.datasource.password

quarkus.datasource."数据源名称".password

数据源密码

环境变量：QUARKUS_DATASOURCE_PASSWORD

显示更多

字符串

quarkus.datasource.credentials-provider

quarkus.datasource."数据源名称".credentials-provider

凭据提供程序名称

环境变量：QUARKUS_DATASOURCE_CREDENTIALS_PROVIDER

显示更多

字符串

quarkus.datasource.credentials-provider-name

quarkus.datasource."数据源名称".credentials-provider-name

凭据提供程序 bean 名称。

这是实现 CredentialsProvider 的 bean 的 bean 名称（如 @Named 中）。当存在多个凭据提供程序时，它用于选择凭据提供程序 bean。当只有一个凭据提供程序可用时，这是不必要的。

对于 Vault，凭据提供程序 bean 名称为 vault-credentials-provider。

环境变量：QUARKUS_DATASOURCE_CREDENTIALS_PROVIDER_NAME

显示更多

字符串

Dev Services

类型

默认

quarkus.datasource.devservices.enabled

quarkus.datasource."数据源名称".devservices.enabled

此开发服务是否应在开发模式或测试中随应用程序一起启动。

默认情况下启用 Dev Service，除非显式设置连接配置（例如 JDBC URL 或反应式客户端 URL）。

环境变量：QUARKUS_DATASOURCE_DEVSERVICES_ENABLED

显示更多

布尔值

quarkus.datasource.devservices.image-name

quarkus.datasource."数据源名称".devservices.image-name

基于容器的 Dev Service 提供程序的容器映像名称。

如果提供程序不是基于容器的数据库，例如 H2 或 Derby，则这不起作用。

环境变量：QUARKUS_DATASOURCE_DEVSERVICES_IMAGE_NAME

显示更多

字符串

quarkus.datasource.devservices.container-env."environment-variable-name"

quarkus.datasource."数据源名称".devservices.container-env."环境变量名"

传递给容器的环境变量。

环境变量：QUARKUS_DATASOURCE_DEVSERVICES_CONTAINER_ENV__ENVIRONMENT_VARIABLE_NAME_

显示更多

Map<String,String>

quarkus.datasource.devservices.container-properties."property-key"

quarkus.datasource."数据源名称".devservices.container-properties."属性键"

传递用于其他容器配置的通用属性。

此处定义的属性是特定于数据库的，并且在每个数据库 dev service 实现中进行专门解释。

环境变量：QUARKUS_DATASOURCE_DEVSERVICES_CONTAINER_PROPERTIES__PROPERTY_KEY_

显示更多

Map<String,String>

quarkus.datasource.devservices.properties."property-key"

quarkus.datasource."数据源名称".devservices.properties."属性键"

添加到数据库连接 URL 的通用属性。

环境变量：QUARKUS_DATASOURCE_DEVSERVICES_PROPERTIES__PROPERTY_KEY_

显示更多

Map<String,String>

quarkus.datasource.devservices.port

quarkus.datasource."数据源名称".devservices.port

开发服务将侦听的可选固定端口。

如果未定义，将随机选择端口。

环境变量：QUARKUS_DATASOURCE_DEVSERVICES_PORT

显示更多

整数

quarkus.datasource.devservices.command

quarkus.datasource."数据源名称".devservices.command

用于基于容器的 Dev Service 提供程序的容器启动命令。

如果提供程序不是基于容器的数据库，例如 H2 或 Derby，则这不起作用。

环境变量：QUARKUS_DATASOURCE_DEVSERVICES_COMMAND

显示更多

字符串

quarkus.datasource.devservices.db-name

quarkus.datasource."数据源名称".devservices.db-name

如果此 Dev Service 支持覆盖数据库名称，则要使用的数据库名称。

环境变量：QUARKUS_DATASOURCE_DEVSERVICES_DB_NAME

显示更多

字符串

quarkus.datasource.devservices.username

quarkus.datasource."数据源名称".devservices.username

如果此 Dev Service 支持覆盖用户名，则要使用的用户名。

环境变量: QUARKUS_DATASOURCE_DEVSERVICES_USERNAME

显示更多

字符串

quarkus.datasource.devservices.password

quarkus.datasource."数据源名称".devservices.password

如果此 Dev Service 支持覆盖密码，则要使用的密码。

环境变量: QUARKUS_DATASOURCE_DEVSERVICES_PASSWORD

显示更多

字符串

quarkus.datasource.devservices.init-script-path

quarkus.datasource."数据源名称".devservices.init-script-path

要从类路径加载并应用于 Dev Service 数据库的 SQL 脚本的路径。

如果提供程序不是基于容器的数据库，例如 H2 或 Derby，则这不起作用。

环境变量: QUARKUS_DATASOURCE_DEVSERVICES_INIT_SCRIPT_PATH

显示更多

字符串列表

quarkus.datasource.devservices.init-privileged-script-path

quarkus.datasource."数据源名称".devservices.init-privileged-script-path

从类路径加载并应用于 Dev Service 数据库的 SQL 脚本的路径，使用 SYS 特权用户。并非所有数据库都提供特权用户。 在这些情况下，该属性将被忽略。如果提供程序不是基于容器的数据库（例如 H2 或 Derby），则这无效。

环境变量: QUARKUS_DATASOURCE_DEVSERVICES_INIT_PRIVILEGED_SCRIPT_PATH

显示更多

字符串列表

quarkus.datasource.devservices.volumes."host-path"

quarkus.datasource."数据源名称".devservices.volumes."主机路径"

要映射到容器的卷。

映射键对应于主机位置；映射值是容器位置。如果主机位置以“classpath:”开头，则映射将以只读权限从类路径加载资源。

使用文件系统位置时，将以读写权限生成卷，这可能会导致文件系统中的数据丢失或修改。

如果提供程序不是基于容器的数据库，例如 H2 或 Derby，则这不起作用。

环境变量: QUARKUS_DATASOURCE_DEVSERVICES_VOLUMES__HOST_PATH_

显示更多

Map<String,String>

quarkus.datasource.devservices.reuse

quarkus.datasource."数据源名称".devservices.reuse

是否在开发模式会话或测试套件执行之后保持开发服务容器运行，以便在下一个开发模式会话或测试套件执行中重用它们。

在开发模式会话或测试套件执行中，只要 Dev Services 的配置（用户名、密码、环境、端口绑定等）没有更改，Quarkus 将始终重用它们。 此功能专门用于在 Quarkus 未运行时 保持容器运行，以便在多次运行中重复使用它们。

此功能需要在 testcontainers.properties 中显式启用，可能需要更改您在开发模式和测试中配置数据初始化的方式，并且可能会无限期地保持容器运行，迫使您手动停止和删除它们。有关更多信息，请参阅 文档的此部分。

此配置属性默认设置为 true，因此主要用于 禁用 重用，如果您在 testcontainers.properties 中启用了它，但只想将其用于某些 Quarkus 应用程序或数据源。

环境变量: QUARKUS_DATASOURCE_DEVSERVICES_REUSE

显示更多

布尔值

true

quarkus.datasource.devservices.show-logs

quarkus.datasource."datasource-name".devservices.show-logs

日志是否应由 JBoss 记录器使用。

如果提供程序不是基于容器的数据库，例如 H2 或 Derby，则这不起作用。

环境变量: QUARKUS_DATASOURCE_DEVSERVICES_SHOW_LOGS

显示更多

布尔值

false

JDBC 配置参考

构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖

配置属性

类型

默认

quarkus.datasource.dev-ui.enabled

激活或禁用 dev ui 页面。

环境变量: QUARKUS_DATASOURCE_DEV_UI_ENABLED

显示更多

布尔值

true

quarkus.datasource.dev-ui.allow-sql

在 Dev UI 页面中允许 sql 查询

环境变量: QUARKUS_DATASOURCE_DEV_UI_ALLOW_SQL

显示更多

布尔值

false

quarkus.datasource.dev-ui.append-to-default-select

将此附加到为获取表值而完成的选择。例如：LIMIT 100 或 TOP 100

环境变量: QUARKUS_DATASOURCE_DEV_UI_APPEND_TO_DEFAULT_SELECT

显示更多

字符串

quarkus.datasource.dev-ui.allowed-db-host

允许的数据库主机。 默认情况下，仅允许 localhost。 此处提供的任何主机也将被允许。 您可以使用特殊值 * 来允许任何 DB 主机。

环境变量: QUARKUS_DATASOURCE_DEV_UI_ALLOWED_DB_HOST

显示更多

字符串

quarkus.datasource.jdbc

quarkus.datasource."datasource-name".jdbc

如果我们为此数据源创建一个 JDBC 数据源。

环境变量: QUARKUS_DATASOURCE_JDBC

显示更多

布尔值

true

quarkus.datasource.jdbc.driver

quarkus.datasource."datasource-name".jdbc.driver

数据源驱动程序类名

环境变量: QUARKUS_DATASOURCE_JDBC_DRIVER

显示更多

字符串

quarkus.datasource.jdbc.transactions

quarkus.datasource."datasource-name".jdbc.transactions

我们是否要使用常规 JDBC 事务、XA 或禁用所有事务功能。

启用 XA 时，您将需要一个实现 javax.sql.XADataSource 的驱动程序。

环境变量: QUARKUS_DATASOURCE_JDBC_TRANSACTIONS

显示更多

enabled将 JDBC 数据源与 Quarkus 的 JTA TransactionManager 集成。 这是默认设置。、 xa与 enabled 类似，也启用与 Quarkus 的 JTA TransactionManager 的集成，但也启用 XA 事务。 需要实现 javax.sql.XADataSource 的 JDBC 驱动程序、 disabled禁用 Agroal 与 Narayana TransactionManager 的集成。 这通常是一个坏主意，仅在特殊情况下有用：请确保在没有深入了解其含义的情况下不要使用它。

enabled将 JDBC 数据源与 Quarkus 的 JTA TransactionManager 集成。 这是默认设置。

quarkus.datasource.jdbc.telemetry

quarkus.datasource."datasource-name".jdbc.telemetry

启用 OpenTelemetry JDBC instrumentation。

环境变量: QUARKUS_DATASOURCE_JDBC_TELEMETRY

显示更多

布尔值

false

quarkus.datasource.jdbc.url

quarkus.datasource."datasource-name".jdbc.url

数据源 URL

环境变量: QUARKUS_DATASOURCE_JDBC_URL

显示更多

字符串

quarkus.datasource.jdbc.initial-size

quarkus.datasource."datasource-name".jdbc.initial-size

池的初始大小。 通常，您会希望将初始大小设置为至少与最小大小匹配，但这并非强制执行，以便允许那些喜欢在启动时延迟初始化连接的架构，同时能够在启动后维持最小池大小。

环境变量: QUARKUS_DATASOURCE_JDBC_INITIAL_SIZE

显示更多

整数

quarkus.datasource.jdbc.min-size

quarkus.datasource."datasource-name".jdbc.min-size

数据源池的最小大小

环境变量: QUARKUS_DATASOURCE_JDBC_MIN_SIZE

显示更多

整数

0

quarkus.datasource.jdbc.max-size

quarkus.datasource."datasource-name".jdbc.max-size

数据源池的最大大小

环境变量: QUARKUS_DATASOURCE_JDBC_MAX_SIZE

显示更多

整数

20

quarkus.datasource.jdbc.background-validation-interval

quarkus.datasource."datasource-name".jdbc.background-validation-interval

我们在后台验证空闲连接的间隔。

设置为 0 以禁用后台验证。

环境变量: QUARKUS_DATASOURCE_JDBC_BACKGROUND_VALIDATION_INTERVAL

显示更多

Duration 

2M

quarkus.datasource.jdbc.foreground-validation-interval

quarkus.datasource."datasource-name".jdbc.foreground-validation-interval

对空闲时间超过指定间隔的连接执行前台验证。

环境变量: QUARKUS_DATASOURCE_JDBC_FOREGROUND_VALIDATION_INTERVAL

显示更多

Duration 

quarkus.datasource.jdbc.acquisition-timeout

quarkus.datasource."datasource-name".jdbc.acquisition-timeout

取消获取新连接之前的超时

环境变量: QUARKUS_DATASOURCE_JDBC_ACQUISITION_TIMEOUT

显示更多

Duration 

5S

quarkus.datasource.jdbc.leak-detection-interval

quarkus.datasource."datasource-name".jdbc.leak-detection-interval

我们检查连接泄漏的间隔。

环境变量: QUARKUS_DATASOURCE_JDBC_LEAK_DETECTION_INTERVAL

显示更多

Duration 

此功能默认禁用。

quarkus.datasource.jdbc.idle-removal-interval

quarkus.datasource."datasource-name".jdbc.idle-removal-interval

我们尝试删除空闲连接的间隔。

环境变量: QUARKUS_DATASOURCE_JDBC_IDLE_REMOVAL_INTERVAL

显示更多

Duration 

5M

quarkus.datasource.jdbc.max-lifetime

quarkus.datasource."datasource-name".jdbc.max-lifetime

连接的最长生命周期。

环境变量: QUARKUS_DATASOURCE_JDBC_MAX_LIFETIME

显示更多

Duration 

默认情况下，对连接的生命周期没有限制。

quarkus.datasource.jdbc.transaction-isolation-level

quarkus.datasource."datasource-name".jdbc.transaction-isolation-level

事务隔离级别。

环境变量: QUARKUS_DATASOURCE_JDBC_TRANSACTION_ISOLATION_LEVEL

显示更多

undefined, none, read-uncommitted, read-committed, repeatable-read, serializable

quarkus.datasource.jdbc.extended-leak-report

quarkus.datasource."datasource-name".jdbc.extended-leak-report

收集并显示有关泄漏连接的额外故障排除信息。

环境变量: QUARKUS_DATASOURCE_JDBC_EXTENDED_LEAK_REPORT

显示更多

布尔值

false

quarkus.datasource.jdbc.flush-on-close

quarkus.datasource."datasource-name".jdbc.flush-on-close

允许在返回到池时刷新连接。 默认情况下未启用。

环境变量: QUARKUS_DATASOURCE_JDBC_FLUSH_ON_CLOSE

显示更多

布尔值

false

quarkus.datasource.jdbc.detect-statement-leaks

quarkus.datasource."datasource-name".jdbc.detect-statement-leaks

启用后，当应用程序在没有关闭所有打开的语句的情况下将连接返回到池时，Agroal 将能够生成警告。 这与跟踪打开的连接无关。 为获得最佳性能而禁用，但仅当高度确信不会发生泄漏时才禁用。

环境变量: QUARKUS_DATASOURCE_JDBC_DETECT_STATEMENT_LEAKS

显示更多

布尔值

true

quarkus.datasource.jdbc.new-connection-sql

quarkus.datasource."datasource-name".jdbc.new-connection-sql

首次使用连接时执行的查询。

环境变量: QUARKUS_DATASOURCE_JDBC_NEW_CONNECTION_SQL

显示更多

字符串

quarkus.datasource.jdbc.validation-query-sql

quarkus.datasource."datasource-name".jdbc.validation-query-sql

为验证连接而执行的查询。

环境变量: QUARKUS_DATASOURCE_JDBC_VALIDATION_QUERY_SQL

显示更多

字符串

quarkus.datasource.jdbc.validation-query-timeout

quarkus.datasource."datasource-name".jdbc.validation-query-timeout

连接验证查询的超时

环境变量: QUARKUS_DATASOURCE_JDBC_VALIDATION_QUERY_TIMEOUT

显示更多

Duration 

quarkus.datasource.jdbc.validate-on-borrow

quarkus.datasource."datasource-name".jdbc.validate-on-borrow

强制在获取之前进行连接验证（前台验证），而不管空闲状态如何。

由于在每次调用时执行验证的开销，建议依赖默认的空闲验证，并将此设置为 false。

环境变量: QUARKUS_DATASOURCE_JDBC_VALIDATE_ON_BORROW

显示更多

布尔值

false

quarkus.datasource.jdbc.pooling-enabled

quarkus.datasource."datasource-name".jdbc.pooling-enabled

禁用池以防止重用连接。 当外部池管理连接的生命周期时，请使用此选项。

环境变量: QUARKUS_DATASOURCE_JDBC_POOLING_ENABLED

显示更多

布尔值

true

quarkus.datasource.jdbc.enable-recovery

quarkus.datasource."datasource-name".jdbc.enable-recovery

是否为此数据源启用恢复。

通常，事务管理器将在恢复期间调用 XA 连接上的 xa_recover ()，以获取当前处于准备状态或启发式完成状态的事务分支列表。 但是，可能会发生多个 XA 连接连接到同一数据源的情况，这些连接都将返回相同的分支集，并且出于提高性能的原因，只能使用一个连接进行 recover() 调用。 此配置属性的默认值为 true，因为当只有一个连接时，连接能够报告其准备好的或启发式完成的分支列表对于数据一致性至关重要。

环境变量: QUARKUS_DATASOURCE_JDBC_ENABLE_RECOVERY

显示更多

布尔值

true

quarkus.datasource.jdbc.transaction-requirement

quarkus.datasource."datasource-name".jdbc.transaction-requirement

获取连接时需要活动事务。 推荐用于生产。 警告：某些扩展在不保存事务的情况下获取连接，例如模式更新和模式验证。 将此设置设置为 STRICT 可能会导致这些情况下出现故障。

环境变量: QUARKUS_DATASOURCE_JDBC_TRANSACTION_REQUIREMENT

显示更多

off、warn、strict

quarkus.datasource.jdbc.additional-jdbc-properties."property-key"

quarkus.datasource."datasource-name".jdbc.additional-jdbc-properties."property-key"

创建新连接时要传递给 JDBC 驱动程序的其他未指定属性。

环境变量: QUARKUS_DATASOURCE_JDBC_ADDITIONAL_JDBC_PROPERTIES__PROPERTY_KEY_

显示更多

Map<String,String>

quarkus.datasource.jdbc.telemetry.enabled

quarkus.datasource."datasource-name".jdbc.telemetry.enabled

启用 OpenTelemetry JDBC instrumentation。

环境变量: QUARKUS_DATASOURCE_JDBC_TELEMETRY_ENABLED

显示更多

布尔值

如果 quarkus.datasource.jdbc.telemetry=false 则为 false，如果 quarkus.datasource.jdbc.telemetry=true 则为 true
关于 Duration 格式

要写入持续时间值，请使用标准 java.time.Duration 格式。 有关更多信息，请参阅 Duration#parse() Java API 文档。

您还可以使用简化的格式，以数字开头

  • 如果该值仅为一个数字，则表示以秒为单位的时间。

  • 如果该值是一个数字后跟 ms，则表示以毫秒为单位的时间。

在其他情况下，简化格式将被转换为 java.time.Duration 格式以进行解析

  • 如果该值是一个数字后跟 h、m 或 s，则在其前面加上 PT。

  • 如果该值是一个数字后跟 d，则在其前面加上 P。

JDBC URL 参考

每个受支持的数据库都包含不同的 JDBC URL 配置选项。 以下部分概述了每个数据库 URL 以及指向官方文档的链接。

DB2

jdbc:db2://<serverName>[:<portNumber>]/<databaseName>[:<key1>=<value>;[<key2>=<value2>;]]

示例

jdbc:db2://:50000/MYDB:user=dbadm;password=dbadm;

有关 URL 语法和其他支持的选项的更多信息，请参阅官方文档。

Derby

jdbc:derby:[//serverName[:portNumber]/][memory:]databaseName[;property=value[;property=value]]

示例

jdbc:derby://:1527/myDB, jdbc:derby:memory:myDB;create=true

Derby 是一个嵌入式数据库，可以作为服务器运行，基于文件运行，也可以完全在内存中运行。 所有这些选项都可用，如上所列。

有关更多信息，请参阅官方文档。

H2

jdbc:h2:{ {.|mem:}[name] | [file:]fileName | {tcp|ssl}:[//]server[:port][,server2[:port]]/name }[;key=value…​]

示例

jdbc:h2:tcp:///~/test, jdbc:h2:mem:myDB

H2 是一个可以在嵌入式或服务器模式下运行的数据库。 它可以使用文件存储或完全在内存中运行。 所有这些选项都可用，如上所列。

有关更多信息，请参阅官方文档。

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))]

示例

jdbc:mariadb://:3306/test

有关更多信息，请参阅官方文档。

Microsoft SQL server

jdbc:sqlserver://[serverName[\instanceName][:portNumber]][;property=value[;property=value]]

示例

jdbc:sqlserver://:1433;databaseName=AdventureWorks

Microsoft SQL Server JDBC 驱动程序的工作方式与其他驱动程序基本相同。

有关更多信息，请参阅官方文档。

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))]

示例

jdbc:mysql://:3306/test

有关更多信息，请参阅官方文档。

MySQL 限制

将 Quarkus 应用程序编译为本机映像时，MySQL 对 JMX 和 Oracle Cloud Infrastructure (OCI) 集成的支持将被禁用，因为它们与 GraalVM 本机映像不兼容。

  • 缺少 JMX 支持是在本机模式下运行的自然结果，不太可能得到解决。

  • 不支持与 OCI 的集成。

Oracle

jdbc:oracle:driver_type:@database_specifier

示例

jdbc:oracle:thin:@localhost:1521/ORCL_SVC

有关更多信息，请参阅官方文档。

PostgreSQL

jdbc:postgresql:[//][host][:port][/database][?key=value…​]

示例

jdbc:postgresql:///test

不同部分的默认值如下

主机

localhost

端口

5432

数据库

与用户名相同的名称

有关其他参数的更多信息，请参阅官方文档。

Quarkus 扩展和数据库驱动程序参考

下表列出了内置的 db-kind 值、相应的 Quarkus 扩展以及这些扩展使用的 JDBC 驱动程序。

使用内置数据源类型之一时，JDBC 和 Reactive 驱动程序会自动解析以匹配这些表中的值。

表 1. 数据库平台类型到 JDBC 驱动程序的映射
数据库类型 Quarkus 扩展 驱动程序

db2

quarkus-jdbc-db2

  • JDBC: com.ibm.db2.jcc.DB2Driver

  • XA: com.ibm.db2.jcc.DB2XADataSource

derby

quarkus-jdbc-derby

  • JDBC: org.apache.derby.jdbc.ClientDriver

  • XA: org.apache.derby.jdbc.ClientXADataSource

h2

quarkus-jdbc-h2

  • JDBC: org.h2.Driver

  • XA: org.h2.jdbcx.JdbcDataSource

mariadb

quarkus-jdbc-mariadb

  • JDBC: org.mariadb.jdbc.Driver

  • XA: org.mariadb.jdbc.MariaDbDataSource

mssql

quarkus-jdbc-mssql

  • JDBC: com.microsoft.sqlserver.jdbc.SQLServerDriver

  • XA: com.microsoft.sqlserver.jdbc.SQLServerXADataSource

mysql

quarkus-jdbc-mysql

  • JDBC: com.mysql.cj.jdbc.Driver

  • XA: com.mysql.cj.jdbc.MysqlXADataSource

oracle

quarkus-jdbc-oracle

  • JDBC: oracle.jdbc.driver.OracleDriver

  • XA: oracle.jdbc.xa.client.OracleXADataSource

postgresql

quarkus-jdbc-postgresql

  • JDBC: org.postgresql.Driver

  • XA: org.postgresql.xa.PGXADataSource
表 2. 数据库类型到 Reactive 驱动程序的映射
数据库类型 Quarkus 扩展 驱动程序

oracle

reactive-oracle-client

io.vertx.oracleclient.spi.OracleDriver

mysql

reactive-mysql-client

io.vertx.mysqlclient.spi.MySQLDriver

mssql

reactive-mssql-client

io.vertx.mssqlclient.spi.MSSQLDriver

postgresql

reactive-pg-client

io.vertx.pgclient.spi.PgDriver

db2

reactive-db2-client

io.vertx.db2client.spi.DB2Driver

这种自动解析在大多数情况下都适用，因此不需要驱动程序配置。

Reactive 数据源配置参考

构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖

配置属性

类型

默认

quarkus.datasource.reactive

quarkus.datasource."datasource-name".reactive

如果我们为此数据源创建一个 Reactive 数据源。

环境变量: QUARKUS_DATASOURCE_REACTIVE

显示更多

布尔值

true

quarkus.datasource.reactive.cache-prepared-statements

quarkus.datasource."datasource-name".reactive.cache-prepared-statements

是否应在客户端缓存预处理语句。

环境变量: QUARKUS_DATASOURCE_REACTIVE_CACHE_PREPARED_STATEMENTS

显示更多

布尔值

false

quarkus.datasource.reactive.url

quarkus.datasource."datasource-name".reactive.url

数据源 URL。

如果设置了多个值，则此数据源将创建一个包含服务器列表而不是单个服务器的池。 该池在连接建立期间使用循环负载平衡进行服务器选择。 请注意，某些驱动程序可能无法在这种情况下容纳多个值。

环境变量: QUARKUS_DATASOURCE_REACTIVE_URL

显示更多

字符串列表

quarkus.datasource.reactive.max-size

quarkus.datasource."datasource-name".reactive.max-size

数据源池的最大大小。

环境变量: QUARKUS_DATASOURCE_REACTIVE_MAX_SIZE

显示更多

整数

20

quarkus.datasource.reactive.event-loop-size

quarkus.datasource."datasource-name".reactive.event-loop-size

创建新的连接对象时，池会为其分配一个事件循环。

当 #event-loop-size 设置为严格的正值时，池将以循环方式分配指定数量的事件循环。 默认情况下，使用 Quarkus 配置或计算的事件循环数。 如果 #event-loop-size 设置为零或负值，则池会将当前事件循环分配给新连接。

环境变量: QUARKUS_DATASOURCE_REACTIVE_EVENT_LOOP_SIZE

显示更多

整数

quarkus.datasource.reactive.trust-all

quarkus.datasource."datasource-name".reactive.trust-all

是否应信任所有服务器证书。

环境变量: QUARKUS_DATASOURCE_REACTIVE_TRUST_ALL

显示更多

布尔值

false

quarkus.datasource.reactive.trust-certificate-pem

quarkus.datasource."datasource-name".reactive.trust-certificate-pem

默认情况下禁用 PEM 信任配置。

环境变量: QUARKUS_DATASOURCE_REACTIVE_TRUST_CERTIFICATE_PEM

显示更多

布尔值

false

quarkus.datasource.reactive.trust-certificate-pem.certs

quarkus.datasource."datasource-name".reactive.trust-certificate-pem.certs

信任证书文件（Pem 格式）的逗号分隔列表。

环境变量: QUARKUS_DATASOURCE_REACTIVE_TRUST_CERTIFICATE_PEM_CERTS

显示更多

字符串列表

quarkus.datasource.reactive.trust-certificate-jks

quarkus.datasource."datasource-name".reactive.trust-certificate-jks

默认情况下禁用 JKS 配置。

环境变量: QUARKUS_DATASOURCE_REACTIVE_TRUST_CERTIFICATE_JKS

显示更多

布尔值

false

quarkus.datasource.reactive.trust-certificate-jks.path

quarkus.datasource."datasource-name".reactive.trust-certificate-jks.path

密钥文件（JKS 格式）的路径。

环境变量: QUARKUS_DATASOURCE_REACTIVE_TRUST_CERTIFICATE_JKS_PATH

显示更多

字符串

quarkus.datasource.reactive.trust-certificate-jks.password

quarkus.datasource."datasource-name".reactive.trust-certificate-jks.password

密钥文件的密码。

环境变量: QUARKUS_DATASOURCE_REACTIVE_TRUST_CERTIFICATE_JKS_PASSWORD

显示更多

字符串

quarkus.datasource.reactive.trust-certificate-pfx

quarkus.datasource."datasource-name".reactive.trust-certificate-pfx

默认情况下禁用 PFX 配置。

环境变量: QUARKUS_DATASOURCE_REACTIVE_TRUST_CERTIFICATE_PFX

显示更多

布尔值

false

quarkus.datasource.reactive.trust-certificate-pfx.path

quarkus.datasource."datasource-name".reactive.trust-certificate-pfx.path

密钥文件（PFX 格式）的路径。

环境变量: QUARKUS_DATASOURCE_REACTIVE_TRUST_CERTIFICATE_PFX_PATH

显示更多

字符串

quarkus.datasource.reactive.trust-certificate-pfx.password

quarkus.datasource."datasource-name".reactive.trust-certificate-pfx.password

密钥的密码。

环境变量: QUARKUS_DATASOURCE_REACTIVE_TRUST_CERTIFICATE_PFX_PASSWORD

显示更多

字符串

quarkus.datasource.reactive.key-certificate-pem

quarkus.datasource."datasource-name".reactive.key-certificate-pem

默认情况下禁用 PEM 密钥/证书配置。

环境变量: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_PEM

显示更多

布尔值

false

quarkus.datasource.reactive.key-certificate-pem.keys

quarkus.datasource."datasource-name".reactive.key-certificate-pem.keys

密钥文件（Pem 格式）路径的逗号分隔列表。

环境变量: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_PEM_KEYS

显示更多

字符串列表

quarkus.datasource.reactive.key-certificate-pem.certs

quarkus.datasource."datasource-name".reactive.key-certificate-pem.certs

证书文件（Pem 格式）路径的逗号分隔列表。

环境变量: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_PEM_CERTS

显示更多

字符串列表

quarkus.datasource.reactive.key-certificate-jks

quarkus.datasource."datasource-name".reactive.key-certificate-jks

默认情况下禁用 JKS 配置。

环境变量: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_JKS

显示更多

布尔值

false

quarkus.datasource.reactive.key-certificate-jks.path

quarkus.datasource."datasource-name".reactive.key-certificate-jks.path

密钥文件（JKS 格式）的路径。

环境变量: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_JKS_PATH

显示更多

字符串

quarkus.datasource.reactive.key-certificate-jks.password

quarkus.datasource."datasource-name".reactive.key-certificate-jks.password

密钥文件的密码。

环境变量: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_JKS_PASSWORD

显示更多

字符串

quarkus.datasource.reactive.key-certificate-pfx

quarkus.datasource."datasource-name".reactive.key-certificate-pfx

默认情况下禁用 PFX 配置。

环境变量: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_PFX

显示更多

布尔值

false

quarkus.datasource.reactive.key-certificate-pfx.path

quarkus.datasource."datasource-name".reactive.key-certificate-pfx.path

密钥文件（PFX 格式）的路径。

环境变量: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_PFX_PATH

显示更多

字符串

quarkus.datasource.reactive.key-certificate-pfx.password

quarkus.datasource."datasource-name".reactive.key-certificate-pfx.password

密钥的密码。

环境变量: QUARKUS_DATASOURCE_REACTIVE_KEY_CERTIFICATE_PFX_PASSWORD

显示更多

字符串

quarkus.datasource.reactive.reconnect-attempts

quarkus.datasource."datasource-name".reactive.reconnect-attempts

首次尝试时无法建立池连接时的重新连接尝试次数。

环境变量: QUARKUS_DATASOURCE_REACTIVE_RECONNECT_ATTEMPTS

显示更多

整数

0

quarkus.datasource.reactive.reconnect-interval

quarkus.datasource."datasource-name".reactive.reconnect-interval

首次尝试时无法建立池连接时，重新连接尝试之间的间隔。

环境变量: QUARKUS_DATASOURCE_REACTIVE_RECONNECT_INTERVAL

显示更多

Duration 

PT1S

quarkus.datasource.reactive.hostname-verification-algorithm

quarkus.datasource."datasource-name".reactive.hostname-verification-algorithm

如果应该检查服务器的身份，则要使用的主机名验证算法。应为 HTTPS，LDAPS 或 NONE。NONE 是默认值，并禁用验证。

环境变量: QUARKUS_DATASOURCE_REACTIVE_HOSTNAME_VERIFICATION_ALGORITHM

显示更多

字符串

NONE

quarkus.datasource.reactive.idle-timeout

quarkus.datasource."datasource-name".reactive.idle-timeout

连接在池中保持未使用的最长时间，超过此时间后将被关闭。

环境变量: QUARKUS_DATASOURCE_REACTIVE_IDLE_TIMEOUT

显示更多

Duration 

无超时

quarkus.datasource.reactive.max-lifetime

quarkus.datasource."datasource-name".reactive.max-lifetime

连接在池中保持的最长时间，超过此时间后将在返回时关闭，并在必要时替换。

环境变量: QUARKUS_DATASOURCE_REACTIVE_MAX_LIFETIME

显示更多

Duration 

无超时

quarkus.datasource.reactive.shared

quarkus.datasource."datasource-name".reactive.shared

设置为 true 以在数据源之间共享池。可以有多个共享池，以名称区分，当未设置特定名称时，将使用 __vertx.DEFAULT 名称。

环境变量: QUARKUS_DATASOURCE_REACTIVE_SHARED

显示更多

布尔值

false

quarkus.datasource.reactive.name

quarkus.datasource."datasource-name".reactive.name

设置池名称，当池在数据源之间共享时使用，否则将被忽略。

环境变量: QUARKUS_DATASOURCE_REACTIVE_NAME

显示更多

字符串

quarkus.datasource.reactive.additional-properties."property-key"

quarkus.datasource."datasource-name".reactive.additional-properties."property-key"

其他未指定的属性，以便在启动新连接时直接通过 Reactive SQL Client 传递到数据库。

环境变量: QUARKUS_DATASOURCE_REACTIVE_ADDITIONAL_PROPERTIES__PROPERTY_KEY_

显示更多

Map<String,String>
关于 Duration 格式

要写入持续时间值，请使用标准 java.time.Duration 格式。 有关更多信息，请参阅 Duration#parse() Java API 文档。

您还可以使用简化的格式，以数字开头

  • 如果该值仅为一个数字，则表示以秒为单位的时间。

  • 如果该值是一个数字后跟 ms，则表示以毫秒为单位的时间。

在其他情况下，简化格式将被转换为 java.time.Duration 格式以进行解析

  • 如果该值是一个数字后跟 h、m 或 s，则在其前面加上 PT。

  • 如果该值是一个数字后跟 d，则在其前面加上 P。

Reactive DB2 配置

构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖

配置属性

类型

默认

数据源

类型

默认

quarkus.datasource.reactive.db2.ssl

quarkus.datasource."datasource-name".reactive.db2.ssl

是否启用 SSL/TLS。

环境变量: QUARKUS_DATASOURCE_REACTIVE_DB2_SSL

显示更多

布尔值

false

Reactive MariaDB/MySQL 特定配置

构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖

配置属性

类型

默认

其他命名数据源

类型

默认

quarkus.datasource.reactive.mysql.charset

quarkus.datasource."datasource-name".reactive.mysql.charset

连接字符集。

环境变量: QUARKUS_DATASOURCE_REACTIVE_MYSQL_CHARSET

显示更多

字符串

quarkus.datasource.reactive.mysql.collation

quarkus.datasource."datasource-name".reactive.mysql.collation

连接排序规则。

环境变量: QUARKUS_DATASOURCE_REACTIVE_MYSQL_COLLATION

显示更多

字符串

quarkus.datasource.reactive.mysql.ssl-mode

quarkus.datasource."datasource-name".reactive.mysql.ssl-mode

与服务器连接的所需安全状态。

请参阅 MySQL 参考手册。

环境变量: QUARKUS_DATASOURCE_REACTIVE_MYSQL_SSL_MODE

显示更多

disabled, preferred, required, verify-ca, verify-identity

disabled

quarkus.datasource.reactive.mysql.connection-timeout

quarkus.datasource."datasource-name".reactive.mysql.connection-timeout

连接超时（秒）

环境变量: QUARKUS_DATASOURCE_REACTIVE_MYSQL_CONNECTION_TIMEOUT

显示更多

整数

quarkus.datasource.reactive.mysql.authentication-plugin

quarkus.datasource."datasource-name".reactive.mysql.authentication-plugin

客户端应使用的身份验证插件。默认情况下，它使用服务器在初始握手数据包中指定的插件名称。

环境变量: QUARKUS_DATASOURCE_REACTIVE_MYSQL_AUTHENTICATION_PLUGIN

显示更多

default, mysql-clear-password, mysql-native-password, sha256-password, caching-sha2-password

default

quarkus.datasource.reactive.mysql.pipelining-limit

quarkus.datasource."datasource-name".reactive.mysql.pipelining-limit

可以流水线传输的数据库命令的最大数量。默认情况下，流水线传输已禁用。

环境变量: QUARKUS_DATASOURCE_REACTIVE_MYSQL_PIPELINING_LIMIT

显示更多

整数

quarkus.datasource.reactive.mysql.use-affected-rows

quarkus.datasource."datasource-name".reactive.mysql.use-affected-rows

是否在 UPDATE 语句中返回 WHERE 子句匹配的行数，而不是实际更改的行数。

环境变量: QUARKUS_DATASOURCE_REACTIVE_MYSQL_USE_AFFECTED_ROWS

显示更多

布尔值

false

Reactive Microsoft SQL server 特定配置

构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖

配置属性

类型

默认

数据源

类型

默认

quarkus.datasource.reactive.mssql.packet-size

quarkus.datasource."datasource-name".reactive.mssql.packet-size

TDS 数据包的所需大小（以字节为单位）。

环境变量: QUARKUS_DATASOURCE_REACTIVE_MSSQL_PACKET_SIZE

显示更多

整数

quarkus.datasource.reactive.mssql.ssl

quarkus.datasource."datasource-name".reactive.mssql.ssl

是否启用 SSL/TLS。

环境变量: QUARKUS_DATASOURCE_REACTIVE_MSSQL_SSL

显示更多

布尔值

false

Reactive Oracle 特定配置

构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖

配置属性

类型

默认

未找到配置属性。

Reactive PostgreSQL 特定配置

构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖

配置属性

类型

默认

数据源

类型

默认

quarkus.datasource.reactive.postgresql.pipelining-limit

quarkus.datasource."datasource-name".reactive.postgresql.pipelining-limit

可以流水线传输的数据库命令的最大数量。

环境变量: QUARKUS_DATASOURCE_REACTIVE_POSTGRESQL_PIPELINING_LIMIT

显示更多

整数

quarkus.datasource.reactive.postgresql.ssl-mode

quarkus.datasource."datasource-name".reactive.postgresql.ssl-mode

客户端的 SSL 运行模式。

请参阅 不同模式下提供的保护。

环境变量: QUARKUS_DATASOURCE_REACTIVE_POSTGRESQL_SSL_MODE

显示更多

disable, allow, prefer, require, verify-ca, verify-full

disable

quarkus.datasource.reactive.postgresql.use-layer7-proxy

quarkus.datasource."datasource-name".reactive.postgresql.use-layer7-proxy

7 层代理可以在与实际数据库的多个连接上负载均衡查询。当发生这种情况时，客户端可能会因缺少会话关联而感到困惑，并且可能会发生不必要的错误，例如 ERROR: unnamed prepared statement does not exist (26000)。请参阅 使用 7 层代理

环境变量: QUARKUS_DATASOURCE_REACTIVE_POSTGRESQL_USE_LAYER7_PROXY

显示更多

布尔值

false

Reactive 数据源 URL 参考

DB2

db2://[user[:[password]]@]host[:port][/database][?<key1>=<value1>[&<key2>=<value2>]]

示例

db2://dbuser:secretpassword@database.server.com:50000/mydb

目前，客户端支持以下参数键

  • 主机

  • 端口

  • user

  • 密码

  • 数据库

在连接 URL 中配置参数会覆盖默认属性。

Microsoft SQL server

sqlserver://[user[:[password]]@]host[:port][/database][?<key1>=<value1>[&<key2>=<value2>]]

示例

sqlserver://dbuser:secretpassword@database.server.com:1433/mydb

目前，客户端支持以下参数键

  • 主机

  • 端口

  • user

  • 密码

  • 数据库

在连接 URL 中配置参数会覆盖默认属性。

MySQL / MariaDB

mysql://[user[:[password]]@]host[:port][/database][?<key1>=<value1>[&<key2>=<value2>]]

示例

mysql://dbuser:secretpassword@database.server.com:3211/mydb

目前，客户端支持以下参数键（不区分大小写）

  • 主机

  • 端口

  • user

  • 密码

  • schema

  • socket

  • useAffectedRows

在连接 URL 中配置参数会覆盖默认属性。

Oracle

EZConnect 格式

oracle:thin:@[[protocol:]//]host[:port][/service_name][:server_mode][/instance_name][?connection properties]

示例

oracle:thin:@mydbhost1:5521/mydbservice?connect_timeout=10sec

TNS 别名格式

oracle:thin:@<alias_name>[?connection properties]

示例

oracle:thin:@prod_db?TNS_ADMIN=/work/tns/

PostgreSQL

postgresql://[user[:[password]]@]host[:port][/database][?<key1>=<value1>[&<key2>=<value2>]]

示例

postgresql://dbuser:secretpassword@database.server.com:5432/mydb

目前，客户端支持

  • 以下参数键

    • 主机

    • 端口

    • user

    • 密码

    • dbname

    • sslmode

  • 其他属性，例如

    • application_name

    • fallback_application_name

    • search_path

    • options

在连接 URL 中配置参数会覆盖默认属性。

相关内容

在相同的扩展上

关于相同主题

Quarkus 是开放的。此项目的所有依赖项均可在 Apache Software License 2.0 或兼容许可下获得。 CC by 3.0

本网站使用 Jekyll 构建，托管在 GitHub Pages 上，并且完全开源。如果您想做得更好，请fork 本网站并向我们展示您的作品。

导航
关注我们
获取帮助
语言
Quarkus 由社区项目组成
版权所有 © Quarkus。保留所有权利。有关我们商标的详细信息，请访问我们的商标政策和商标列表。第三方商标归其各自所有者所有，此处提及并不暗示任何认可或关联。