Documentation
Lynxus documentation
Section titled “Lynxus documentation”
Lynxus generates ordinary Java Mapper implementations at compile time and executes them through a fixed, explicit JDBC lifecycle. Start with the architecture below, then expand into the chapter that matches your task.
The compiler owns stable decisions—SQL validation, parameter planning, dynamic SQL compilation, and result-shape checks. The generated Mapper then calls SqlExecutor, while JDBC connection, statement, mapping, and cleanup remain visible at runtime.
Why teams choose Lynxus
Section titled “Why teams choose Lynxus”Lynxus keeps the programming model small while moving stable work to compilation. The result is a runtime path that is easier to inspect, test, and operate.
Capability overview
Section titled “Capability overview”| Concern | Lynxus approach | Practical benefit |
|---|---|---|
| SQL validation | Annotation processing and javac diagnostics | Find invalid statements and signatures before deployment |
| Mapper dispatch | Generated Java implementations | No runtime proxy lookup on the request path |
| Type handling | Compile-time parameter and result planning | Fewer surprises from implicit conversions |
| Object mapping | Generated assemblers and typed row mappers | Readable code with explicit construction rules |
| Dynamic SQL | Supported expressions compiled into Java control flow | No runtime expression interpreter is required |
| Extension model | Narrow providers, binders, row mappers, and interceptors | Extend one responsibility without replacing the lifecycle |
| DataSource ownership | One Mapper belongs to one DataSource domain | Routing and transaction boundaries remain unambiguous |
MySQL benchmark snapshot
Section titled “MySQL benchmark snapshot”The following snapshot comes from the reproducible MySQL 8.4 JMH run documented in the benchmark report. Lower is better; values are microseconds per operation on a local container, not a production latency promise.
| Workload | Direct JDBC | Lynxus | MyBatis |
|---|---|---|---|
| Scalar query | 3,511 | 3,362 | 3,563 |
| Record mapping | 3,404 | 3,423 | 3,580 |
| JavaBean mapping | 3,623 | 3,207 | 3,611 |
| Dynamic SQL | 3,370 | 3,499 | 3,758 |
| Cursor, ten rows | 3,307 | 3,644 | 3,988 |
The complete timing table, environment metadata, and reproduction command live in the benchmark report.
Choose your path
Section titled “Choose your path”Build your first Mapper
Section titled “Build your first Mapper”Start with dependencies, annotation processing, a small Mapper, and explicit runtime assembly.
This chapter covers dependencies, annotation processing, a first Mapper, and explicit runtime assembly.
Understand the architecture
Section titled “Understand the architecture”See what moves to javac, what remains at runtime, and how generated code reaches JDBC.
This chapter explains compile-time generation, the generated source boundary, and the fixed JDBC lifecycle.
Integrate with Spring Boot
Section titled “Integrate with Spring Boot”Connect named Mapper packages to DataSource domains and participate in Spring transactions without hiding execution behind a session.
This chapter covers Mapper scanning, package-to-DataSource bindings, transactions, and routing boundaries.
Migrate existing Mappers
Section titled “Migrate existing Mappers”Map supported patterns deliberately, understand compatibility boundaries, and identify cases that need an explicit extension.
This chapter classifies supported patterns, deliberate non-goals, and explicit extension points.
Go deeper
Section titled “Go deeper”How the chapters fit together
Section titled “How the chapters fit together”| Chapter | What you will learn | Best next step |
|---|---|---|
| User guides | Install, model, integrate, and migrate | Start here |
| Core reference | Mapper contracts and JDBC behavior | Read the core contract |
| Extensions | Providers, binders, row mappers, and interceptors | Choose an extension |
| Compatibility | Supported patterns and explicit boundaries | Check the matrix |
Documentation principles
Section titled “Documentation principles”The source repository owns the canonical technical Markdown. This site adds navigation, search, bilingual presentation, stable URLs, and machine-readable indexes for people and AI agents.