Configure data sources in Quarkus

使用统一的配置模型为 Java 数据库连接（JDBC）和反应式驱动程序定义数据源。应用程序使用数据源来访问关系数据库。Quarkus 提供了一个统一的配置模型来为 Java 数据库连接（JDBC）和反应式数据库驱动程序定义数据源。 Quarkus 使用 Agroal和 Vert.x为 JDBC 和反应式驱动程序提供高性能、可扩展的数据源连接池。quarkus-jdbc- and `quarkus-reactive--client`扩展提供构建时优化，并将配置的数据源与 Quarkus 特性集成，如安全性、运行状况检查和指标。有关使用反应式数据源的更多信息，请参阅 Quarkus Reactive SQL clients指南。此外，请参阅 Quarkus Hibernate ORM指南以了解有关使用 JDBC 数据源的信息。

Get started with configuring `datasources` in Quarkus

对于熟悉基本知识的用户，本部分提供了快速设置数据源的概述和代码示例。

有关示例的高级配置，请参阅 References。

Zero-config setup in development mode

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

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

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

要使用此特性，请确保已安装与数据库类型相关的 Docker 或 Podman 容器运行时。某些数据库（如 H2）以内存模式运行，不需要容器运行时。

使用 `%prod.`为生产模式的实际连接详细信息加上前缀，以确保它们不会在 dev 模式下应用。有关详细信息，请参阅“配置参考”指南的 Profiles部分。

有关 Dev 服务的更多信息，请参阅 Dev Services overview。

有关更多详情和可选配置，请参阅 Dev Services for databases。

Configure a JDBC datasource

添加您选择的数据库的正确 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
Configure your JDBC datasource:[source, properties]

quarkus.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	仅当类路径中有多个数据库扩展时，才需要此配置值。

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

JDBC connection pool size adjustment

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

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

有关连接池大小调整属性的更多信息，请参阅 JDBC configuration reference 部分。

Configure a reactive datasource

添加您选择的数据库的正确反应性扩展。
- quarkus-reactive-db2-client
- quarkus-reactive-mssql-client
- quarkus-reactive-mysql-client
- quarkus-reactive-oracle-client
- quarkus-reactive-pg-client
Configure your reactive datasource:[source, properties]

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	仅当类路径中有多个反应性驱动程序扩展时，才需要此配置值。

Configure datasources

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

Configure a single datasource

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

使用以下配置属性定义数据源，其中 db-kind 定义要连接到的数据库平台，例如，h2：[source, properties]

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 驱动程序

您可以在 Quarkus 应用程序中使用 Using other databases 中描述的任何 JDBC 驱动程序（在 JVM 模式下）。不过，将您的应用程序编译为原生可执行文件时，使用非内置数据库类型不太可能起作用。对于本地可执行版本，建议使用可用的 JDBC Quarkus 扩展，或者为特定的驱动器贡献一个自定义扩展。

配置以下属性以定义凭据：[source, properties]

quarkus.datasource.username=<your username>
quarkus.datasource.password=<your password>

您还可以通过 using a credential provider 从 Vault 为数据源检索密码。

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

JDBC datasource

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

要使用 JDBC 数据源，首先添加必要的依赖关系：[style="loweralpha"]
1. 要与内置 JDBC 驱动程序配合使用，请从以下列表中选择并添加适合关系数据库驱动程序的 Quarkus 扩展：
  - Derby - quarkus-jdbc-derby
  - H2 - quarkus-jdbc-h2

H2 和 Derby 数据库可以配置为在“嵌入式模式”下运行；但是，Derby 扩展不支持将嵌入式数据库引擎编译成本地可执行文件。阅读 Testing with in-memory databases 以获取有关集成测试的建议。

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 和它的 documentation，可以在 Quarkiverse 中找到。例如，要添加 PostgreSQL 驱动程序依赖关系：

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

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

要与自定义 JDBC 驱动程序配合使用，请将 quarkus-agroal 依赖关系添加到您的项目以及关系数据库驱动程序的扩展：[source, bash]

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

要对其他数据库使用 JDBC 驱动程序，请 use a database with no built-in extension or with a different driver。

通过定义 JDBC URL 属性配置 JDBC 连接：[source, properties]

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

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

有关配置 JDBC 的更多信息，请参阅 JDBC URL format reference和 Quarkus extensions and database drivers reference。

Custom databases and drivers

如果你需要连接到一个数据库，但 Quarkus 没有提供带有 JDBC 驱动的扩展，你可以改为使用一个自定义驱动。例如，如果你在你的项目中使用了 OpenTracing JDBC 驱动。

如果没有扩展，该驱动在以 JVM 模式运行的任何 Quarkus 应用程序中都能正常工作。但是，当把你的应用程序编译成原生可执行文件时，该驱动很可能无法工作。如果你计划制作一个原生可执行文件，请使用现有的 JDBC Quarkus 扩展，或为你的驱动贡献一个。

OpenTracing 已弃用，取而代之的是 OpenTelemetry。有关跟踪信息，请查看下面的 Datasource tracing相关部分。

A custom driver definition example with the legacy OpenTracing driver:

quarkus.datasource.jdbc.driver=io.opentracing.contrib.jdbc.TracingDriver

An example for defining access to a database with no built-in support in JVM mode:

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 configuration reference部分。

Consuming the datasource

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

若要在代码中访问数据源，像获取任何其他 bean 一样获取它，如下所示：

@Inject
AgroalDataSource defaultDataSource;

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

Reactive datasource

Quarkus 提供了多个反应式客户端，可与反应式数据源一起使用。

向你的应用程序添加相应的扩展：
- 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`一致。
添加驱动程序后，配置连接 URL，并为连接池定义适当的大小。[source, properties]

quarkus.datasource.reactive.url=postgresql:///your_database
quarkus.datasource.reactive.max-size=20

Reactive connection pool size adjustment

为了在负载高峰期间保护你的数据库免于过载，请适当调整池大小，以限制数据库负载。适当的大小总取决于许多因素，例如并发应用程序用户数或工作负载的性质。

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

有关池大小调整属性的更多信息，请参阅 Reactive datasource configuration reference部分。

JDBC and reactive datasources simultaneously

当同时包含一个 JDBC 扩展（与 Agroal 一起）和一个处理给定数据库类型的反应式数据源扩展时，它们都将默认创建。

如果你想同时使用它们，请确保同时设置了 JDBC和 reactive配置，例如：

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

如果你不想创建 JDBC 数据源和反应式数据源，请使用以下配置。* 显式禁用 JDBC 数据源：

quarkus.datasource.jdbc=false

显式禁用反应式数据源：[source, properties]

quarkus.datasource.reactive=false

在大多数情况下，上述配置是可选的，因为既不会存在 JDBC 驱动程序，也不会存在反应式数据源扩展，两者不会共存。

Configure multiple datasources

Hibernate ORM 扩展支持通过配置属性定义 persistence units。对于每个持久性单元，请指向您选择的 datasource。

定义多个 datasource 的方式与定义单个 datasource 的方式类似，但有一个重要的区别 - 您必须为每个 datasource 指定一个名称 (配置属性)。

以下示例提供了三个不同的 datasource：

the default one
a datasource named users
a datasource named 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.[optional name.][datasource property]。

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

Named datasource injection

使用多个 datasource 时，每个 `DataSource`还带有 `io.quarkus.agroal.DataSource`限定符，其值是 datasource 的名称。

通过使用上一部分中提到的属性配置三个不同的 datasource，如下注入每个datasource：

@Inject
AgroalDataSource defaultDataSource;

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

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

Activate/deactivate datasources

如果在构建时配置了某个 datasource，则默认情况下它在运行时处于活动状态，即 Quarkus 会在应用程序启动时启动相应的 JDBC 连接池或反应式客户端。

要在运行时停用某个 datasource，请将 quarkus.datasource[.optional name].active`设置为 `false。然后 Quarkus 将不会在应用程序启动时启动相应的 JDBC 连接池或反应式客户端。在运行时使用相应 datasource 的任何尝试都将失败，并显示一条明确的错误消息。

这在您希望应用程序能够在运行时使用预先确定的 datasource 集中的一项 datasource 时尤为有用。

如果另一个 Quarkus 扩展依赖于一个不活动的数据源，那么该扩展可能会启动失败。在这种情况下，您还需要停用该其他扩展。例如，请参见 here for 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`at runtime将仅使 PostgreSQL 数据源可用，并在运行时设置 `quarkus.datasource."oracle".active=true`将仅使 Oracle 数据源可用。

Custom configuration profiles可以帮助简化这样的设置。通过将以下特定于配置文件的配置附加到上面的配置，您可以简单地通过 setting quarkus.profile： `quarkus.profile=prod,pg`或 `quarkus.profile=prod,oracle`选择一个持久性单元/datasource。

%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."

定义一个重定向到当前活动数据源的 CDI bean producer也很有用，如下所示：

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;
        }
    }
}

Use multiple datasources in a single transaction

默认情况下，数据源上的 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 数据源：

确保 JDBC 驱动程序支持 XA。所有 supported JDBC drivers do，但 other JDBC drivers可能不支持。
确保数据库服务器已配置为启用 XA。
通过将<<`quarkus.datasource[.optional name].jdbc.transactions`,quarkus-agroal_quarkus-datasource-jdbc-transactions>>设置为 xa，显式为每个相关数据源启用 XA 支持。

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

当前不支持反应性数据源上的 XA 事务。

如果事务涉及其他非数据源资源，请记住 *those*资源可能不支持 XA 事务或可能需要其他配置。

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

请注意，仍然可以通过 Last Resource Commit Optimization (LRCO)为所有数据源（并且只为一个数据源）启用 XA except one。
如果你不需要某个数据源的回滚来触发其他数据源的回滚，请考虑将代码拆分成多个事务。为此，请使用 QuarkusTransaction.requiringNew()/@Transactional(REQUIRES_NEW)（最好）或 UserTransaction（针对更复杂的使用案例）。

作为最后的手段，为了与 Quarkus 3.8 及更低版本兼容，你可以通过将 quarkus.transaction-manager.unsafe-multiple-last-resources`设置为 `allow`来允许跨多个非 XA 数据源进行不安全的交易处理。使用此属性设置为 `allow，事务回滚可能只适用于其中一些非 XA 数据源，其他非 XA 数据源可能已经提交其更改，进而使整个系统处于不一致的状态。或者，你可以允许相同的 unsafe 行为，但当利用此行为时发出警告：

将该属性设置为 `warn-each`将在 each 违规的事务中记录一条警告。
将该属性设置为 `warn-first`将在 first 违规的事务中记录一条警告。

我们不建议使用此配置属性，并且我们计划在未来将其删除，因此你应计划相应修复应用程序。如果你认为此功能的用例有效，并且应该保留此选项，请在 Quarkus tracker 中打开一个 issue 并说明原因。

Datasource integrations

Datasource health check

如果您使用 quarkus-smallrye-health扩展，则 `quarkus-agroal`和反应客户端扩展会自动添加一个就绪性检查以验证数据源。

当您访问应用程序的运行就绪状态端点时，/q/health/ready`默认显示有关数据源验证状态的信息。如果您有多个数据源，则会检查所有数据源，并且只要发生单个数据源验证失败，状态就会变为 `DOWN。

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

若要只从运行状况检查中排除某个特定数据源，请使用：

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

Datasource metrics

如果您使用的是 quarkus-micrometer或 quarkus-smallrye-metrics扩展，`quarkus-agroal`可以将一些与数据源相关指标添加到指标注册表。这可以通过将 `quarkus.datasource.metrics.enabled`属性设置为 `true`来激活。

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

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

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

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

Datasource tracing

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

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

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

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

Narayana transaction manager integration

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

您可以通过设置 `transactions`配置属性来覆盖此内容：

`quarkus.datasource.jdbc.transactions`用于默认未命名数据源
quarkus.datasource.<datasource-name>.jdbc.transactions for named datasource

有关更多信息，请参阅下面的 Configuration reference部分。

要通过使用 JDBC 在数据库中存储事务日志，请参阅 Using transactions in Quarkus指南的 Configuring transaction logs to be stored in a datasource部分。

Named datasources

使用开发人员服务时，总是会创建默认数据源，但要指定已命名数据源，您需要至少有一个构建时间属性，以便 Quarkus 可以检测如何创建数据源。

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

Testing with in-memory databases

一些数据库（例如 H2 和 Derby）通常在 embedded mode 中用作快速运行集成测试的工具。

建议的方法是使用你打算在生产中使用的真实数据库，尤其是在 Dev Services provide a zero-config database for testing 时，针对容器运行测试相对较快，并在实际环境中产生预期结果。不过，在需要运行简单集成测试时也可以使用受 JVM 支持的数据库。

Support and limitations

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

Derby 在原生模式下无法嵌入到应用程序中。但是，Quarkus Derby 扩展允许原生编译 Derby JDBC client，支持 remote 连接。
不建议在原生镜像中嵌入 H2。请考虑使用替代方式，例如改用与单独数据库的远程连接。

Run an integration test

添加对提供以下 Maven 坐标下附加工具的工件的依赖关系：
- io.quarkus:quarkus-test-h2 for H2
- io.quarkus:quarkus-test-derby for Derby这将允许你在应用程序编译成原生可执行文件时对其进行测试，而数据库将作为 JVM 进程运行。
对集成测试中的任何类添加以下特定注解，以在 JVM 或原生可执行文件中运行集成测试：
- @WithTestResource(H2DatabaseTestResource.class)
- `@WithTestResource(DerbyDatabaseTestResource.class)`这确保测试套件将管理的数据库作为测试执行所需的单独进程来启动和终止。
  .H2 example

package my.app.integrationtests.db;

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

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

配置与管理数据库的连接：[source, properties]

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

References

Common datasource configuration reference

Unresolved include directive in modules/ROOT/pages/datasource.adoc - include::../../../target/quarkus-generated-doc/config/quarkus-datasource.adoc[]

JDBC configuration reference

Unresolved include directive in modules/ROOT/pages/datasource.adoc - include::../../../target/quarkus-generated-doc/config/quarkus-agroal.adoc[]

JDBC URL reference

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

DB2

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

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

有关 URL 语法的更多信息和其他受支持的选项，请参阅 official documentation。

Derby

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

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

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

有关更多信息，请参阅 official documentation。

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 是一个可以以嵌入式或服务器模式运行的数据库。它可以使用文件存储或完全在内存中运行。列出的所有选项都可用。

有关详细信息，请参阅 official documentation。

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

有关详细信息，请参阅 official documentation。

Microsoft SQL server

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

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

Microsoft SQL Server JDBC 驱动程序的工作原理基本上与其他驱动程序相同。

有关详细信息，请参阅 official documentation。

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

有关详细信息，请参阅 official documentation。

MySQL limitations

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

缺少 JMX 支持是本机模式运行的自然后果，并且不太可能得到解决。
不支持与 OCI 集成。

Oracle

jdbc:oracle:driver_type:@database_specifier

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

有关详细信息，请参阅 official documentation。

PostgreSQL

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

Example: jdbc:postgresql://localhost/test

不同部分的默认值如下：

host: localhost
port: 5432
database: same name as the username

有关其他参数的详细信息，请参阅 official documentation。

Quarkus extensions and database drivers reference

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

使用其中一种内置 datasource 类型时，JDBC 和 Reactive 驱动程序会自动解析为与这些表的中的值匹配。

Table 1. Database platform kind to JDBC driver mapping
Database kind	Quarkus extension	Drivers
`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.MySQLDataSource`
`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`

Table 2. Database kind to Reactive driver mapping
Database kind	Quarkus extension	Driver
`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 datasource configuration reference

Unresolved include directive in modules/ROOT/pages/datasource.adoc - include::../../../target/quarkus-generated-doc/config/quarkus-reactive-datasource.adoc[]

Reactive DB2 configuration

Unresolved include directive in modules/ROOT/pages/datasource.adoc - include::../../../target/quarkus-generated-doc/config/quarkus-reactive-db2-client.adoc[]

Reactive MariaDB/MySQL specific configuration

Unresolved include directive in modules/ROOT/pages/datasource.adoc - include::../../../target/quarkus-generated-doc/config/quarkus-reactive-mysql-client.adoc[]

Reactive Microsoft SQL server-specific configuration

Unresolved include directive in modules/ROOT/pages/datasource.adoc - include::../../../target/quarkus-generated-doc/config/quarkus-reactive-mssql-client.adoc[]

Reactive Oracle-specific configuration

Unresolved include directive in modules/ROOT/pages/datasource.adoc - include::../../../target/quarkus-generated-doc/config/quarkus-reactive-oracle-client.adoc[]

Reactive PostgreSQL-specific configuration

Unresolved include directive in modules/ROOT/pages/datasource.adoc - include::../../../target/quarkus-generated-doc/config/quarkus-reactive-pg-client.adoc[]

Reactive datasource URL reference

DB2

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

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

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

host
port
user
password
database

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

Microsoft SQL server

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

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

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

host
port
user
password
database

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

MySQL / MariaDB

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

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

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

host
port
user
password
schema
socket
useAffectedRows

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

Oracle

EZConnect format

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

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

TNS alias format

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

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

PostgreSQL

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

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

目前，客户端支持：

Following parameter keys:
- host
- port
- user
- password
- dbname
- sslmode
Additional properties, such as:
- application_name
- fallback_application_name
- search_path
- options

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

Configure data sources in Quarkus

Get started with configuring datasources in Quarkus

Zero-config setup in development mode

Configure a JDBC datasource

JDBC connection pool size adjustment

Configure a reactive datasource

Configure datasources

Configure a single datasource

JDBC datasource

Custom databases and drivers

Consuming the datasource

Reactive datasource

Reactive connection pool size adjustment

JDBC and reactive datasources simultaneously

Configure multiple datasources

Named datasource injection

Activate/deactivate datasources

Use multiple datasources in a single transaction

Datasource integrations

Datasource health check

Datasource metrics

Datasource tracing

Narayana transaction manager integration

Named datasources

Testing with in-memory databases

Support and limitations

Run an integration test

References

Common datasource configuration reference

JDBC configuration reference

JDBC URL reference

DB2

Derby

H2

MariaDB

Microsoft SQL server

MySQL

MySQL limitations

Oracle

PostgreSQL

Quarkus extensions and database drivers reference

Reactive datasource configuration reference

Reactive DB2 configuration

Reactive MariaDB/MySQL specific configuration

Reactive Microsoft SQL server-specific configuration

Reactive Oracle-specific configuration

Reactive PostgreSQL-specific configuration

Reactive datasource URL reference

DB2

Microsoft SQL server

MySQL / MariaDB

Oracle

EZConnect format

TNS alias format

PostgreSQL

Get started with configuring `datasources` in Quarkus