docs: update multi-datasource docs for @CompileStatic injection, MultiTenant routing, and CRUD connection fixes

Add documentation reflecting the post-fix state after PRs apache#15393,
apache#15395, and apache#15396 are merged:

- Add @CompileStatic + injected @service property example (PR apache#15396)
- Add Multi-Tenancy with explicit datasource section (PR apache#15393)
- List all CRUD methods that respect connection routing (PR apache#15395)
- Soften IMPORTANT boxes to NOTE with authoritative tone

Assisted-by: Claude Code <Claude@Claude.ai>

Author: jamesfredley

grails-data-hibernate5/docs/src/docs/asciidoc/multipleDataSources/dataSourceNamespaces.adoc

@@ -62,4 +62,4 @@ def results = c.list {
 }
 ----
 
-TIP: The namespace syntax (e.g., `ZipCode.auditing.get(42)`) uses dynamic dispatch and is not compatible with `@CompileStatic`. For statically compiled code, use `GormEnhancer.findStaticApi(ZipCode, 'auditing')` instead, which returns a `GormStaticApi` handle with the same methods routed to the specified datasource. See the <<dataServicesMultipleDataSources,Data Services and Multiple Datasources>> section for examples.
+TIP: The namespace syntax (e.g., `ZipCode.auditing.get(42)`) uses dynamic dispatch and is not compatible with `@CompileStatic`. For statically compiled code, use `GormEnhancer.findStaticApi(ZipCode, 'auditing')` to obtain a `GormStaticApi` handle with the same methods routed to the specified datasource, or use a Data Service with `@Transactional(connection = 'auditing')` for automatic routing. See the <<dataServicesMultipleDataSources,Data Services and Multiple Datasources>> section for the full pattern.

grails-data-hibernate5/docs/src/docs/asciidoc/multipleDataSources/index.adoc

@@ -33,7 +33,7 @@ include::dataSourceNamespaces.adoc[]
 
 === Using Data Services with Multiple Datasources
 
-When using GORM Data Services (`@Service` annotation) with secondary datasources, you must annotate the abstract class with `@Transactional(connection = 'connectionName')` to route all auto-implemented methods to the correct datasource. See the <<dataServicesMultipleDataSources,Data Services and Multiple Datasources>> section for the full pattern, including `GormEnhancer.findStaticApi()` for complex queries.
+GORM Data Services support multi-datasource routing via `@Transactional(connection = 'connectionName')` on the abstract class. All auto-implemented methods - `get()`, `save()`, `delete()`, `findBy*()`, `countBy*()` - route to the specified datasource automatically. This works with `@CompileStatic`, injected `@Service` properties, and `MultiTenant` domain classes. See the <<dataServicesMultipleDataSources,Data Services and Multiple Datasources>> section for the full pattern, including `GormEnhancer.findStaticApi()` for complex queries.
 
 [[connectionSources]]
 === The ConnectionSources API

grails-data-hibernate5/docs/src/docs/asciidoc/services/multipleDataSources.adoc

@@ -73,7 +73,7 @@ abstract class BookService implements BookDataService {
 
 The `@Transactional(connection = 'books')` annotation on the abstract class ensures that all auto-implemented methods (`get`, `save`, `delete`, `findBy*`, `countBy*`, etc.) route to the `books` datasource. Without this annotation, queries silently route to the default datasource.
 
-IMPORTANT: The `connection` parameter is required when using Data Services with secondary datasources. The `@Service(Book)` annotation alone does not determine which datasource to use, even if the `Book` domain class declares `datasource 'books'` in its mapping block.
+NOTE: The `@Service(Book)` annotation identifies the domain class but does not determine which datasource to use. Even if `Book` declares `datasource 'books'` in its mapping block, you must specify `@Transactional(connection = 'books')` on the abstract class to route operations to the correct datasource.
 
 ==== How Connection Routing Works
 
@@ -189,3 +189,80 @@ class LibraryService {
 ----
 
 The consuming service does not need `@Transactional(connection = 'books')`. The Data Service handles datasource routing internally.
+
+Data Services can also inject other Data Services. `@CompileStatic` works on `@Service` abstract classes that declare `@Service`-typed properties:
+
+[source,groovy]
+----
+import grails.gorm.services.Service
+
+interface AuthorDataService {
+
+    Author get(Serializable id)
+
+    Author save(Author author)
+}
+----
+
+[source,groovy]
+----
+import groovy.transform.CompileStatic
+import grails.gorm.services.Service
+import grails.gorm.transactions.Transactional
+
+@CompileStatic
+@Service(Author)
+@Transactional(connection = 'books')
+abstract class AuthorService implements AuthorDataService {
+
+    BookDataService bookDataService  // injected @Service property
+
+    Map getAuthorWithBooks(Serializable authorId) {
+        Author author = get(authorId)
+        List<Book> books = bookDataService.findAllByAuthor(author.name)
+        [author: author, books: books]
+    }
+}
+----
+
+When the Spring context initializes the generated implementation class, it eagerly populates all `@Service`-typed properties via `datastore.getService()`. By the time any user code runs, injected Data Services are fully available.
+
+==== Multi-Tenancy with Multiple Datasources
+
+Domain classes that implement `GormEntity` with the `MultiTenant` trait and declare an explicit non-default datasource (e.g., `datasource 'analytics'`) route correctly through Data Services. GORM's `GormEnhancer` preserves explicit datasource qualifiers for multi-tenant entities, so Data Services using `@Transactional(connection = 'analytics')` work the same way as for non-tenant domain classes:
+
+[source,groovy]
+----
+import grails.gorm.MultiTenant
+
+class Metric implements MultiTenant<Metric> {
+
+    String name
+    BigDecimal value
+
+    static mapping = {
+        datasource 'analytics'
+    }
+}
+----
+
+[source,groovy]
+----
+import grails.gorm.services.Service
+import grails.gorm.transactions.Transactional
+import groovy.transform.CompileStatic
+
+@CompileStatic
+@Service(Metric)
+@Transactional(connection = 'analytics')
+abstract class MetricService {
+
+    abstract Metric get(Serializable id)
+
+    abstract Metric save(Metric metric)
+
+    abstract List<Metric> list()
+}
+----
+
+The `connection` parameter on the abstract class routes all auto-implemented operations - including `save()`, `get()`, and `delete()` - to the `analytics` datasource, regardless of multi-tenancy mode (DATABASE or DISCRIMINATOR).

grails-doc/src/en/guide/conf/dataSource/multipleDatasources.adoc

@@ -264,7 +264,7 @@ If you have a `Foo` domain class in `dataSource1` and a `Bar` domain class in `d
 ==== GORM Data Services and Multiple Datasources
 
 
-GORM Data Services provide a statically compiled alternative to the `static datasource` property shown above. When a `@Service` abstract class needs to route queries to a non-default datasource, use the `connection` parameter of `@Transactional`.
+GORM Data Services provide a type-safe, statically compiled approach to multi-datasource access. When a `@Service` abstract class needs to route operations to a non-default datasource, declare the target connection with `@Transactional(connection = 'name')`.
 
 
 ===== Basic Pattern
@@ -307,7 +307,7 @@ abstract class BookService implements BookDataService {
 
 The `@Transactional(connection = 'books')` annotation on the abstract class ensures that all auto-implemented methods (`get`, `save`, `delete`, `findBy*`, `countBy*`, etc.) route to the `books` datasource. Without this annotation, queries silently route to the default datasource.
 
-IMPORTANT: The `connection` parameter is required when using Data Services with secondary datasources. The `@Service(Book)` annotation alone does not determine which datasource to use, even if the `Book` domain class has `datasource 'books'` in its mapping block.
+NOTE: The `@Service(Book)` annotation identifies the domain class but does not determine which datasource to use. Even if `Book` declares `datasource 'books'` in its mapping block, you must specify `@Transactional(connection = 'books')` on the abstract class to route operations to the correct datasource.
 
 
 ===== How Connection Routing Works
@@ -436,6 +436,85 @@ class LibraryService {
 
 The consuming service does not need `@Transactional(connection = 'books')`. The Data Service handles datasource routing internally. If the consuming service coordinates writes across multiple Data Services, annotate the orchestrating method with `@Transactional` to ensure atomicity on the default datasource.
 
+Data Services can also inject other Data Services. `@CompileStatic` works on `@Service` abstract classes that declare `@Service`-typed properties:
+
+[source,groovy]
+----
+import grails.gorm.services.Service
+
+interface AuthorDataService {
+
+    Author get(Serializable id)
+
+    Author save(Author author)
+}
+----
+
+[source,groovy]
+----
+import groovy.transform.CompileStatic
+import grails.gorm.services.Service
+import grails.gorm.transactions.Transactional
+
+@CompileStatic
+@Service(Author)
+@Transactional(connection = 'books')
+abstract class AuthorService implements AuthorDataService {
+
+    BookDataService bookDataService  // injected @Service property
+
+    Map getAuthorWithBooks(Serializable authorId) {
+        Author author = get(authorId)
+        List<Book> books = bookDataService.findAllByAuthor(author.name)
+        [author: author, books: books]
+    }
+}
+----
+
+When the Spring context initializes the generated implementation class, it eagerly populates all `@Service`-typed properties via `datastore.getService()`. By the time any user code runs, injected Data Services are fully available.
+
+
+===== Multi-Tenancy with Multiple Datasources
+
+
+Domain classes that implement `GormEntity` with the `MultiTenant` trait and declare an explicit non-default datasource (e.g., `datasource 'analytics'`) route correctly through Data Services. GORM's `GormEnhancer` preserves explicit datasource qualifiers for multi-tenant entities, so Data Services using `@Transactional(connection = 'analytics')` work the same way as for non-tenant domain classes:
+
+[source,groovy]
+----
+import grails.gorm.MultiTenant
+
+class Metric implements MultiTenant<Metric> {
+
+    String name
+    BigDecimal value
+
+    static mapping = {
+        datasource 'analytics'
+    }
+}
+----
+
+[source,groovy]
+----
+import grails.gorm.services.Service
+import grails.gorm.transactions.Transactional
+import groovy.transform.CompileStatic
+
+@CompileStatic
+@Service(Metric)
+@Transactional(connection = 'analytics')
+abstract class MetricService {
+
+    abstract Metric get(Serializable id)
+
+    abstract Metric save(Metric metric)
+
+    abstract List<Metric> list()
+}
+----
+
+The `connection` parameter on the abstract class routes all auto-implemented operations - including `save()`, `get()`, and `delete()` - to the `analytics` datasource, regardless of multi-tenancy mode (DATABASE or DISCRIMINATOR).
+
 
 ==== Transactions across multiple data sources
 

grails-doc/src/en/guide/services/declarativeTransactions/transactionsMultiDataSource.adoc

@@ -62,7 +62,7 @@ class BookService {
 }
 ----
 
-TIP: When using GORM Data Services (`@Service` annotation), use `@Transactional(connection = 'books')` on the abstract class instead of per-method annotations. This routes all auto-implemented methods to the correct datasource automatically. See the <<multipleDatasources,Data Services and Multiple Datasources>> section for details.
+TIP: GORM Data Services offer a simpler approach. Annotate the `@Service` abstract class with `@Transactional(connection = 'books')` and all auto-implemented methods - `get()`, `save()`, `delete()`, `findBy*()`, `countBy*()` - route to the correct datasource automatically. See the <<multipleDatasources,Data Services and Multiple Datasources>> section for the full pattern.
 
 [source, groovy]
 ----