Unresolved reference: Repository

[distinctdan]

Expected Behavior

I'm trying to add micronaut-data to an existing project. The docs say to add the following to gradle, which doesn't work:

annotationProcessor("io.micronaut.data:micronaut-data-processor")

I'm getting the error Unresolved reference: Repository when I try to add the @Repository annotation to an interface. The docs mention a runtime dependency, but they don't tell what it is. This is basic stuff guys, I shouldn't have to do an hour of research to figure out all of the required packages, this needs to be in the docs. The docs seem to assume that you're going to regenerate a new micronaut starter project every time, which isn't convenient at all.

After further research, it looks like there are a variety of possible dependencies scattered throughout the docs. These should all be moved to up at the top under the Build Configuration heading, and it should be clearly stated that you have to install one of them. As a user, I should be able to install micronaut-data and start using it quickly, without having to read and understand the entire documentation. There needs to be a "getting started" section that clearly states what you need to do to install it and get started, just like most other libraries.

Actual Behaviour

The docs should correctly state how to install micronaut-data.

Steps To Reproduce

No response

Environment Information

No response

Example Application

No response

Version

Latest

[distinctdan]

Allow me to walk through my experience as a new user to help you guys better understand my journey through the site. I'm documenting this to help you understand my user flow, so that you guys can make the docs easier to use:

1. I visit the docs for micronaut-data. I immediately see a bunch of stuff about history and a changelog, which I don't care about as a new user.
2. I see a Build Configuration section which looks like what I want, to figure out how to install it and configure it.
3. I follow the steps in Build Configuration and add the dependency annotationProcessor("io.micronaut.data:micronaut-data-processor").
4. I go down to the very next section 3.1 Repository Interfaces and start trying to create a @Repository.
5. It doesn't work.
6. I waste an hour trying to figure out why it doesn't work, I read a lot more of the docs, and eventually discover you have to add other dependencies, which should have been listed or linked up-front, but are actually scattered throughout the rest of the docs.

[graemerocher]

Good feedback. The docs have an "Improve this doc" link above each section, perhaps you would like to contribute to add clarity to areas you think are lacking?

[distinctdan]

Thanks, I might be open to updating docs, but I still haven't gotten this working yet. It may be better to have someone with more domain knowledge do it if anyone is available. The current error I'm running into is the same as this issue: https://github.com/micronaut-projects/micronaut-data/pull/197. Here are my dependencies for micronaut-data, not sure what I'm missing yet:

    annotationProcessor("io.micronaut.data:micronaut-data-processor")
    implementation("io.micronaut.data:micronaut-data-jdbc")
    compileOnly("jakarta.persistence:jakarta.persistence-api")

[dstepanov]

You would also need a JDBC driver and a JDBC pool

[distinctdan]

Thanks, ok, I've got it working now, it looks like @Repository isn't compatible with JDBC, you have to set up JPA instead I think. This is the kind of thing where maybe I've gotten it working, but I would rather someone with more experience with the project do the documentation for how it's supposed to be set up for each use case. I just don't have the domain knowledge of how it's supposed to be used. Here's an example of what I ended up with. FYI my team prefers native SQL over JPA because many of our queries have a lot of joins, even though this example is simpler.

@JdbcRepository(dialect = Dialect.POSTGRES)
interface PostgresAmendmentDao : GenericRepository<AmendmentRequest, Long> {
    @Query("""
        SELECT *,
            fk_bulk_amendment as bulk_amendment_id,
            fk_response_id as response_id,
            fk_waiver_id as waiver_id
        FROM assessment.amendment_request 
        WHERE id in (:ids)
    """, nativeQuery = true)
    fun getAmendmentRequests(ids: List<Long>): List<AmendmentRequest>
}

[graemerocher]

we have many good guides on the topic with associated sample code like https://guides.micronaut.io/latest/micronaut-data-jdbc-repository.html and https://guides.micronaut.io/latest/micronaut-data-one-to-many.html perhaps links to those would have helped

[distinctdan]

So I've read the guides, but unfortunately there are a couple of problems with using the guides as documentation:

• The guides still don't tell you what dependencies you need to install, or provide any commentary on why you would choose one set of dependencies over another. Telling users to create a new project isn't a good practice because then you have to go and reverse engineer the new project to see what's different in that variation vs the base framework, and you don't have any guidance on why it was configured that way. Dependencies should be clearly stated on the main documentation page.
• Guides aren't discoverable from the main docs. Most libraries have a single package to install. Even complex frameworks like Jetpack Compose have a clear list of packages you can add and comments explaining what each package does.

I would ask that the micronaut-data developers figure out which packages are required, and which are optional. Then, place that information in a dependencies list at the beginning of the docs. If there are multiple routes a user can take, clearly state that they must pick 1, and clearly list the dependencies for that route. Here are the Compose docs as an example, I think it would be good if the micronaut docs were more like this for the installation instructions: https://developer.android.com/develop/ui/compose/setup