refactor(persistence-jpa): runbook SQL 리더 이름을 RunbookSql로 바꾼다

문제 (재리뷰 round8 RR8-03-03)
- runbook에서 runbook-sql 블록을 읽는 IT 도우미의 이름이
  OutboxRunbookSql이다. round7 수정 뒤로 마이그레이션 runbook
  (migration-failed.md)도 이 클래스로 읽는다. 다음 runbook의 SQL을 lane으로
  돌리려는 사람이 이름을 보고 공용 리더를 찾지 못해 사본을 만들 수 있다.

고른 방법
- 리뷰 권장안대로 RunbookSql로 이름을 바꾸고 사용처 세 클래스(같은
  postgresqlIntegrationTest source set)를 따라 고친다. 클래스 Javadoc에
  모든 runbook lane이 이 리더 하나를 쓴다고 적는다. 동작은 바꾸지 않는다.

위험·한계
- 같은 source set 안의 package-private 클래스라 밖에서 쓰는 곳이 없다.
  리뷰 기록(docs/reviews/**)의 옛 이름은 그때의 기록이라 두었다.
- RED 없음 — 이름 문제다. 사용처 lane 셋이 그대로 통과하는 것으로 본다.

검증 (desktop, 이 커밋의 트리 328f6012, --no-build-cache, 로그 ~/r9-g3-logs/)
- :adapter:outbound:persistence-jpa:check rc=0, test 666건 실패·skip 0
- postgresqlConcurrentIndexMigrationIntegrationTest rc=0, 7건
- postgresqlOutboxOrderKeyRunbookIntegrationTest rc=0, 10건
- postgresqlOutboxDispositionRunbookIntegrationTest rc=0, 8건
- 네 명령 모두 FROM-CACHE 0, 테스트 태스크 실행됨(UP-TO-DATE 아님)

Refs: docs/reviews/2026-11-03-rereview/round8/03-migration.md RR8-03-03
Fixes: 6ec0c4f7fa ("fix(migration): 실패한 동시 인덱스 마이그레이션 복구와 검사기 설명을 실제 동작에 맞춘다")
This commit is contained in:
DongHyeonka
2026-11-07 08:07:42 +09:00
parent 3eb3b06755
commit e3ebc25ef4
4 changed files with 15 additions and 13 deletions
@@ -206,7 +206,7 @@ class PostgreSqlConcurrentIndexMigrationIntegrationTest {
"실패한 동시 인덱스 마이그레이션은 runbook 절차(빌드 확인, 무효 인덱스 삭제, 원인 정리, 그 버전의 실패 이력 행 삭제) 뒤 다시 배포하면 적용된다")
void aFailedConcurrentIndexMigrationIsRecoveredByTheRunbookProcedure(@TempDir Path stream)
throws Exception {
OutboxRunbookSql runbook = OutboxRunbookSql.fromSystemProperty(MIGRATION_FAILED_RUNBOOK);
RunbookSql runbook = RunbookSql.fromSystemProperty(MIGRATION_FAILED_RUNBOOK);
try (HikariDataSource database = postgres.createDatabase(databaseName())) {
// given
Files.writeString(stream.resolve("V1__probe.sql"), FIRST_RELEASE + DUPLICATE_NOTE);
@@ -41,13 +41,13 @@ class PostgreSqlOutboxDispositionRunbookIntegrationTest {
private static final Duration IN_FLIGHT_TIMEOUT = Duration.ofMinutes(5);
private static PostgreSqlReadinessSupport postgres;
private static OutboxRunbookSql deadLetterRunbook;
private static OutboxRunbookSql publishFailedRunbook;
private static RunbookSql deadLetterRunbook;
private static RunbookSql publishFailedRunbook;
@BeforeAll
static void setup() throws IOException {
deadLetterRunbook = OutboxRunbookSql.fromSystemProperty("outbox.runbook");
publishFailedRunbook = OutboxRunbookSql.fromSystemProperty("outbox.publish-failed.runbook");
deadLetterRunbook = RunbookSql.fromSystemProperty("outbox.runbook");
publishFailedRunbook = RunbookSql.fromSystemProperty("outbox.publish-failed.runbook");
postgres = PostgreSqlReadinessSupport.start();
}
@@ -47,13 +47,13 @@ class PostgreSqlOutboxOrderKeyRunbookIntegrationTest {
private static final Instant OCCURRED = Instant.parse("2026-11-01T00:00:00Z");
private static PostgreSqlReadinessSupport postgres;
private static OutboxRunbookSql runbook;
private static RunbookSql runbook;
private static String duplicateCheck;
private static String removePublishedDuplicates;
@BeforeAll
static void setup() throws IOException {
runbook = OutboxRunbookSql.fromSystemProperty("outbox.runbook");
runbook = RunbookSql.fromSystemProperty("outbox.runbook");
duplicateCheck = runbook.block("v21-duplicate-order-keys");
removePublishedDuplicates = runbook.block("v21-remove-published-duplicates");
postgres = PostgreSqlReadinessSupport.start();
@@ -7,19 +7,21 @@ import java.nio.file.Path;
import java.util.Map;
/**
* The SQL a runbook gives an operator, read out of the runbook itself: the outbox runbooks, and the
* migration runbook's recovery of a failed concurrent index migration.
* The SQL a runbook gives an operator, read out of the runbook itself. Every lane that runs a
* runbook's SQL reads it through this one class: so far the outbox runbooks and the migration
* runbook's recovery of a failed concurrent index migration (re-review 2026-11-03 round 8,
* RR8-03-03: the class kept an outbox name after the migration runbook began to use it).
*
* <p>A runbook block is marked {@code <!-- runbook-sql: id -->} and followed by a {@code sql}
* fence. The lanes that run these blocks against real PostgreSQL read them from the document rather
* than keep a copy, so editing a block in the runbook is what the lane tests: a copy would pass
* while the document an operator follows is wrong.
*/
final class OutboxRunbookSql {
final class RunbookSql {
private final String runbook;
private OutboxRunbookSql(String runbook) {
private RunbookSql(String runbook) {
this.runbook = runbook;
}
@@ -30,13 +32,13 @@ final class OutboxRunbookSql {
* @return the runbook's SQL blocks
* @throws IOException when the file cannot be read
*/
static OutboxRunbookSql fromSystemProperty(String property) throws IOException {
static RunbookSql fromSystemProperty(String property) throws IOException {
String path = System.getProperty(property);
if (path == null || path.isBlank()) {
throw new IllegalStateException(
"system property " + property + " must name the runbook this lane runs");
}
return new OutboxRunbookSql(Files.readString(Path.of(path), StandardCharsets.UTF_8));
return new RunbookSql(Files.readString(Path.of(path), StandardCharsets.UTF_8));
}
/**