Split multi-tenancy quickstart into two projects #1493

tobHai · 2025-01-19T16:31:35Z

Check list:

Your pull request:

I split the existing quickstart into two:

schema approach
database approach

Additionally, I used dev services for the database connections.
The only real code change I did was fixing a warning in: d939238 (#1493)

I am not sure to which guide the checklist is referring to - do I need to update another project as well?

yrodiere · 2025-01-20T09:49:15Z

I am not sure to which guide the checklist is referring to - do I need to update another project as well?

It refers to the Quarkus guide. The documentation.
In this case this file: https://github.com/quarkusio/quarkus/blob/main/docs/src/main/asciidoc/hibernate-orm.adoc
In particular you'll see reference to quickstarts for multitenancy here: https://github.com/quarkusio/quarkus/blob/cc10bd920755824b94437e88ac01da8651eb7ea0/docs/src/main/asciidoc/hibernate-orm.adoc?plain=1#L1085

So you'd need to:

Remove that reference (it's now invalid)
Introduce references to your newly introduced quickstarts in the relevant subsections
Make sure any code examples mentioned in these subsections is consistent with your newly introduced quickstarts

yrodiere

Thanks, that's a nice cleanup. I added a few comments below.

Before merging, I think we'll need:

Comments to be addressed/dismissed.
A PR to be sent to the main Quarkus repo to make sure the documentation (hibernate-orm.adoc) is updated consistently.
Ideally, all commits in this PR to be squashed into at most two: the splitting, and the addition of @PersistenceUnitExtension on tenant resolvers. EDIT: Okay maybe three if you want to keep the devservice thing separate, but that seems like it could be annoying to do properly, so I'd just squash that together in the same commit as the splitting.

I created a follow-up issue (quarkusio/quarkus#45715), but it's out of scope: just a few pre-existing problems that your PR reminded me of (thanks!).

yrodiere · 2025-01-20T09:51:16Z

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

+### DATABASE Multitenancy
+
+Approach that uses a separate database (datasource 'base' and 'mycompany') for storing the tenant's data.
+
+#### Start Quarkus in development mode
+
+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


You can probably remove the section header since the whole project is about database multitenancy.

Suggested change

### DATABASE Multitenancy

Approach that uses a separate database (datasource 'base' and 'mycompany') for storing the tenant's data.

#### Start Quarkus in development mode

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

### Start Quarkus in development mode

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

yrodiere · 2025-01-20T09:54:46Z

hibernate-orm-multi-tenancy-database-quickstart/pom.xml

+        <profile>
+            <id>eclipse</id>
+            <activation>
+                <property>
+                    <!-- This is a trick to have the profile automatically activated by Eclipse -->
+                    <name>m2e.version</name>
+                </property>
+            </activation>
+            <build>
+                <pluginManagement>
+                    <plugins>
+                        <!--This plugin's configuration is used to store Eclipse m2e settings only. It has no influence on the Maven build itself.-->
+                        <plugin>
+                            <groupId>org.eclipse.m2e</groupId>
+                            <artifactId>lifecycle-mapping</artifactId>
+                            <version>1.0.0</version>
+                            <configuration>
+                                <lifecycleMappingMetadata>
+                                    <pluginExecutions>
+                                        <pluginExecution>
+                                            <pluginExecutionFilter>
+                                                <groupId>io.fabric8</groupId>
+                                                <artifactId>
+                                                    docker-maven-plugin
+                                                </artifactId>
+                                                <versionRange>
+                                                    [0.28.0,)
+                                                </versionRange>
+                                                <goals>
+                                                    <goal>start</goal>
+                                                    <goal>stop</goal>
+                                                </goals>
+                                            </pluginExecutionFilter>
+                                            <action>
+                                                <ignore></ignore>
+                                            </action>
+                                        </pluginExecution>
+                                    </pluginExecutions>
+                                </lifecycleMappingMetadata>
+                            </configuration>
+                        </plugin>
+                    </plugins>
+                </pluginManagement>
+            </build>
+        </profile>


This can be removed, since you removed docker-maven-plugin.

Suggested change

<profile>

<id>eclipse</id>

<activation>

<property>



<name>m2e.version</name>

</property>

</activation>

<build>

<pluginManagement>

<plugins>



<plugin>

<groupId>org.eclipse.m2e</groupId>

<artifactId>lifecycle-mapping</artifactId>

<version>1.0.0</version>

<configuration>

<lifecycleMappingMetadata>

<pluginExecutions>

<pluginExecution>

<pluginExecutionFilter>

<groupId>io.fabric8</groupId>

<artifactId>

docker-maven-plugin

</artifactId>

<versionRange>

[0.28.0,)

</versionRange>

<goals>

<goal>start</goal>

<goal>stop</goal>

</goals>

</pluginExecutionFilter>

<action>

<ignore></ignore>

</action>

</pluginExecution>

</pluginExecutions>

</lifecycleMappingMetadata>

</configuration>

</plugin>

</plugins>

</pluginManagement>

</build>

</profile>

yrodiere · 2025-01-20T12:19:13Z

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

+When serving multiple customers from a same application (e.g.: SaaS), each customer is a tenant with a separate database or a separate schema in the same database. 
+
+For the schema per tenant approach see [Schema Quickstart](../hibernate-orm-multi-tenancy-schema-quickstart/README.md).


Suggested change

When serving multiple customers from a same application (e.g.: SaaS), each customer is a tenant with a separate database or a separate schema in the same database.

For the schema per tenant approach see [Schema Quickstart](../hibernate-orm-multi-tenancy-schema-quickstart/README.md).

When serving multiple customers from a same application (e.g.: SaaS), each customer is a tenant with a separate database.

For the schema per tenant approach see [Schema Quickstart](../hibernate-orm-multi-tenancy-schema-quickstart/README.md).

yrodiere · 2025-01-20T12:21:57Z

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

+### SCHEMA Multitenancy
+
+Approach that uses a single database (default datasource) with two schemas ('base' and 'mycompany') for storing the tenant's data.
+
+#### Start Quarkus in development mode (Profile 'development')
+
+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
+
+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
+
+After getting a cup of coffee, you'll be able to run this executable directly:
+
+> ./target/hibernate-orm-schema-multi-tenancy-quickstart-1.0.0-SNAPSHOT-runner


Same as above, the heading probably isn't necessary anymore.

Suggested change

### SCHEMA Multitenancy

Approach that uses a single database (default datasource) with two schemas ('base' and 'mycompany') for storing the tenant's data.

#### Start Quarkus in development mode (Profile 'development')

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

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

After getting a cup of coffee, you'll be able to run this executable directly:

> ./target/hibernate-orm-schema-multi-tenancy-quickstart-1.0.0-SNAPSHOT-runner

### Start Quarkus in development mode (Profile 'development')

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

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

After getting a cup of coffee, you'll be able to run this executable directly:

> ./target/hibernate-orm-schema-multi-tenancy-quickstart-1.0.0-SNAPSHOT-runner

yrodiere · 2025-01-20T12:46:13Z

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

You should probably align this file on the docs, since that's where we'll explain the quickstart:

One thing you'll want to change compared to the docs though (and maybe update in the docs): the JDBC URL property needs to be prefixed with %prod, otherwise dev services will be disabled and Quarkus will just try to connect to that URL.

So this:

quarkus.datasource.base.jdbc.url=jdbc:postgresql://localhost:5432/quarkus_test ... quarkus.datasource.mycompany.jdbc.url=jdbc:postgresql://localhost:5433/mycompany

Should be this instead:

%prod.quarkus.datasource.base.jdbc.url=jdbc:postgresql://localhost:5432/quarkus_test ... %prod.quarkus.datasource.mycompany.jdbc.url=jdbc:postgresql://localhost:5433/mycompany

yrodiere · 2025-01-20T12:46:47Z

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

Same here, ideally the whole file should be made consistent with the one at https://quarkus.io/guides/hibernate-orm#schema-approach

Here too, the JDBC URL should be limited to the prod profile, otherwise dev services will be disabled.

yrodiere · 2025-01-20T13:06:00Z

...ate-orm-multi-tenancy-schema-quickstart/src/test/java/org/acme/hibernate/orm/IdeTestApp.java

+/**
+ * Workaround to allow launching the Quarkus application inside the IDE.
+ * 
+ * @see https://github.com/quarkusio/quarkus/issues/2143
+ */
+@Disabled("You can enable this pseudo test to run the app in your IDE")
+@QuarkusTest
+public class IdeTestApp {


This issue appears to have been fixed. I'd suggest removing this class from both Maven modules?

yrodiere · 2025-01-20T13:29:33Z

...i-tenancy-database-quickstart/src/main/java/org/acme/hibernate/orm/CustomTenantResolver.java

You should probably use @PersistenceUnitExtension here too?

yrodiere · 2025-01-20T13:31:48Z

Also, I tested locally, it works great! Much better experience than the previous docker-compose setup with Maven profiles.

quarkus-bot · 2025-01-20T14:18:21Z

Status for workflow `Pull Request Build - development`

This is the status report for running Pull Request Build - development on commit 8871672.

✅ The latest workflow run for the pull request has completed successfully.

It should be safe to merge provided you have a look at the other checks in the summary.

tobHai added 8 commits January 19, 2025 17:26

Split multi-tenancy quickstart into two projects

7dc4c0f

Use dev services in schema quickstart

263f921

Cleanup schema quickstart

5a0370d

Fix warning in schema quickstart

d939238

Use dev services in database example

0b0be39

Cleanup properties

bec0068

Update README

c1b350e

Further cleanup

8871672

tobHai marked this pull request as ready for review January 19, 2025 17:49

tobHai mentioned this pull request Jan 19, 2025

Hibernate ORM multi-tenancy quickstart is outdated (and broken) quarkusio/quarkus#41759

Open

yrodiere reviewed Jan 20, 2025

View reviewed changes

yrodiere self-assigned this Jan 20, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Split multi-tenancy quickstart into two projects #1493

Split multi-tenancy quickstart into two projects #1493

tobHai commented Jan 19, 2025 •

edited by yrodiere

Loading

yrodiere commented Jan 20, 2025

yrodiere left a comment •

edited

Loading

yrodiere Jan 20, 2025

yrodiere Jan 20, 2025

yrodiere Jan 20, 2025

yrodiere Jan 20, 2025

yrodiere Jan 20, 2025

yrodiere Jan 20, 2025

yrodiere Jan 20, 2025

yrodiere Jan 20, 2025

yrodiere commented Jan 20, 2025

quarkus-bot bot commented Jan 20, 2025

		When serving multiple customers from a same application (e.g.: SaaS), each customer is a tenant with a separate database or a separate schema in the same database.

		For the schema per tenant approach see [Schema Quickstart](../hibernate-orm-multi-tenancy-schema-quickstart/README.md).

Split multi-tenancy quickstart into two projects #1493

Are you sure you want to change the base?

Split multi-tenancy quickstart into two projects #1493

Conversation

tobHai commented Jan 19, 2025 • edited by yrodiere Loading

yrodiere commented Jan 20, 2025

yrodiere left a comment • edited Loading

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

yrodiere commented Jan 20, 2025

quarkus-bot bot commented Jan 20, 2025

Status for workflow Pull Request Build - development

tobHai commented Jan 19, 2025 •

edited by yrodiere

Loading

yrodiere left a comment •

edited

Loading

Status for workflow `Pull Request Build - development`