Merge pull request #1520 from lucamolteni/45715-development

Hibernate ORM guide examples / quickstart are more complex than they should

Author: gsmet

README.md

@@ -50,13 +50,15 @@ See [CONTRIBUTING](CONTRIBUTING.md) for how to build these examples.
 * [Hibernate Reactive Panache and RESTEasy Reactive](./hibernate-reactive-quickstart): Exposing a CRUD service over REST using Hibernate Reactive and Panache to connect to a PostgreSQL database
 * [Hibernate Reactive and RESTEasy](./hibernate-reactive-quickstart): Exposing a CRUD service over REST using Hibernate Reactive to connect to a PostgreSQL database
 * [Hibernate Reactive and Vert.x Web](./hibernate-reactive-routes-quickstart): Exposing a CRUD service with Reactive Routes using Hibernate Reactive to connect to a PostgreSQL database
+* [Hibernate Reactive with StatelessSession](./hibernate-reactive-stateless-quickstart): Exposing a CRUD service with Reactive Routes using Hibernate Reactive  using `StatelessSession` to connect to a PostgreSQL database
 * [Hibernate ORM and RESTEasy](./hibernate-orm-quickstart): Exposing a CRUD service over REST using Hibernate ORM to connect to a PostgreSQL database
 * [Hibernate ORM with Panache and RESTEasy](./hibernate-orm-panache-quickstart): Exposing a CRUD service over REST using Panache to connect to a PostgreSQL database
 * [Hibernate ORM with Panache and RESTEasy in Kotlin](./hibernate-orm-panache-kotlin-quickstart): Exposing a CRUD service over REST using Panache and kotlin to connect to a PostgreSQL database
 * [Hibernate ORM REST Data with Panache](./hibernate-orm-rest-data-panache-quickstart): Automatically generate the CRUD endpoints for your entities and repositories using Hibernate ORM with Panache.
 * [Hibernate ORM Multitenancy Database](./hibernate-orm-multi-tenancy-database-quickstart): Multitenant CRUD service over REST using Hibernate ORM to connect to multiple PostgreSQL databases (database approach)
 * [Hibernate ORM Multitenancy Schema](./hibernate-orm-multi-tenancy-schema-quickstart): Multitenant CRUD service over REST using Hibernate ORM to connect to a PostgreSQL database (schema approach)
 * [Hibernate Search + Elasticsearch](./hibernate-search-orm-elasticsearch-quickstart): Index your Hibernate entities in Elasticsearch to get full text search
+* [Hibernate Search Standalone + Elasticsearch](./hibernate-search-orm-elasticsearch-quickstart): Index your Hibernate entities in Elasticsearch without Hibernate ORM to get full text search
 * [Infinispan Client](./infinispan-client-quickstart): How to use Infinispan Client. Covers creating caches and simple get/put
 * [Artemis JMS](./jms-quickstart): How to use the Artemis JMS extension
 * [Kafka](./kafka-quickstart): Use MicroProfile Reactive Messaging to interact with Apache Kafka

hibernate-orm-multi-tenancy-database-quickstart/README.md

@@ -31,27 +31,98 @@ Launch the Maven build on the checked out sources of this demo:
 
 ## Running the demo
 
-### Start Quarkus in development mode
+### Live coding with Quarkus
 
-The Maven Quarkus plugin provides a development mode that supports live coding. To try this out:
+The Maven Quarkus plugin provides a development mode that supports
+live coding. To try this out:
 
 > ./mvnw quarkus:dev
 
 In this mode you can make changes to the code and have the changes immediately applied, by just refreshing your browser.
 
-### Run Quarkus as native executable
+Dev Mode automatically starts two Docker containers running Postgres databases. This feature is called ["Dev Services."](https://quarkus.io/guides/dev-services)
 
-You can also create a native executable from this application without making any source code changes. A native executable removes the dependency on the JVM:
-everything needed to run the application on the target platform is included in the executable, allowing the application to run with minimal resource overhead.
+To access the database from the terminal, run:
 
-Compiling a native executable takes a bit longer, as GraalVM performs additional steps to remove unnecessary codepaths. Use the  `native` profile to compile  a native executable:
+```sh
+docker container list
+```
 
-> ./mvnw package -Pnative
+To get the id or the name of the created containers and then to access the database machine use 
 
-After getting a cup of coffee, you'll be able to run this executable directly:
+```sh
+docker exec -it <container-name> psql -U quarkus -d base
+docker exec -it <container-name> psql -U quarkus -d mycompany
+```
+
+As the ids and names are auto generated, you should try the command with both ids or names to see what works.
+If the wrong one is provided, you'll get a `FATAL:  role "base" does not exist`. Try the other container instance instead.
+
+    Hot reload works even when modifying your JPA entities.
+    Try it! Even the database schema will be updated on the fly.
+
+### Run Quarkus in JVM mode
+
+When you're done iterating in developer mode, you can run the application as a
+conventional jar file.
+
+First compile it:
+
+> ./mvnw package
+
+Next, make sure you have the two PostgreSQL databases running. In production, Quarkus does not start any container for you like it does in Dev Mode.
+To set up two PostgreSQL databases with Docker:
+
+```sh
+
+docker run -it --rm=true --name base-container -e POSTGRES_USER=base -e POSTGRES_PASSWORD=base -e POSTGRES_DB=base -p 5432:5432 postgres:13.3
+docker run -it --rm=true --name mycompany-container -e POSTGRES_USER=mycompany -e POSTGRES_PASSWORD=mycompany -e POSTGRES_DB=mycompany -p 5433:5432 postgres:13.3
+```
+
+Connection properties for the Agroal datasource are defined in the standard Quarkus configuration file,
+`src/main/resources/application.properties`.
+
+To access these databases, since the usernames and passwords are set inside the `%prod` profile, and the usernames are the same as the Postgres database names, we can use to access those:
+
+```sh
+docker exec -it base-container psql -U base
+docker exec -it mycompany-container psql -U mycompany
+```
+
+
+Then run it:
+
+> java -jar ./target/quarkus-app/quarkus-run.jar
+
+    Have a look at how fast it boots.
+    Or measure total native memory consumption...
+
+### Run Quarkus as a native application
+
+You can also create a native executable from this application without making any
+source code changes. A native executable removes the dependency on the JVM:
+everything needed to run the application on the target platform is included in
+the executable, allowing the application to run with minimal resource overhead.
+
+Compiling a native executable takes a bit longer, as GraalVM performs additional
+steps to remove unnecessary codepaths. Use the  `native` profile to compile a
+native executable:
+
+> ./mvnw package -Dnative
+
+After getting a cup of coffee, you'll be able to run this binary directly:
 
 > ./target/hibernate-orm-schema-multi-tenancy-quickstart-1.0.0-SNAPSHOT-runner
 
+    Please brace yourself: don't choke on that fresh cup of coffee you just got.
+    
+    Now observe the time it took to boot, and remember: that time was mostly spent to generate the tables in your database and import the initial data.
+    
+    Next, maybe you're ready to measure how much memory this service is consuming.
+
+N.B. This implies all dependencies have been compiled to native;
+that's a whole lot of stuff: from the bytecode enhancements that Hibernate ORM
+applies to your entities, to the lower level essential components such as the PostgreSQL JDBC driver, the Undertow webserver.
 
 ## See the demo in your browser
 

hibernate-orm-multi-tenancy-database-quickstart/src/main/java/org/acme/hibernate/orm/Fruit.java

@@ -5,18 +5,14 @@
 import jakarta.persistence.GeneratedValue;
 import jakarta.persistence.Id;
 import jakarta.persistence.NamedQuery;
-import jakarta.persistence.SequenceGenerator;
-import jakarta.persistence.Table;
 
 @Entity
-@Table(name = "known_fruits")
 @NamedQuery(name = "Fruits.findAll", query = "SELECT f FROM Fruit f ORDER BY f.name")
 @NamedQuery(name = "Fruits.findByName", query = "SELECT f FROM Fruit f WHERE f.name=:name")
 public class Fruit {
 
     @Id
-    @SequenceGenerator(name = "fruitsSequence", sequenceName = "known_fruits_id_seq", allocationSize = 1, initialValue = 10)
-    @GeneratedValue(generator = "fruitsSequence")
+    @GeneratedValue
     private Integer id;
 
     @Column(length = 40, unique = true)

hibernate-orm-multi-tenancy-database-quickstart/src/main/resources/META-INF/resources/index.html

@@ -141,7 +141,6 @@ <h1>Multitenancy Hibernate ORM - Quarkus</h1>
             <li>ArC, a CDI based dependency injection framework</li>
             <li>the Narayana Transaction Manager coordinating all transactions</li>
             <li>Agroal, the high performance Datasource implementation</li>
-            <li>Infinispan used as Hibernate 2nd level caching: enabled on both entities and queries</li>
             <li>The Undertow webserver</li>
             <li>Some magic bytecode generation plugged in the compiler...</li>
         </ul>

hibernate-orm-multi-tenancy-database-quickstart/src/main/resources/application.properties

@@ -5,16 +5,16 @@ quarkus.hibernate-orm.datasource=base
 
 # Default tenant 'base'
 quarkus.datasource.base.db-kind=postgresql
-quarkus.datasource.base.username=quarkus_test
-quarkus.datasource.base.password=quarkus_test
-%prod.quarkus.datasource.base.jdbc.url=jdbc:postgresql://localhost:5432/quarkus_test
 quarkus.flyway.base.locations=classpath:database/base
 quarkus.flyway.base.migrate-at-start=true
+%prod.quarkus.datasource.base.username=base
+%prod.quarkus.datasource.base.password=base
+%prod.quarkus.datasource.base.jdbc.url=jdbc:postgresql://localhost:5432/base
 
 # Tenant 'mycompany'
 quarkus.datasource.mycompany.db-kind=postgresql
-quarkus.datasource.mycompany.username=mycompany
-quarkus.datasource.mycompany.password=mycompany
-%prod.quarkus.datasource.mycompany.jdbc.url=jdbc:postgresql://localhost:5433/mycompany
 quarkus.flyway.mycompany.locations=classpath:database/mycompany
-quarkus.flyway.mycompany.migrate-at-start=true
+quarkus.flyway.mycompany.migrate-at-start=true
+%prod.quarkus.datasource.mycompany.username=mycompany
+%prod.quarkus.datasource.mycompany.password=mycompany
+%prod.quarkus.datasource.mycompany.jdbc.url=jdbc:postgresql://localhost:5433/mycompany

hibernate-orm-multi-tenancy-database-quickstart/src/main/resources/database/base/V1.0.0__create_fruits.sql

@@ -1,10 +1,10 @@
-CREATE SEQUENCE known_fruits_id_seq;
-SELECT setval('known_fruits_id_seq', 3);
-CREATE TABLE known_fruits
+CREATE SEQUENCE fruit_seq INCREMENT BY 50; -- 50 is quarkus default
+CREATE TABLE fruit
 (
-  id   INT,
-  name VARCHAR(40)
+    id   INT,
+    name VARCHAR(40)
 );
-INSERT INTO known_fruits(id, name) VALUES (1, 'Cherry');
-INSERT INTO known_fruits(id, name) VALUES (2, 'Apple');
-INSERT INTO known_fruits(id, name) VALUES (3, 'Banana');
+INSERT INTO fruit(id, name) VALUES (1, 'Cherry');
+INSERT INTO fruit(id, name) VALUES (2, 'Apple');
+INSERT INTO fruit(id, name) VALUES (3, 'Banana');
+ALTER SEQUENCE fruit_seq RESTART WITH 4;

hibernate-orm-multi-tenancy-database-quickstart/src/main/resources/database/mycompany/V1.0.0__create_fruits.sql

@@ -1,10 +1,10 @@
-CREATE SEQUENCE known_fruits_id_seq;
-SELECT setval('known_fruits_id_seq', 3);
-CREATE TABLE known_fruits
+CREATE SEQUENCE fruit_seq INCREMENT BY 50; -- 50 is quarkus default
+CREATE TABLE fruit
 (
   id   INT,
   name VARCHAR(40)
 );
-INSERT INTO known_fruits(id, name) VALUES (1, 'Avocado');
-INSERT INTO known_fruits(id, name) VALUES (2, 'Apricots');
-INSERT INTO known_fruits(id, name) VALUES (3, 'Blackberries');
+INSERT INTO fruit(id, name) VALUES (1, 'Avocado');
+INSERT INTO fruit(id, name) VALUES (2, 'Apricots');
+INSERT INTO fruit(id, name) VALUES (3, 'Blackberries');
+ALTER SEQUENCE fruit_seq RESTART WITH 4;

hibernate-orm-multi-tenancy-schema-quickstart/README.md

@@ -28,29 +28,80 @@ for help setting up your environment.
 Launch the Maven build on the checked out sources of this demo:
 
 > ./mvnw package
+
 ## Running the demo
 
-### Start Quarkus in development mode (Profile 'development')
+### Live coding with Quarkus
 
-The Maven Quarkus plugin provides a development mode that supports live coding. To try this out:
+The Maven Quarkus plugin provides a development mode that supports
+live coding. To try this out:
 
 > ./mvnw quarkus:dev
+
 In this mode you can make changes to the code and have the changes immediately applied, by just refreshing your browser.
 
-### Run Quarkus as native executable
+Dev Mode automatically starts a Docker container with a Postgres database. This feature is called ["Dev Services."](https://quarkus.io/guides/dev-services)
+
+To access the database from the terminal, run:
+
+```sh
+docker exec -it <container-name> psql -U quarkus
+```
+
+    Hot reload works even when modifying your JPA entities.
+    Try it! Even the database schema will be updated on the fly.
+
+### Run Quarkus in JVM mode
+
+When you're done iterating in developer mode, you can run the application as a
+conventional jar file.
+
+First compile it:
+
+> ./mvnw package
 
-You can also create a native executable from this application without making any source code changes. A native executable removes the dependency on the JVM:
-everything needed to run the application on the target platform is included in the executable, allowing the application to run with minimal resource overhead.
+Next, make sure you have a PostgreSQL database running. In production, Quarkus does not start a container for you like it does in Dev Mode.
+To set up a PostgreSQL database with Docker:
 
-Compiling a native executable takes a bit longer, as GraalVM performs additional steps to remove unnecessary codepaths. Use the  `native` profile to compile a
+> docker run -it --rm=true --name quarkus_test -e POSTGRES_USER=quarkus_test -e POSTGRES_PASSWORD=quarkus_test -e POSTGRES_DB=quarkus_test -p 5432:5432 postgres:13.3
+
+Connection properties for the Agroal datasource are defined in the standard Quarkus configuration file,
+`src/main/resources/application.properties`.
+
+Then run it:
+
+> java -jar ./target/quarkus-app/quarkus-run.jar
+
+    Have a look at how fast it boots.
+    Or measure total native memory consumption...
+
+### Run Quarkus as a native application
+
+You can also create a native executable from this application without making any
+source code changes. A native executable removes the dependency on the JVM:
+everything needed to run the application on the target platform is included in
+the executable, allowing the application to run with minimal resource overhead.
+
+Compiling a native executable takes a bit longer, as GraalVM performs additional
+steps to remove unnecessary codepaths. Use the  `native` profile to compile a
 native executable:
 
-> ./mvnw package -Pnative
+> ./mvnw package -Dnative
 
-After getting a cup of coffee, you'll be able to run this executable directly:
+After getting a cup of coffee, you'll be able to run this binary directly:
 
 > ./target/hibernate-orm-schema-multi-tenancy-quickstart-1.0.0-SNAPSHOT-runner
 
+    Please brace yourself: don't choke on that fresh cup of coffee you just got.
+    
+    Now observe the time it took to boot, and remember: that time was mostly spent to generate the tables in your database and import the initial data.
+    
+    Next, maybe you're ready to measure how much memory this service is consuming.
+
+N.B. This implies all dependencies have been compiled to native;
+that's a whole lot of stuff: from the bytecode enhancements that Hibernate ORM
+applies to your entities, to the lower level essential components such as the PostgreSQL JDBC driver, the Undertow webserver.
+
 ## See the demo in your browser
 
 Navigate to:

hibernate-orm-multi-tenancy-schema-quickstart/src/main/java/org/acme/hibernate/orm/Fruit.java

@@ -5,18 +5,14 @@
 import jakarta.persistence.GeneratedValue;
 import jakarta.persistence.Id;
 import jakarta.persistence.NamedQuery;
-import jakarta.persistence.SequenceGenerator;
-import jakarta.persistence.Table;
 
 @Entity
-@Table(name = "known_fruits")
 @NamedQuery(name = "Fruits.findAll", query = "SELECT f FROM Fruit f ORDER BY f.name")
 @NamedQuery(name = "Fruits.findByName", query = "SELECT f FROM Fruit f WHERE f.name=:name")
 public class Fruit {
 
     @Id
-    @SequenceGenerator(name = "fruitsSequence", sequenceName = "known_fruits_id_seq", allocationSize = 1, initialValue = 10)
-    @GeneratedValue(generator = "fruitsSequence")
+    @GeneratedValue
     private Integer id;
 
     @Column(length = 40, unique = true)

hibernate-orm-multi-tenancy-schema-quickstart/src/main/resources/META-INF/resources/index.html

@@ -141,7 +141,6 @@ <h1>Multitenancy Hibernate ORM - Quarkus</h1>
             <li>ArC, a CDI based dependency injection framework</li>
             <li>the Narayana Transaction Manager coordinating all transactions</li>
             <li>Agroal, the high performance Datasource implementation</li>
-            <li>Infinispan used as Hibernate 2nd level caching: enabled on both entities and queries</li>
             <li>The Undertow webserver</li>
             <li>Some magic bytecode generation plugged in the compiler...</li>
         </ul>