docs: Add a page about service file conflict for überjars (#578)

akka · May 31, 2024 · ccf6d51 · ccf6d51
1 parent 479cbe3
commit ccf6d51
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 0 deletions.
diff --git a/docs/src/main/paradox/index.md b/docs/src/main/paradox/index.md
@@ -20,6 +20,7 @@ The Akka Persistence R2DBC plugin allows for using SQL database with R2DBC as a
 * [Migration tool](migration.md)
 * [Migration Guide](migration-guide.md)
 * [Native Image](native-image.md)
+* [Troubleshooting](troubleshooting.md)
 * [Contributing](contributing.md)
 
 @@@

diff --git a/docs/src/main/paradox/troubleshooting.md b/docs/src/main/paradox/troubleshooting.md
@@ -0,0 +1,17 @@
+# Troubleshooting 
+
+## Failing to use the configured plugin 
+
+If you see something like this, where the driver is not available:
+
+```
+ Unable to create a ConnectionFactory for 'ConnectionFactoryOptions{options={...}}'. Available drivers: [ pool ]
+```
+
+It is likely because you are building a shaded jar with all dependencies and the ´META-INF/services` entry for 
+the R2DBC driver for the database you are using got lost.
+
+If using maven shading plugin, make sure to use the [ServicesResourceTransformer](https://maven.apache.org/plugins/maven-shade-plugin/examples/resource-transformers.html#ServicesResourceTransformer). 
+
+For other build tools, make sure the tool merges `META-INF/services/io.r2dbc.spi.ConnectionFactoryProvider` 
+files rather than dropping one when there is a conflict.