ai-instructions: Instructions file for GitHub Copilot

Spring Boot Repository Engine

Naming Conventions

• Name repository interfaces with the *Repository suffix (e.g., HolidayRepository).
• Name repository implementations with the *RepositoryImpl suffix (e.g., HolidayRepositoryImpl).
• Name SQL configuration property records with the *SqlConfigurationProperties suffix (e.g., HolidaySqlConfigurationProperties).
• Use resource entity names in repository identifiers (never DataRepository or PersistenceRepository).
• Name SQL property keys with the pattern sql.<resource>.<operation> (e.g., sql.holidays.find-by-id).
• Name SQL column name constant classes with the *SqlColumns suffix (e.g., UserSqlColumns, AccountSqlColumns).

Rules

• Defer the global ORM ban to spring-boot-architecture.instructions.md.
• Defer ORM dependency bans to spring-boot-pom.instructions.md.
• Use findById, findAll, findBy*, save, update, and deleteById as standard method name prefixes.
• Keep method names consistent with operation semantics across all repositories.
• Keep JDBC or JdbcClient as the default for relational persistence modules.
• Use interface + implementation separation (XyzRepository interface + XyzRepositoryImpl) for modules with multiple persistence adapters or higher domain complexity.
• Use a single @Repository class without a separate interface for focused modules with a single persistence adapter.
• Allow non-relational repository implementations only when the module is explicitly scoped to an approved non-relational store.
• Declare SQL column name constants in a *SqlColumns utility class within the feature package.
• Use *SqlColumns constants as all named parameter keys in SQL method calls.
• Declare SQL result-set column-label constants in the repository implementation and reuse them for all ResultSet reads.
• Return Optional<T> from all single-resource lookup methods (e.g., findById).
• Keep business orchestration out of repository methods.
• Parameterize all SQL executed by repositories.
• Build SQL parameter containers to be null-tolerant by omitting null entries or binding typed null values explicitly.
• Accept pagination parameters (offset, limit, sort column) as explicit method parameters for paginated queries.
• Keep SQL statements straightforward and readable; prefer simple joins, predicates, and direct projections over expression-heavy control-flow in SQL.
• Implement sortable pagination in SQL only when the user explicitly requires database-side sorting or the expected data volume makes application-side sorting unsuitable.
• When the user prefers simpler SQL and data volume constraints do not require database-side sorting, perform sorting in Java after retrieval using an allowlisted set of sortable fields.
• Externalize SQL statements into @PropertySource-backed XML property files, one file per feature.
• Declare @PropertySource on the @Configuration class that owns the JdbcClient bean.
• Access SQL statements through a @ConfigurationProperties record named XyzSqlConfigurationProperties within the feature package.
• Register XyzSqlConfigurationProperties using one explicit pattern: either @Component + @ConfigurationProperties on the record, or @EnableConfigurationProperties on the owning @Configuration class.
• Annotate *SqlConfigurationProperties records with @Validated and annotate each SQL field with @NotBlank.
• Validate generated-key fallback results explicitly and throw a deterministic data-retrieval exception when no key is returned.
• Use Locale.ROOT for case normalization in machine-parsed string comparisons (e.g., SQL error-message feature detection).
• Catch SQL exceptions at the repository boundary and wrap them in a feature-scoped exception; services must not re-wrap the same SQL failure.
• Fall back from INSERT/UPDATE ... RETURNING only when exception evidence indicates the database does not support RETURNING.
• Rethrow unrelated SQL grammar errors.