My second application tutorial

docs/src/main/asciidoc/getting-started-dev-services.adoc

@@ -0,0 +1,326 @@
+////
+This document is maintained in the main Quarkus repository
+and pull requests should be submitted there:
+https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
+////
+
+[id="getting-started-dev-services-tutorial"]
+= Your second Quarkus application
+include::_attributes.adoc[]
+:categories: getting-started, data, core
+
+
+This tutorial shows you how to create an application which writes to and reads from a database.
+You will use Dev Services, so you will not actually download, configure, or even start the database yourself.
+You will use Panache to make reading and writing data easier.
+
+
+== Prerequisites
+
+:prerequisites-time: 30 minutes
+:prerequisites-docker:
+:prerequisites-no-graalvm:
+include::{includes}/prerequisites.adoc[]
+
+This tutorial builds on what you learned writing xref:{doc-guides}/getting-started.adoc[your first Quarkus application].
+You will not need the code from that application, but make sure you understand the concepts.
+
+== Solution
+
+We recommend that you follow the instructions from <<Bootstrapping the project>> onwards to create the application step by step.
+
+However, you can go right to the completed example.
+
+Download an {quickstarts-archive-url}[archive] or clone the git repository:
+
+[source,bash,subs=attributes+]
+----
+git clone {quickstarts-clone-url}
+----
+
+The solution is located in the `getting-started-dev-services` {quickstarts-tree-url}/getting-started-dev-services[directory].
+
+:sectnums:
+:sectnumlevels: 3
+== Outline steps
+
+- Bootstrap the application
+- Update the application to read user input
+- Create a Panache Entity
+- Read and write the entity
+- Configure an external database using a profile
+
+== Setting up an interactive application
+
+=== Bootstrapping the project
+
+The easiest way to create a new Quarkus project is to open a terminal and run the following command:
+
+For Linux & MacOS users
+
+:create-app-artifact-id: getting-started-dev-services
+:create-app-extensions: resteasy-reactive
+:create-app-code:
+include::{includes}/devtools/create-app.adoc[]
+
+For Windows users:
+
+- If using cmd , (don't use backward slash `\` and put everything on the same line)
+- If using Powershell , wrap `-D` parameters in double quotes e.g. `"-DprojectArtifactId=getting-started"`
+
+For an explanation of what's in the generated application, see the xref:getting-started.adoc[First application guide].
+
+=== Running the application
+
+1. Launch the application in dev mode
+----
+mvn quarkus:dev
+----
+
+7. Visit http://localhost:8080/hello. It should show a "Hello from RestEasy Reactive" message.
+
+=== Accepting user input
+
+Let's make the application a bit more interactive.
+Open the project in your IDE and navigate to `src/main/java/org/acme/GreetingResource.java'
+Add a query param in the `hello` method.
+
+----
+public String hello(@QueryParam("name") String name) {
+return "Hello " + name;
+}
+----
+
+Visit http://localhost:8080/hello?name=Bloom.
+
+You should see a personalised message: `Hello Bloom`.
+
+=== Fixing the tests
+
+In your Quarkus terminal, type 'r' to run the tests. You should see
+that your application changes broke the tests!
+
+To fix the tests, open `src/test/java/org/acme/GreetingResource.test`
+and replace
+
+----
+             .body(is("Hello from RESTEasy Reactive"));
+----
+
+with
+
+----
+             .body(containsString("Hello"));
+----
+
+This still validates the rest endpoint, but it's more flexible
+about the expected output.
+You should see in your terminal that the tests are now passing.
+
+== Adding persistence
+
+=== Creating a Panache Entity
+
+1. To add the persistence libraries, run
+----
+quarkus ext add hibernate-orm-panache jdbc-postgresql
+----
+
+The application will record the names of people it greets. Define a simple Hibernate Entity
+by creating a `Greeting.java` class. Add the following content:
+
+----
+@Entity
+public class Greeting extends PanacheEntity {
+String name;
+}
+----
+
+The entity makes use of xref:{doc-guides}hibernate-orm-panache.adoc[Panache], a layer on top of Hibernate.
+ Extending `PanacheEntity` brings in a range of methods for reading, writing, and finding data.
+ Because all the data access methods are on the `Greeting` entity, rather than on a separate data access class,
+ this is an example of the active record pattern.
+
+The `Greeting` table will have one column, a field called `name`.
+
+=== Writing data
+
+To use the new entity, update the `hello` method to start writing some data.
+
+Change the method to the following:
+
+----
+@GET
+@Transactional
+@Produces(MediaType.TEXT_PLAIN)
+public String hello(@QueryParam("name") String name) {
+   Greeting greeting = new Greeting();
+   greeting.name = name;
+   greeting.persist();
+   return "Hello " + name;
+}
+----
+
+Don't forget the `@Transactional` method, which ensures writes are wrapped
+in a transaction.
+
+Generally, you shouldn't do state updates on a `GET` REST method, but here it makes
+trying things out simpler. Let's assume what's being written is an logging "side effect",
+rather than a meaningful state changes!
+
+Try out the updated endpoint by visiting http://localhost:8080/hello?name=Bloom.
+You should see a "Hello Bloom" message.
+
+=== Reading data
+Although the new persistence code seems to be working without errors, how
+do you know anything is being written to the database?
+
+Add a second REST method to `GreetingResource`.
+
+----
+@GET
+@Path("names")
+@Produces(MediaType.TEXT_PLAIN)
+public String names() {
+List<Greeting> greetings = Greeting.listAll();
+   String names = greetings.stream().map(g-> g.name)
+   .collect(Collectors.joining (", "));
+   return "I've said hello to " + names;
+}
+----
+
+To try it out, visit http://localhost:8080/hello?name=Bloom, and then http://localhost/hello/names.
+
+You should see the following message: "I've said hello to Bloom".
+
+== Dev services
+
+Reading and writing to the database seems to be working well, but that's a bit unexpected.
+Where did a PostgresQL database come from? You didn't set anything up.
+
+The database is being managed using xref:{docfile}/dev-services.adoc[dev services].
+Dev services take care of stopping and starting services needed by your application.
+Because you
+included the `postgresql-jdbc` dependency, the database is a containerised PostGresQL database.
+If you'd added `postgresql-mysql` insead, you would have gotten a containerised MySQL database.
+
+If you like, use your container tool to see what containers are running.
+For example, if you're using Docker, run `docker ps`, and for podman, run `podman ps`.
+You'll see something like the following:
+
+----
+ff88dcedd899  docker.io/library/postgres:14  postgres -c fsync...  1 hour ago  Up 1 hour  0.0.0.0:34789->5432/tcp  nostalgic_bassi
+----
+
+Stop Quarkus and run `docker ps` again.
+You should see nothing running.
+Quarkus will automatically stop the container when your application stops.
+
+=== Initialising services
+
+If you play with your code some more, you may notice that sometimes, after making an application change, http://localhost/hello/names doesn't list any names.
+What's going on? By default, in dev mode, with a dev services database,
+ Quarkus configures Hibernate database generation to be `drop-and-create`.
+ See the xref:{docfile}/hibernate-orm.adoc#quarkus-hibernate-orm_quarkus.hibernate-orm.database-database-related-configuration[Hibernate configuration reference] for more details.
+ If a code change triggers an application restart, the database tables
+ will be dropped (deleted) and then re-created.
+
+This is convenient, but what if you'd prefer the database to always have content?
+That would make testing easier.
+If you provide an `import.sql` file, Quarkus will use that to initialise
+the database on each start.
+
+2. Make a `src/main/resources/import.sql` file in your project
+3. Add the following SQL statements:
+
+----
+INSERT INTO Greeting(id, name)
+VALUES (nextval('Greeting_SEQ'), 'Alice');
+INSERT INTO Greeting(id, name)
+VALUES (nextval('Greeting_SEQ'), 'Bob');
+----
+
+Now, try stopping and starting your application, and then visiting http://localhost:8080/hello/names.
+You'll see that Alice and Bob are always included in the list of names.
+
+== Controlling dev services
+
+=== Using an external database instead
+
+What if you'd rather use an external database that you manage yourself?
+Add the following to `src/main/resources/application.properties`:
+
+----
+# configure your datasource
+quarkus.datasource.db-kind = postgresql
+quarkus.datasource.username = leopold
+quarkus.datasource.password = bloom
+quarkus.datasource.jdbc.url = jdbc:postgresql://localhost:5432/mydatabase
+----
+
+This tells Quarkus that you don't want it to start a dev service,
+because you have your own database. You don't need to worry about starting
+the database, because you're just seeing how to change the configuration.
+
+Visit `http://localhost:8080/hello/names`. Instead of a list of names,
+you'll get a red error screen. In the terminal where Quarkus is running.
+you'll see the following stack error message:
+
+----
+2023-06-28 19:18:22,880 ERROR [io.qua.ver.htt.run.QuarkusErrorHandler] (executor-thread-1) HTTP Request to /hello?name=fred failed, error id: 4f9b5ce6-3b08-41c5-af36-24eee4d1dd2b-2: org.hibernate.exception.JDBCConnectionException: Unable to acquire JDBC Connection [Connection to localhost:5432 refused. Check that the hostname and port are correct and that the postmaster is accepting TCP/IP connections.] [n/a]
+        at org.hibernate.exception.internal.SQLStateConversionDelegate.convert(SQLStateConversionDelegate.java:98)
+        at org.hibernate.exception.internal.StandardSQLExceptionConverter.convert(StandardSQLExceptionConverter.java:56)
+...
+----
+
+This makes sense; you've disabled the database dev service, but you haven't
+started your own database.
+
+=== Using profiles
+
+Unless you want to, don't worry about setting up an external database
+to resolve the connection error. Instead, you will go back to using the dev service.
+It made life easy!
+
+But what about production? You won't want to use dev services in production.
+In fact, Quarkus only starts dev services in dev and test modes.
+
+Wouldn't it be nice to configure an external database,
+ but have it *only* used in production, so you could still
+ use dev services the rest of the time?
+
+Add a `%prod`
+prefix to the database configuration. This means the configuration
+only applies to the xref:{docfile}/config-reference#profiles[prod profile]
+
+The configuration should look like this:
+
+----
+# configure your datasource
+%prod.quarkus.datasource.db-kind = postgresql
+%prod.quarkus.datasource.username = leopold
+%prod.quarkus.datasource.password = bloom
+%prod.quarkus.datasource.jdbc.url = jdbc:postgresql://localhost:5432/mydatabase
+----
+
+Now the external database will be used in prod mode,
+and dev services will be used in dev and test modes.
+
+Check http://localhost:8080/hello/names. It should be working again,
+because the dev services have been re-enabled.
+Notice that there was no need to restart Quarkus for any of these changes.
+
+
+:sectnums!:
+== Summary
+
+You've taken a simple REST application and updated it to write and read
+data from a database, using Hibernate and Panache. The data was peristed to
+a 'real' database, without you having to configure anything.
+
+
+== References
+
+* xref:{doc-guides}dev-services.adoc[Dev services]
+
+* xref:{doc-guides}hibernate-orm-panache.adoc[Panache]