[#577] Guide: Integrating with a PostgreSQL database #625

yersan · 2024-06-19T15:49:51Z

Fixes #577

bstansberry

The basic structure of this looks good; my comments are all just copy editing.

If we do a MariaDB or other DB variant of this we'd likely refactor much of this out into separate files for inclusion.

bstansberry · 2024-08-22T18:40:32Z

_data/guides.yaml

+    guides:
+      - title: Integrating with a PostgreSQL database
+        url: /guides/database-integrating-with-postgresql
+        description: Learn how to configure a datasource to connect a PostgreSQL database.


s/connect a/connect to a/g

bstansberry · 2024-08-22T18:42:16Z

guides/database-integrating-with-postgresql.adoc

+:postgre-docker-image: docker.io/library/postgres
+:postgre-sql-kubernetes-service-name: postgres-service
+
+In this guide, you will learn how to configure WildFly to connect to a PostgreSQL database. You will create a simple Book Store API application to manage books stored in the database using a https://jakarta.ee/specifications/restful-ws/[Jakarta RESTful Web Services (JAX-RS), window=_blank].


I think there's a missing word after "(JAX-RS)", or you can change "using a" to just "using".

Done. Replaced with "using"

bstansberry · 2024-08-22T18:42:54Z

guides/database-integrating-with-postgresql.adoc

+
+=== PostgreSQL
+
+We will use PostgreSQL as database server in its containerized version: see https://hub.docker.com/_/postgres[PostgreSQL Official Image, window=_blank].


s/as database/as the database/g

bstansberry · 2024-08-22T18:43:37Z

guides/database-integrating-with-postgresql.adoc

+  {postgre-docker-image}
+----
+
+NOTE: we started the container with the `--rm` so it can be disposed automatically when we stop it.


s/disposed/disposed of/g

s/the --rm/the --rm flag/g

bstansberry · 2024-08-22T18:44:39Z

guides/database-integrating-with-postgresql.adoc

+
+=== Create a new Maven project
+
+We are going to use the *WildFly Getting Started Archetype* to create the base structure of our Book Store API.


s/API/API application/g

bstansberry · 2024-08-22T18:53:23Z

guides/database-integrating-with-postgresql.adoc

+----
+NOTE: We don't need to specify the name of the Datasource by using `<jta-data-source>`. In absence of this property, JPA will use the default datasource configured in the server.
+
+=== Configure RESTful Web Services (JAX-RS) application


s/Configure/Configure the Jakarta/g

I think you should drop the "(JAX-RS)". Mentioning it once is enough.

Added Jakarta

bstansberry · 2024-08-22T18:57:52Z

guides/database-integrating-with-postgresql.adoc

+
+=== Configure RESTful Web Services (JAX-RS) application
+
+The `BookStoreApplication` class acts as a configuration class for the JAX-RS application. It essentially tells the JAX-RS runtime that this is a JAX-RS application and provides the base path for the application's RESTful web services.


Jakarta REST.

We should not use the term JAX-RS beyond the very first "Jakarta RESTful Web Services (JAX-RS)" above.

s/tells the JAX-RS runtime/tells the WildFly runtime/g

The fact that it's the jax-rs subsystem that detects this is an internal detail of the WildFly runtime.

Jakarta REST.
We should not use the term JAX-RS beyond the very first "Jakarta RESTful Web Services (JAX-RS)" above.

Not sure if I am following you here. Should not we use JAX-RS to avoid writing the full name? I understand that in the title of a section makes more sense to use the full name "Jakarta RESTful Web Services" (with or without the JAX-RS since it has been already mentioned before), and then in the paragraph use JAX-RS to avoid using the full name.

@yersan JAX-RS is a Java EE trademark that was not transferred by Oracle to the Eclipse foundation when Jakarta was created. We should avoid using it as a shorthand -- use Jakarta REST. Similar things apply to all the old Java EE shorthands, JAX-WS etc. We are not required or willing to break our software to deal with this change (e.g. renaming subsystems) but for purely documentation things like this we should avoid the old shorthands.

TBH, we shouldn't use JAX-RS even once. This shift from Java EE to Jakarta EE is many years old now; we don't need to remind people who are actually using these technologies.

I thought that you were trying to remind people of the old term by using it, but I think now you were more just trying to use a short form. Don't use JAX-RS as a short form.

@bstansberry ok, I've have updated it accordingly, take another look when you have a chance, thanks!

bstansberry · 2024-08-22T19:13:29Z

guides/database-integrating-with-postgresql.adoc

+----
+
+=== BookResource
+The `BookResource` is the web service that exposes the book records as JSon objects.


s/JSon/JSON

bstansberry · 2024-08-22T19:14:12Z

guides/database-integrating-with-postgresql.adoc

+mvn clean package
+----
+
+Notice how WildFly Glow gives us information about the Feature packs and Galleon layers discovered. It also provides some hints about required environment variables:


s/Feature packs/feature packs/g

bstansberry · 2024-08-22T19:17:28Z

guides/database-integrating-with-postgresql.adoc

+// Always keep a what's next? section to let the user know what could be achieved next
+== What's next?
+
+In this guide we have learnt how to configure a WildFly server to access to a PostgreSQL database and how to easily trim the server capabilities using WildFly Glow. Seamlessly, you can adapt the same application to use other databases by changing the Galleon Layers used by the WildFly server.


s/learnt/learned

yersan

Thanks for reviewing this @bstansberry , all fixed but added a small note about JAX-RS usage

yersan · 2024-08-26T10:33:53Z

_data/guides.yaml

+    guides:
+      - title: Integrating with a PostgreSQL database
+        url: /guides/database-integrating-with-postgresql
+        description: Learn how to configure a datasource to connect a PostgreSQL database.


yersan · 2024-08-26T10:35:36Z

guides/database-integrating-with-postgresql.adoc

+:postgre-docker-image: docker.io/library/postgres
+:postgre-sql-kubernetes-service-name: postgres-service
+
+In this guide, you will learn how to configure WildFly to connect to a PostgreSQL database. You will create a simple Book Store API application to manage books stored in the database using a https://jakarta.ee/specifications/restful-ws/[Jakarta RESTful Web Services (JAX-RS), window=_blank].


Done. Replaced with "using"

yersan · 2024-08-26T10:36:09Z

guides/database-integrating-with-postgresql.adoc

+
+=== PostgreSQL
+
+We will use PostgreSQL as database server in its containerized version: see https://hub.docker.com/_/postgres[PostgreSQL Official Image, window=_blank].


yersan · 2024-08-26T10:38:58Z

guides/database-integrating-with-postgresql.adoc

+  {postgre-docker-image}
+----
+
+NOTE: we started the container with the `--rm` so it can be disposed automatically when we stop it.


yersan · 2024-08-26T10:39:41Z

guides/database-integrating-with-postgresql.adoc

+
+=== Create a new Maven project
+
+We are going to use the *WildFly Getting Started Archetype* to create the base structure of our Book Store API.


yersan · 2024-08-26T11:12:50Z

guides/database-integrating-with-postgresql.adoc

+
+=== Configure RESTful Web Services (JAX-RS) application
+
+The `BookStoreApplication` class acts as a configuration class for the JAX-RS application. It essentially tells the JAX-RS runtime that this is a JAX-RS application and provides the base path for the application's RESTful web services.


Jakarta REST.
We should not use the term JAX-RS beyond the very first "Jakarta RESTful Web Services (JAX-RS)" above.

Not sure if I am following you here. Should not we use JAX-RS to avoid writing the full name? I understand that in the title of a section makes more sense to use the full name "Jakarta RESTful Web Services" (with or without the JAX-RS since it has been already mentioned before), and then in the paragraph use JAX-RS to avoid using the full name.

yersan · 2024-08-26T11:13:55Z

guides/database-integrating-with-postgresql.adoc

+----
+NOTE: We don't need to specify the name of the Datasource by using `<jta-data-source>`. In absence of this property, JPA will use the default datasource configured in the server.
+
+=== Configure RESTful Web Services (JAX-RS) application


Added Jakarta

yersan · 2024-08-26T11:15:16Z

guides/database-integrating-with-postgresql.adoc

+----
+
+=== BookResource
+The `BookResource` is the web service that exposes the book records as JSon objects.


yersan · 2024-08-26T11:15:41Z

guides/database-integrating-with-postgresql.adoc

+mvn clean package
+----
+
+Notice how WildFly Glow gives us information about the Feature packs and Galleon layers discovered. It also provides some hints about required environment variables:


yersan · 2024-08-26T11:16:05Z

guides/database-integrating-with-postgresql.adoc

+// Always keep a what's next? section to let the user know what could be achieved next
+== What's next?
+
+In this guide we have learnt how to configure a WildFly server to access to a PostgreSQL database and how to easily trim the server capabilities using WildFly Glow. Seamlessly, you can adapt the same application to use other databases by changing the Galleon Layers used by the WildFly server.


yersan

Took another round, I'll squash all the commits when we are done

yersan · 2024-08-26T15:47:15Z

guides/database-integrating-with-postgresql.adoc

+
+=== Configure RESTful Web Services (JAX-RS) application
+
+The `BookStoreApplication` class acts as a configuration class for the JAX-RS application. It essentially tells the JAX-RS runtime that this is a JAX-RS application and provides the base path for the application's RESTful web services.


@bstansberry ok, I've have updated it accordingly, take another look when you have a chance, thanks!

bstansberry

@yersan Just a few more things.

bstansberry · 2024-08-26T18:44:25Z

guides/database-integrating-with-postgresql.adoc

+
+=== Create a new Maven project
+
+We are going to use the *WildFly Getting Started Archetype* to create the base structure of our Book Store API application.


Perhaps make this a link?

Done.

Added https://github.com/wildfly/wildfly-archetypes/tree/main/wildfly-getting-started-archetype link

bstansberry · 2024-08-26T18:46:55Z

guides/database-integrating-with-postgresql.adoc

+----
+
+==== Configure WildFly Datasource and trimming server capabilities:
+To connect to the database we need to configure the https://docs.wildfly.org/32/Admin_Guide.html#DataSource[WildFly Datasource Subsystem,window=_blank] and install the PostgreSQL driver into the WildFly server. The https://github.com/wildfly-extras/wildfly-datasources-galleon-pack[WildFly Datasource Galleon Pack, window=_blank] contains a set of https://github.com/wildfly-extras/wildfly-datasources-galleon-pack/blob/main/doc/postgresql/README.md[Galleon Layers, window=_blank] that provide *JDBC drivers* and *WildFly Datasource Subsystem* configurations for various databases. For this guide, we will use the `postgresql-default-datasource` Galleon layer that will configure a PostgreSQL datasource as the default datasource for the server.


s/WildFly Datasource Galleon Pack/WildFly Datasources Galleon Pack/g

Done.

Replaced all the occurrences.

bstansberry · 2024-08-26T18:50:05Z

guides/database-integrating-with-postgresql.adoc

+In the above configuration, behind the scenes the `wildfly-maven-plugin` is using https://docs.wildfly.org/wildfly-glow/[WildFly Glow, window=_blank] to discover automatically the required Galleon Layers for our application. The `discover-provisioning-info` configuration tells the plugin to discover the required layers by inspecting our application code. By using the `postgresql:default` addon, we are specifying we want to use a PostgreSQL database, and we want to configure it as the default datasource for the server.
+
+=== persistence.xml
+This file is used to configure the Jakarta Persistence API (JPA) persistence unit and its database schema generation strategy. In this guide, we are using the `drop-and-create` strategy to drop the existing schema and create a new one every time the application starts. For a production environment, you should use a more appropriate strategy to avoid data loss.


Since we're dealing with the abbreviations, 'JPA' is another one we should drop.

Also, no "API".

It's just Jakarta Persistence. https://jakarta.ee/specifications/persistence/

Done. It leads to "This file is used to configure the Jakarta Persistence persistence unit", which indeed seems to be correct.

bstansberry · 2024-08-26T18:51:39Z

guides/database-integrating-with-postgresql.adoc

+    </persistence-unit>
+</persistence>
+----
+NOTE: We don't need to specify the name of the Datasource by using `<jta-data-source>`. In absence of this property, JPA will use the default datasource configured in the server.


s/JPA/Jakarta Persistence/g

…hub project

yersan

@bstansberry , I've applied all the suggestions, take another look. Thanks for the review!

yersan · 2024-08-27T11:08:40Z

guides/database-integrating-with-postgresql.adoc

+
+=== Create a new Maven project
+
+We are going to use the *WildFly Getting Started Archetype* to create the base structure of our Book Store API application.


Done.

Added https://github.com/wildfly/wildfly-archetypes/tree/main/wildfly-getting-started-archetype link

yersan · 2024-08-27T11:11:11Z

guides/database-integrating-with-postgresql.adoc

+----
+
+==== Configure WildFly Datasource and trimming server capabilities:
+To connect to the database we need to configure the https://docs.wildfly.org/32/Admin_Guide.html#DataSource[WildFly Datasource Subsystem,window=_blank] and install the PostgreSQL driver into the WildFly server. The https://github.com/wildfly-extras/wildfly-datasources-galleon-pack[WildFly Datasource Galleon Pack, window=_blank] contains a set of https://github.com/wildfly-extras/wildfly-datasources-galleon-pack/blob/main/doc/postgresql/README.md[Galleon Layers, window=_blank] that provide *JDBC drivers* and *WildFly Datasource Subsystem* configurations for various databases. For this guide, we will use the `postgresql-default-datasource` Galleon layer that will configure a PostgreSQL datasource as the default datasource for the server.


Done.

Replaced all the occurrences.

yersan · 2024-08-27T11:13:51Z

guides/database-integrating-with-postgresql.adoc

+In the above configuration, behind the scenes the `wildfly-maven-plugin` is using https://docs.wildfly.org/wildfly-glow/[WildFly Glow, window=_blank] to discover automatically the required Galleon Layers for our application. The `discover-provisioning-info` configuration tells the plugin to discover the required layers by inspecting our application code. By using the `postgresql:default` addon, we are specifying we want to use a PostgreSQL database, and we want to configure it as the default datasource for the server.
+
+=== persistence.xml
+This file is used to configure the Jakarta Persistence API (JPA) persistence unit and its database schema generation strategy. In this guide, we are using the `drop-and-create` strategy to drop the existing schema and create a new one every time the application starts. For a production environment, you should use a more appropriate strategy to avoid data loss.


Done. It leads to "This file is used to configure the Jakarta Persistence persistence unit", which indeed seems to be correct.

yersan · 2024-08-27T11:15:53Z

guides/database-integrating-with-postgresql.adoc

+    </persistence-unit>
+</persistence>
+----
+NOTE: We don't need to specify the name of the Datasource by using `<jta-data-source>`. In absence of this property, JPA will use the default datasource configured in the server.


bstansberry · 2024-08-27T21:30:14Z

Thanks @yersan

yersan marked this pull request as draft June 19, 2024 16:50

yersan force-pushed the issue-577 branch from a65ee8d to b3bdd4e Compare June 19, 2024 17:21

yersan marked this pull request as ready for review June 19, 2024 17:21

yersan requested a review from bstansberry June 19, 2024 17:21

[wildfly#577] Guide: Integrating with a PostgreSQL database

d0d501b

yersan force-pushed the issue-577 branch from b3bdd4e to d0d501b Compare June 19, 2024 17:24

bstansberry requested changes Aug 22, 2024

View reviewed changes

[wildfly#577] Guide: Integrating with a PostgreSQL database

8993f98

yersan commented Aug 26, 2024

View reviewed changes

[wildfly#577] Review Jakarta REST / JAX-RS usage

1998b55

yersan commented Aug 26, 2024

View reviewed changes

yersan mentioned this pull request Aug 26, 2024

Wildfly mini serie #595

Merged

bstansberry requested changes Aug 26, 2024

View reviewed changes

[wildfly#577] Review JPA usages, added link for wildfly archetype git…

f09e2f1

…hub project

yersan commented Aug 27, 2024

View reviewed changes

bstansberry merged commit 83ee4b1 into wildfly:main Aug 27, 2024

yersan deleted the issue-577 branch August 27, 2024 22:00


		=== PostgreSQL

		We will use PostgreSQL as database server in its containerized version: see https://hub.docker.com/_/postgres[PostgreSQL Official Image, window=_blank].


		=== Create a new Maven project

		We are going to use the WildFly Getting Started Archetype to create the base structure of our Book Store API.


		=== Configure RESTful Web Services (JAX-RS) application

		The `BookStoreApplication` class acts as a configuration class for the JAX-RS application. It essentially tells the JAX-RS runtime that this is a JAX-RS application and provides the base path for the application's RESTful web services.

[#577] Guide: Integrating with a PostgreSQL database #625

[#577] Guide: Integrating with a PostgreSQL database #625

Conversation

yersan commented Jun 19, 2024

bstansberry left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yersan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yersan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bstansberry left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yersan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bstansberry commented Aug 27, 2024