Apply suggestions from code review

Co-authored-by: Michelle Purcell <[email protected]>

Erin fixes1

Signed-off-by: Michal Maléř <[email protected]>

Erin fixes2

Signed-off-by: Michal Maléř <[email protected]>

Fixes

Signed-off-by: Michal Maléř <[email protected]>

docs/src/main/asciidoc/datasource.adoc

@@ -4,60 +4,55 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 [id="datasources"]
-= Get started with configuring datasources in Quarkus
+= Configure datasources in Quarkus
 include::_attributes.adoc[]
 :categories: data,getting-started
+:summary: Use a unified configuration model to define datasources for Java Database Connectivity (JDBC) and Reactive drivers.
 
-Learn how to easily configure a Java Database Connectivity (JDBC) and Reactive datasource, their combination, or several datasources if required.
-
-Many Java applications require connections to a relational database.
-The usual way to establish database connections is to combine a data source and a database driver.
-
-Quarkus supports JDBC and reactive drivers and allows for unified and flexible configurations.
-
-Quarkus supports lightweight link:https://agroal.github.io/[Agroal] datasource and connection pooling implementation for JDBC, as well as link:https://vertx.io/[Vert.x] reactive drivers for reactive approaches.
-This provides high performance, scalability, and features integration with the other components in Quarkus,
-such as security, health checks, and metrics.
+////
+Note for contributors and writers:
+In text, use `data source` in code, `datasource` or `DataSource` is more common.
+See, https://docs.oracle.com/javase/tutorial/jdbc/basics/connecting.html
+////
 
-For more details about consuming and using a reactive datasource,
-refer to the xref:reactive-sql-clients.adoc[Reactive SQL clients] guide.
+Applications use datasources to access relational databases.
+Quarkus provides a unified configuration model to define datasources for Java Database Connectivity (JDBC) and Reactive database drivers.
 
-Datasource guide then explains the following:
+Quarkus uses link:https://agroal.github.io/[Agroal] and link:https://vertx.io/[Vert.x] to provide high-performance, scaleable data source connection pooling for JDBC and reactive drivers.
+The `jdbc-*` and `reactive-*` extensions provide build time optimizations and integrate configured data sources with Quarkus features like security, health checks, and metrics.
 
-* Configuring a datasource or multiple datasources
-* Obtaining a reference to those datasources in the code
-* Enabling metrics and health checks for datasources
+For more details about consuming and using a reactive datasource, see the Quarkus xref:reactive-sql-clients.adoc[Reactive SQL clients] guide.
 
 ////
 Future references to all other parts of this doc.
 ////
 
-
 == Get started with configuring `datasources` in Quarkus
 
 To start configuring datasources quickly, this section serves as a quick introduction to datasources and provides you with code references you can test and use if you are already familiar with the basics.
 
-For the advanced configuration with examples, see xref:datasource-reference[Datasource references].
+For more advanced configuration with examples, see xref:datasource-reference[Datasource references].
 
 [[dev-services]]
 === Zero-config setup in development mode
 
 When testing or running in development mode, Quarkus can provide you with a zero-config database, a feature referred to as _Dev Services_.
 
-Depending on your database type, a Docker or Podman container runtime need to be installed to use this feature.
-Some databases, such as H2, run in-memory and do not require a container runtime.
+Depending on your database type, a Docker or Podman container runtime needs to be installed to use this feature.
+Some databases, for example H2, run in memory and do not require a container runtime.
 
 To start using Dev Services, include the relevant extension for the type of database you want, such as `jdbc-postgresql`, `reactive-pg-client`, or both.
 
-In this scenario, configuring a database URL and setting up username and password is not needed.
+In this scenario, configuring a database URL and setting up a username and password is not needed.
 If you provide the user credentials, Quarkus will configure the underlying database to use them.
 This is useful when you want to connect to the underlying database externally using your tooling.
 
-Quarkus provides the database instance and the necessary connection between the database and application. You can start coding without worrying about config.
+Quarkus provides the database instance and the necessary connection between the database and the application. 
+You can start coding without worrying about configuration.
 
 For more details and optional configurations, see xref:databases-dev-services.adoc[Databases Dev Services].
 
-=== JDBC datasource
+=== Configure a JDBC datasource
 
 . Add the `agroal` extension plus one of `jdbc-db2`, `jdbc-derby`, `jdbc-h2`, `jdbc-mariadb`, `jdbc-mssql`, `jdbc-mysql`, `jdbc-oracle` or `jdbc-postgresql`.
 
@@ -76,7 +71,7 @@ quarkus.datasource.jdbc.max-size=16
 If only one viable extension is available, Quarkus assumes this is the correct one.
 If a driver has been added to the test scope, Quarkus automatically includes the driver in testing.
 
-=== Reactive datasource
+=== Configure a reactive datasource
 
 . Add the correct reactive extension for the database of your choice.
 
@@ -109,20 +104,19 @@ For simplicity, we will reference a single datasource as the default (unnamed) d
 A datasource can be either a JDBC datasource, reactive, or both.
 This depends on the configuration and the selection of project extensions.
 
-. Define a datasource with the following configuration property:
+. Define a datasource with the following configuration property, where `db-kind` defines which database platform to connect to, for example, `h2` or `postgresql`:
 +
 [source, properties]
 ----
 quarkus.datasource.db-kind=h2
 ----
 +
-NOTE: This step is required only if your application depends on more than one database driver.
-If the application operates with a single driver, this driver is detected automatically.
+Quarkus deduces the JDBC driver class it needs to use from the specified value of the `db-kind` database platform attribute.
 +
-The database kind defines to which type of database you will connect.
-In particular, Quarkus deduces the JDBC driver class it needs to use from the database kind.
+NOTE: This step is required only if your application depends on multiple database drivers.
+If the application operates with a single driver, this driver is detected automatically.
 +
-Quarkus currently includes these built-in database kinds:
+Quarkus currently includes the following built-in database kinds:
 +
 * DB2: `db2`
 * Derby: `derby`
@@ -161,7 +155,7 @@ It is possible to use JDBC and a reactive driver simultaneously.
 
 JDBC is the most common database connection pattern, typically needed when used in combination with non-reactive Hibernate ORM.
 
-. Add the `quarkus-agroal` dependency to your project using the following Maven command:
+. Add the `quarkus-agroal` dependency to your project:
 +
 [source,bash]
 ----
@@ -182,7 +176,7 @@ Therefore, the Agroal extension dependency does not have to be added explicitly
 +
 [NOTE]
 ====
-The H2 and Derby databases can be configured to run in "embedded mode"; however, the Derby extension does not support compiling the embedded database engine into native executables.
+H2 and Derby databases can be configured to run in "embedded mode"; however, the Derby extension does not support compiling the embedded database engine into native executables.
 
 Read <<in-memory-databases,Testing with in-memory databases>> for suggestions regarding integration testing.
 ====
@@ -193,9 +187,10 @@ Read <<in-memory-databases,Testing with in-memory databases>> for suggestions re
 * Oracle - `jdbc-oracle`
 * PostgreSQL - `jdbc-postgresql`
 * Other JDBC extensions, such as link:https://github.com/quarkiverse/quarkus-jdbc-sqlite[SQLite] and its link:https://quarkiverse.github.io/quarkiverse-docs/quarkus-jdbc-sqlite/dev/index.html[documentation], can be found in the https://github.com/quarkiverse[Quarkiverse].
+
 To use a JDBC driver for another database, <<other-databases,use a database with no built-in extension or with a different driver>>.
 
-. Add the extension to your application using the `add-extension` command.
+. Add the extension to your application by using the `add-extension` command.
 +
 For example, to add the PostgreSQL driver dependency, run the following command:
 +
@@ -218,17 +213,13 @@ All the configuration properties specific to JDBC have the `jdbc` prefix.
 For reactive datasources, the prefix is `reactive`.
 ====
 
-.References
-
-* <<jdbc-url,JDBC URL format reference>>
-* <<extensions-and-database-drivers-reference,Quarkus extensions and database drivers reference>>
-
+For more information about configuring JDBC, see <<jdbc-url,JDBC URL format reference>> and <<extensions-and-database-drivers-reference,Quarkus extensions and database drivers reference>>.
 
 
 [[other-databases]]
-===== Use a database with no built-in extension or with a different driver
+===== Custom databases and drivers
 
-You can use a specific driver if you need to (for instance, for using the OpenTracing driver) or if you want to use a database for which Quarkus does not have a built-in JDBC driver extension.
+If you need to connect to a database for which Quarkus does not provide an extension with the JDBC driver, you can use a custom driver instead. For example, if you are using the OpenTracing JDBC driver in your project.
 
 Without an extension, the driver will work correctly in any Quarkus app running in JVM mode.
 However, the driver is unlikely to work when compiling your application to a native executable.
@@ -323,7 +314,7 @@ Creating multiple reactive datasources is not currently possible.
 
 [NOTE]
 ====
-The Hibernate ORM extension supports defining xref:hibernate-orm.adoc#multiple-persistence-units[persistence units] using configuration properties.
+The Hibernate ORM extension supports defining xref:hibernate-orm.adoc#multiple-persistence-units[persistence units] by using configuration properties.
 For each persistence unit, point to the datasource of your choice.
 ====
 
@@ -365,7 +356,7 @@ Generally, this is the `db-kind` property, but you can also specify Dev Services
 
 When using multiple datasources, each `DataSource` also has the `io.quarkus.agroal.DataSource` qualifier with the name of the datasource as the value.
 
-. Using the above-mentoned properties to configure three different datasources, inject each one as follows:
+. By using the above-mentioned properties to configure three different datasources, inject each one as follows:
 +
 [source,java,indent=0]
 ----
@@ -445,8 +436,11 @@ Embedded databases (H2 and Derby) work in JVM mode.
 For native mode, the following limitations apply:
 
 * Derby cannot be embedded into the application in native mode, and only remote connection is supported.
-* H2 can be embedded into the application in native mode, but this is considered experimental.
-We recommend carefully considering alternatives (remote connection to a separate database, etc.) before embedding H2 within your native image.
+[IMPORTANT]
+====
+Embedding H2 within your native image is not recommended. 
+Consider using an alternative approach, for example, using a remote connection to a separate database instead.
+====
 
 ==== Run an integration test
 
@@ -463,7 +457,7 @@ This will allow you to test your application even when it is compiled into a nat
 * `@QuarkusTestResource(H2DatabaseTestResource.class)`
 * `@QuarkusTestResource(DerbyDatabaseTestResource.class)`
 +
-This will make sure the test suite starts and stops the embedded database into a separate process as necessary to run your tests.
+This ensures that the test suite starts and terminates the managed database in a separate process as required for test execution.
 +
 .H2 example
 [source,java]
@@ -478,7 +472,7 @@ public class TestResources {
 }
 ----
 
-. Connect to it using:
+. Connect to the managed database:
 +
 [source,properties]
 ----
@@ -519,8 +513,7 @@ For more information on URL syntax and additional supported options, see the lin
 
 Example:: `jdbc:derby://localhost:1527/myDB`, `jdbc:derby:memory:myDB;create=true`
 
-Derby is an embedded database.
-It can run as a server, based on a file, or run completely in memory.
+Derby is an embedded database that can run as a server, based on a file, or can run completely in memory.
 All of these options are available as listed above.
 
 For more information, see the link:https://db.apache.org/derby/docs/10.8/devguide/cdevdvlp17453.html#cdevdvlp17453[official documentation].
@@ -531,8 +524,7 @@ For more information, see the link:https://db.apache.org/derby/docs/10.8/devguid
 
 Example:: `jdbc:h2:tcp://localhost/~/test`, `jdbc:h2:mem:myDB`
 
-H2 is an embedded database.
-It can run as a server, based on a file, or run completely in memory.
+H2 is an embedded database that can run as a server, based on a file, or run completely in memory.
 All of these options are available as listed above.
 
 For more information, see the link:https://h2database.com/html/features.html?highlight=url&search=url#database_url[official documentation].
@@ -598,7 +590,7 @@ For more information about additional parameters, see the link:https://jdbc.post
 [[extensions-and-database-drivers-reference]]
 === Quarkus extensions and database drivers reference
 
-The below tables list the built-in db-kind values, the corresponding Quarkus extensions, and the JDBC drivers used by those extensions.
+The following tables list the built-in `db-kind` values, the corresponding Quarkus extensions, and the JDBC drivers used by those extensions.
 
 When using one of the built-in datasource kinds, the JDBC and Reactive drivers are resolved automatically to match the values from these tables.