jamesfredley opened a new pull request, #15406: URL: https://github.com/apache/grails-core/pull/15406
## Summary Adds documentation for using GORM Data Services with multiple datasources - a topic completely absent from grails-doc today. Covers `@Transactional(connection)` routing, `GormEnhancer.findStaticApi()` for statically compiled escape-hatch queries, and the interface + abstract class pattern. ## Changes **`multipleDatasources.adoc`** - New "GORM Data Services and Multiple Datasources" section with 4 subsections: - **Basic Pattern** - Interface + abstract class with `@Transactional(connection = 'books')`, explaining that the `connection` parameter is required (the `@Service` annotation alone does not determine datasource routing) - **How Connection Routing Works** - How `ServiceTransformation` copies the `@Transactional(connection)` annotation to the generated implementation and how `findConnectionId()` propagates it to auto-implemented methods - **Complex Queries with GormEnhancer** - `GormEnhancer.findStaticApi(Book, 'books')` pattern for HQL, criteria, and aggregation queries that cannot be auto-implemented. Includes a reference table of all available `GormStaticApi` methods - **Consuming Multi-Datasource Data Services** - Injecting the interface type in other services **`transactionsMultiDataSource.adoc`** - Added a TIP cross-referencing the new Data Services section ## Why This Is Needed Currently, `multipleDatasources.adoc` only documents the old `static datasource = 'lookup'` pattern on plain services. There is zero mention of: - `@Service` (GORM Data Services) - `@Transactional(connection = 'xxx')` for datasource routing - `GormEnhancer.findStaticApi()` for statically compiled access - `GormStaticApi` and its available methods These are all essential for production multi-datasource applications using modern GORM patterns. Without this documentation, developers must read the `ServiceTransformation` source code to understand how connection routing works. ## Verified Against Source All technical claims were verified against grails-core source: - `ServiceTransformation.groovy` line 253: `copyAnnotations(classNode, impl)` copies `@Transactional(connection)` to generated implementation - `TransactionalTransform.findTransactionalAnnotation()` lines 171-176: falls back to `methodNode.getDeclaringClass()` to find the connection identifier - `SaveImplementer`, `FindOneImplementer`, `DeleteImplementer`, `CountImplementer`: all call `findConnectionId()` and use it in generated method bodies - `GormEnhancer.findStaticApi(Class, String)`: returns `GormStaticApi` bound to the specified connection ## Environment Information - Grails 7.0.x branch - GORM 7.x - Groovy 4.0.x -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
