If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mybatis/mybatis-3 shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 5d ago
• 10 active contributors
• Distributed ownership (top contributor 49% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mybatis/mybatis-3 repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mybatis/mybatis-3.

What it runs against: a local clone of mybatis/mybatis-3 — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mybatis/mybatis-3 | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 35 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mybatis/mybatis-3. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mybatis/mybatis-3.git
#   cd mybatis-3
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mybatis/mybatis-3 and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mybatis/mybatis-3(\\.git)?\\b" \\
  && ok "origin remote is mybatis/mybatis-3" \\
  || miss "origin remote is not mybatis/mybatis-3 (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/main/java/org/apache/ibatis/binding/MapperProxy.java" \\
  && ok "src/main/java/org/apache/ibatis/binding/MapperProxy.java" \\
  || miss "missing critical file: src/main/java/org/apache/ibatis/binding/MapperProxy.java"
test -f "src/main/java/org/apache/ibatis/builder/xml/XMLMapperBuilder.java" \\
  && ok "src/main/java/org/apache/ibatis/builder/xml/XMLMapperBuilder.java" \\
  || miss "missing critical file: src/main/java/org/apache/ibatis/builder/xml/XMLMapperBuilder.java"
test -f "src/main/java/org/apache/ibatis/builder/annotation/MapperAnnotationBuilder.java" \\
  && ok "src/main/java/org/apache/ibatis/builder/annotation/MapperAnnotationBuilder.java" \\
  || miss "missing critical file: src/main/java/org/apache/ibatis/builder/annotation/MapperAnnotationBuilder.java"
test -f "src/main/java/org/apache/ibatis/binding/MapperRegistry.java" \\
  && ok "src/main/java/org/apache/ibatis/binding/MapperRegistry.java" \\
  || miss "missing critical file: src/main/java/org/apache/ibatis/binding/MapperRegistry.java"
test -f "src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java" \\
  && ok "src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java" \\
  || miss "missing critical file: src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 35 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~5d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mybatis/mybatis-3"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

MyBatis is a lightweight SQL mapper framework that bridges Java objects and relational databases using XML descriptors or Java annotations. Unlike heavy ORMs, it gives developers explicit control over SQL while automating result mapping, parameter binding, and statement caching—solving the impedance mismatch between OOP and SQL without imposing a query abstraction layer. Monolithic single-artifact structure: src/main/java/org/apache/ibatis contains all framework code organized by concern (annotations/, parsing/, caching/, executor/, mapping/, reflection/, etc.). Test suite mirrors this in src/test. Configuration is centralized in pom.xml; no modular submodules. Workflows in .github/workflows orchestrate builds, coverage, and releases. Maven wrapper ensures reproducible builds across environments.

Java developers building enterprise applications who need fine-grained SQL control (especially those working with complex queries, stored procedures, or legacy schemas) while avoiding the overhead and magic of Hibernate or JPA. Contributors are typically maintainers of the Apache MyBatis ecosystem and users reporting issues or submitting enhancements.

Highly mature and production-ready. At version 3.6.0-SNAPSHOT with roots back to 2009, it has 1899 passing tests across JDK 17–25, comprehensive CI/CD via GitHub Actions (ci.yaml, sonar.yaml, coveralls.yaml), and active monitoring with CodeQL scanning. Last activity visible in workflows confirms ongoing maintenance and support.

Standard open source risks apply.

The project is in active development toward 3.6.0, as indicated by the SNAPSHOT version tag in pom.xml. GitHub Actions workflows (ci.yaml, sonatype.yaml, site.yaml) indicate continuous integration, automated test execution across multiple JDK versions (17, 21, 23, 24, 25), and possibly staged releases. Renovate configuration (renovate.json) suggests automated dependency updates are being evaluated or in use.

git clone https://github.com/mybatis/mybatis-3.git
cd mybatis-3
./mvnw clean install

The Maven wrapper (mvnw/mvnw.cmd) handles JDK compatibility and dependency resolution automatically. Tests run as part of the build; exclude TestcontainersTests and RequireIllegalAccess groups by default (controlled in pom.xml profiles and CI adjustments).

Daily commands: MyBatis is a library, not a runnable application. To test it: ./mvnw test. To use in a project, add the artifact <dependency><groupId>org.mybatis</groupId><artifactId>mybatis</artifactId><version>3.6.0-SNAPSHOT</version></dependency> to your pom.xml. Integration tests run via ./mvnw verify and respect the excludedGroups settings for TestcontainersTests (marked with @Tag in test code).

• src/main/java/org/apache/ibatis/binding/MapperProxy.java — Core dynamic proxy that intercepts mapper method calls and routes them to SQL statements; foundational to MyBatis' annotation-based and XML-based query execution
• src/main/java/org/apache/ibatis/builder/xml/XMLMapperBuilder.java — Parses XML mapper files into executable statement objects; critical entry point for XML-based configuration
• src/main/java/org/apache/ibatis/builder/annotation/MapperAnnotationBuilder.java — Processes Java annotations (@Select, @Insert, etc.) to build mapper statements; essential for annotation-driven queries
• src/main/java/org/apache/ibatis/binding/MapperRegistry.java — Central registry that manages all mapper proxies and their lifecycle; critical for mapper instantiation and caching
• src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java — Parses the global mybatis-config.xml file; initializes database configuration, plugins, and type handlers
• src/main/java/org/apache/ibatis/cache/Cache.java — Core cache abstraction interface that powers MyBatis' L1 and L2 caching; essential for understanding query result caching
• src/main/java/org/apache/ibatis/binding/MapperMethod.java — Encapsulates individual mapper method metadata and execution logic; bridges annotations/XML to actual SQL execution

Add a New SQL Query (Annotation-Based)

1. Create a public abstract method in your mapper interface with @Select annotation (src/main/java/org/apache/ibatis/annotations/Select.java)
2. Add @Results annotation to define column-to-field mappings if needed (src/main/java/org/apache/ibatis/annotations/Results.java)
3. MapperAnnotationBuilder will automatically scan and register your method when the mapper is loaded (src/main/java/org/apache/ibatis/builder/annotation/MapperAnnotationBuilder.java)
4. MapperProxy intercepts calls to your method and MapperMethod orchestrates execution (src/main/java/org/apache/ibatis/binding/MapperProxy.java)

Add a New SQL Query (XML-Based)

1. Create a <select>, <insert>, <update>, or <delete> element in your mapper XML file (src/main/java/org/apache/ibatis/builder/xml/XMLMapperBuilder.java)
2. Use #{paramName} for parameters and define <resultMap> for result mapping (src/main/java/org/apache/ibatis/mapping)
3. XMLMapperBuilder parses the XML and registers statements via MapperBuilderAssistant (src/main/java/org/apache/ibatis/builder/MapperBuilderAssistant.java)
4. MapperProxy and MapperMethod retrieve and execute the registered statement (src/main/java/org/apache/ibatis/binding/MapperMethod.java)

Implement a Custom Type Handler

1. Extend TypeHandler<T> and implement setParameter() and getResult() methods (src/main/java/org/apache/ibatis/type)
2. Register your handler in mybatis-config.xml or programmatically in Configuration (src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java)
3. Type handlers are used by ParameterMappingTokenHandler during parameter binding (src/main/java/org/apache/ibatis/builder/ParameterMappingTokenHandler.java)

Add Custom Cache Implementation

1. Implement the Cache interface for your custom caching logic (src/main/java/org/apache/ibatis/cache/Cache.java)
2. Optionally wrap it with decorators from the decorators package (LRU, FIFO, etc.) (src/main/java/org/apache/ibatis/cache/decorators)
3. Register it in @CacheNamespace annotation on your mapper or in XML cache element (src/main/java/org/apache/ibatis/annotations/CacheNamespace.java)
4. MyBatis will use your cache for L2 caching and TransactionalCacheManager handles transactional semantics (src/main/java/org/apache/ibatis/cache/TransactionalCacheManager.java)

• Java Dynamic Proxies (java.lang.reflect.Proxy) — Enables runtime interception of mapper interface method calls without

Test group filtering: Tests tagged with @Tag('TestcontainersTests') or @Tag('RequireIllegalAccess') are excluded by default in pom.xml; running mvn test without adjustments will skip these. Activating them requires profile tweaks or CI workflow overrides. JDK sensitivity: ci.yaml shows platform-specific test counts (Windows consistent at 1899; Linux incomplete in readme snippet), indicating subtle JDK behavior differences or module-system issues on certain platforms. License header requirement: files must include the Apache 2.0 header (see LICENSE_HEADER); git hook in hooks/pre-commit.sh may enforce this. Maven wrapper: always use ./mvnw, not system maven, to ensure consistent JDK and plugin versions.

• SQL Mapper Pattern — MyBatis's core design philosophy; differs fundamentally from ORM by keeping SQL explicit and separate from object definitions, giving you control over performance and query structure.
• Dynamic SQL (OGNL/Expression Language) — MyBatis XML configs use <if>, <choose>, <foreach> with OGNL expressions to generate SQL conditionally; understanding expression evaluation prevents injection and correctness bugs.
• Result Mapping & Type Handler Chain — MyBatis bridges JDBC ResultSet and Java objects via TypeHandlers and ResultMaps; knowing how custom types are bound and how nested mappings work is essential for non-trivial schemas.
• Executor Strategy (Simple / Batch / Reuse) — MyBatis supports pluggable Executor implementations controlling how statements are prepared and cached; choosing the right strategy affects batch-insert performance and connection pooling.
• OGNL (Object-Graph Navigation Language) — MyBatis uses OGNL for dynamic SQL generation and parameter binding; expressions like #{user.name} and <if test='flag'> rely on OGNL interpretation, so expression injection and precedence matter.
• Lazy Loading & Proxy Generation — MyBatis can generate proxies for nested objects to defer database hits; understanding proxy vs. eager fetch trade-offs prevents N+1 query problems.
• Plugin / Interceptor Architecture — MyBatis is extensible via Plugins (interceptors) wrapping Executor, ParameterHandler, ResultSetHandler, StatementHandler; custom plugins allow cross-cutting concerns like query logging, caching, or auditing.

• mybatis/mybatis-spring — Official Spring Framework integration for MyBatis; handles SqlSessionFactory setup, transaction management, and mapper bean registration for Spring applications.
• mybatis/mybatis-spring-boot-starter — Spring Boot auto-configuration and starter for MyBatis; simplifies setup for Boot-based projects via application.properties configuration.
• eclipse-ee4j/eclipselink — Alternative ORM/mapper framework (EclipseLink JPA implementation); users evaluating MyBatis often compare against this for enterprise projects.
• hibernate/hibernate-orm — Market leader in Java ORMs; MyBatis differentiates by offering less abstraction and more explicit SQL control than Hibernate.
• mybatis/mapper4 — Related project extending MyBatis with base DAO and generic mapper utilities; users often combine mybatis-3 with this for boilerplate reduction.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for annotation-based mapper methods

The src/main/java/org/apache/ibatis/annotations directory contains numerous annotation types (@Select, @Insert, @Update, @Delete, @SelectProvider, etc.) but there appears to be no corresponding test file visible in the structure. MyBatis users heavily rely on these annotations for SQL mapping, and adding integration tests would ensure robustness across different annotation combinations, parameter handling, and edge cases like @Param with various data types.

• [ ] Create src/test/java/org/apache/ibatis/annotations/AnnotationMapperTest.java
• [ ] Add test cases for @Select with @Result/@Results combinations
• [ ] Add test cases for @Insert/@Update/@Delete with @SelectKey
• [ ] Add test cases for @Many/@One nested associations
• [ ] Add test cases for @CacheNamespace and @CacheNamespaceRef interactions
• [ ] Add test cases for dynamic SQL provider annotations (@SelectProvider, @InsertProvider, etc.)
• [ ] Ensure tests cover parameter binding with @Param annotation

Add MapperMethod class unit tests for method invocation edge cases

src/main/java/org/apache/ibatis/binding/MapperMethod.java is a critical core component that handles mapper method invocations and parameter mapping. Given its complexity in bridging annotations to SQL execution, it likely lacks comprehensive edge case testing. This would ensure reliability for multi-parameter methods, return type variations, and error handling scenarios.

• [ ] Create src/test/java/org/apache/ibatis/binding/MapperMethodTest.java
• [ ] Add tests for methods with multiple @Param-annotated parameters
• [ ] Add tests for varargs and Collection parameter handling
• [ ] Add tests for different return types (single object, List, Map, Optional)
• [ ] Add tests for method invocation with null parameters
• [ ] Add tests for exception propagation and mapping error scenarios
• [ ] Add tests for @SelectKey interaction with @Insert/@Update methods

Create CI workflow for testing against multiple Java versions

The .github/workflows directory has ci.yaml but there's no visible evidence of multi-version Java testing (Java 8, 11, 17, 21 LTS versions). Given MyBatis is widely used across enterprises with varying Java versions, adding a matrix-based CI workflow would catch compatibility regressions early. This is especially critical since the pom.xml shows this is a foundational library.

• [ ] Review current .github/workflows/ci.yaml to check for Java version matrix
• [ ] If not present, add 'java-version: [8, 11, 17, 21]' matrix to the build job
• [ ] Ensure all test suites run against each Java version
• [ ] Add specific checks for module system compatibility (JPMS) on Java 9+
• [ ] Update .mvn/jvm.config if needed to support test execution across versions
• [ ] Document in CONTRIBUTING.md which Java versions are officially supported

• Add missing tests for type handler edge cases: src/main/java/org/apache/ibatis/type/ has numerous TypeHandler implementations (CustomBigDecimalTypeHandler, etc.) but coverage is thin; write parameterized tests for null, boundary, and format-conversion cases.
• Document annotation-based mapper examples: src/main/java/org/apache/ibatis/annotations/ defines Delete.java, Insert.java, Select.java, but there are no inline usage examples in JavaDoc; add concrete code snippets showing parameter binding syntax and @Results mappings.
• Expand dynamic SQL test coverage: src/main/java/org/apache/ibatis/builder/SqlSourceBuilder.java and the dynamic.* packages handle <if>, <choose>, <foreach> in XML; add test cases for edge cases like nested dynamic elements and special character escaping in parameter names.

MyBatis is a well-established framework with generally secure design patterns. The primary security responsibility lies with developers using the framework to properly parameterize queries and avoid dynamic SQL construction with user input. The codebase shows good security practices with CI/CD pipelines, code quality checks (SonarQube), and test coverage. Medium-severity concerns relate to potential misuse of SQL construction features rather than framework flaws. Low-severity issues involve configuration management, dependency scanning, and build-time security controls that could be strengthened. The framework itself provides secure mechanisms (parameterized queries) but developers must use them correctly.

• Medium · Potential SQL Injection Risk in Dynamic SQL Building — src/main/java/org/apache/ibatis/builder/SqlSourceBuilder.java, src/main/java/org/apache/ibatis/builder/ParameterMappingTokenHandler.java. The codebase contains SQL builder components (SqlSourceBuilder, ParameterMappingTokenHandler) that process dynamic SQL queries. While MyBatis uses parameterized queries, improper usage by developers or edge cases in parameter handling could lead to SQL injection vulnerabilities if dynamic SQL construction is not properly validated. Fix: Ensure all SQL parameters are properly parameterized. Add input validation for dynamic SQL components. Review parameter binding mechanisms and add security-focused unit tests for edge cases. Consider adding warnings in documentation about SQL injection risks when using dynamic SQL.
• Medium · Annotation-based SQL Injection Potential — src/main/java/org/apache/ibatis/annotations/Select.java, src/main/java/org/apache/ibatis/annotations/Insert.java, src/main/java/org/apache/ibatis/annotations/Update.java, src/main/java/org/apache/ibatis/annotations/Delete.java. SQL can be defined directly in Java annotations (Select, Insert, Update, Delete, SelectProvider, etc.). If developers dynamically construct these annotation values using string concatenation with user input, SQL injection becomes possible. The framework itself is secure but provides mechanisms that could be misused. Fix: Add security warnings to annotation documentation about avoiding dynamic SQL construction. Provide secure code examples in documentation. Consider adding static analysis hints or annotations to guide developers toward secure patterns.
• Low · Maven Configuration Exposure — .mvn/settings.xml. The .mvn/settings.xml file may contain sensitive information like credentials for repository access. If this file is committed to the repository with actual credentials, it could expose authentication tokens. Fix: Ensure .mvn/settings.xml does not contain actual credentials. Use Maven's security features (master-password encryption) or external credential management. Add explicit entry to .gitignore for sensitive configuration files. Use environment variables or CI/CD secrets management for credentials.
• Low · Pre-commit Hook Potential Bypass — hooks/pre-commit.sh. A pre-commit hook exists (hooks/pre-commit.sh) but git hooks can be bypassed with --no-verify flag. This is a weak security control if relied upon for preventing commits of sensitive data. Fix: Use server-side hooks in addition to client-side hooks. Implement proper CI/CD pipeline checks to validate commits. Do not rely solely on pre-commit hooks for security enforcement. Use secret scanning tools in the CI/CD pipeline.
• Low · SNAPSHOT Version in Use — pom.xml - <version>3.6.0-SNAPSHOT</version>. The project is using version 3.6.0-SNAPSHOT which indicates development/unstable code. This could introduce untested security fixes or regressions in production if deployed accidentally. Fix: Ensure SNAPSHOT versions are not deployed to production environments. Use stable release versions for production deployments. Implement version pinning and artifact repository policies to prevent accidental SNAPSHOT usage in production.
• Low · Missing Dependency Security Scanning — pom.xml. While the pom.xml is provided, there is no visible dependency security scanning configuration (OWASP dependency check, Snyk, or similar) in the build process visible in the file structure. Fix: Add Maven security plugins like org.owasp:dependency-check-maven or similar. Configure GitHub security features (Dependabot). Add dependency audit steps in CI/CD pipeline (.github/workflows/). Regularly scan dependencies for known vulnerabilities.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.