You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
v0.3.0: BUILTIN schema management is the new default
v0.2.0 made schema management opt-in (default NONE) which forced users without
Flyway/Liquibase to copy DDL manually before their first run. That was poor UX
for the most common case.
v0.3.0 flips the default to BUILTIN — the starter runs CREATE TABLE IF NOT EXISTS
on every startup via Spring Boot's DataSourceScriptDatabaseInitializer. The SQL
is idempotent (IF NOT EXISTS clauses), so re-running on every boot is a no-op
once the table exists.
Three strategies now:
- BUILTIN (default) — starter creates the table; no migration tool needed
- FLYWAY — appends classpath:db/api-log to spring.flyway.locations
- NONE — starter does not touch the schema; consumer applies the DDL
Implementation:
- ApiLogProperties.Schema.Management: BUILTIN, FLYWAY, NONE (default BUILTIN)
- ApiLogSchemaInitializer extends DataSourceScriptDatabaseInitializer so
JpaBaseConfiguration auto-DependsOn it — the EntityManagerFactory waits for
schema creation before validating entities (avoids ddl-auto=validate failure
on fresh DBs).
- V1.0__create_api_log.sql: added IF NOT EXISTS to CREATE TABLE and CREATE INDEX
statements. Flyway is fine with this (it tracks migrations by version, not
by SQL effect).
Tests pinned to schema.management=builtin in src/test/resources/application.properties.
Docs (installation, quickstart, configuration ref, schema ref, changelog) updated
to lead with BUILTIN; FLYWAY and NONE are documented as alternatives for teams
with specific schema-management policies.
Breaking from v0.2.0 only for users who relied on the v0.2.0 NONE default; full
migration notes in docs/changelog.md.
Copy file name to clipboardExpand all lines: CHANGELOG.md
+11-1Lines changed: 11 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,6 +7,15 @@ The source of truth for the entries below is [docs/changelog.md](docs/changelog.
7
7
8
8
## [Unreleased]
9
9
10
+
## [0.3.0] — BUILTIN schema management is the new default
11
+
12
+
### Changed
13
+
14
+
-**`BUILTIN` is now the default for `api.log.schema.management`.** The starter runs `CREATE TABLE IF NOT EXISTS` on startup via Spring Boot's `DataSourceScriptDatabaseInitializer` — no migration tool needed. Flips v0.2.0's `NONE` default which left first-time users with a missing table.
15
+
-`V1.0__create_api_log.sql` now uses `IF NOT EXISTS` clauses, idempotent and safe to re-run on every boot.
16
+
17
+
Three strategies now: `builtin` (default), `flyway`, `none`. See [docs/changelog.md](docs/changelog.md#030--builtin-schema-management-is-the-new-default) for the full v0.2.0 migration guide.
18
+
10
19
## [0.2.0] — Schema management opt-in
11
20
12
21
### Changed
@@ -23,6 +32,7 @@ See [docs/changelog.md](docs/changelog.md#020--schema-management-opt-in) for the
23
32
24
33
First public release. See [docs/changelog.md](docs/changelog.md#010--initial-release) for details.
enabled: true # default — set to false to disable the whole infrastructure
92
92
schema:
93
-
management: none # default — see "Schema" below
93
+
management: builtin# default — see "Schema" below
94
94
```
95
95
96
96
You bring your own:
97
97
98
98
- `DataSource` pointing at a PostgreSQL database
99
99
- `ObjectMapper`bean (Spring Boot's auto-config is fine)
100
-
- Either the `api_log` table created via your own migration tool, OR the bundled Flyway migration (opt in below)
100
+
101
+
The `api_log` table is created for you on first boot — no other setup needed.
101
102
102
103
### Schema
103
104
104
-
The `api_log` table is **not** created automatically. Two options:
105
+
`api.log.schema.management` selects how the `api_log` table is provisioned:
105
106
106
-
1. **Apply the DDL yourself** (default, recommended for production) — see the [Schema reference](https://api-log.devslab.kr/reference/schema/) for the SQL, then put it in your own Flyway/Liquibase/manual flow.
107
-
2. **Opt in to the bundled migration** — add Flyway to your dependencies and set `api.log.schema.management=flyway`. The starter then appends `classpath:db/api-log` to your Flyway locations.
107
+
- **`builtin`** (default) — the starter runs `CREATE TABLE IF NOT EXISTS` on startup. Idempotent, requires no migration tool. Just works.
108
+
- **`flyway`** — register with the consumer's Flyway flow (`flyway_schema_history` tracks the migration). Requires `flyway-core` on the classpath.
109
+
- **`none`** — the starter does not touch the schema. Apply the DDL yourself via Liquibase / manual `psql` / your own flow. See the [Schema reference](https://api-log.devslab.kr/reference/schema/) for the SQL.
108
110
109
111
Full installation guide: [api-log.devslab.kr/getting-started/installation](https://api-log.devslab.kr/getting-started/installation/).
Copy file name to clipboardExpand all lines: docs/changelog.ko.md
+21-1Lines changed: 21 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,6 +6,25 @@
6
6
7
7
## [Unreleased]
8
8
9
+
## [0.3.0] — BUILTIN 스키마 관리가 새 기본값
10
+
11
+
### Changed
12
+
13
+
-**BUILTIN이 새 기본 스키마 관리 전략.** v0.2.0이 스키마 관리를 옵트인(`NONE` 기본)으로 만들었지만, Flyway/Liquibase 안 쓰는 사용자는 첫 부팅에서 "테이블 없음" 에러를 봐야 했습니다. v0.3.0은 기본값을 `BUILTIN`으로 뒤집어 — 스타터가 Spring Boot의 `DataSourceScriptDatabaseInitializer`로 `CREATE TABLE IF NOT EXISTS`를 자동 실행. 테이블이 그냥 존재합니다.
14
+
-`V1.0__create_api_log.sql`이 `IF NOT EXISTS` 절을 사용해 멱등적 — 매 부팅마다 안전하게 재실행 가능. Flyway도 문제 없음 (`flyway_schema_history` 행이 핵심, SQL 결과가 아님).
15
+
16
+
### 전략 정리 (v0.3.0 이후)
17
+
18
+
-`api.log.schema.management=builtin` (기본) — 스타터가 부팅 시 테이블 생성
19
+
-`api.log.schema.management=flyway` — 스타터가 `FlywayConfigurationCustomizer` 등록 (Flyway 의존성 필요)
20
+
-`api.log.schema.management=none` — 스타터가 스키마에 손 안 댐; 사용자가 직접 DDL 적용
21
+
22
+
### v0.2.0에서 마이그레이션
23
+
24
+
-**`management=flyway` 명시한 경우:** 변경 불필요.
25
+
-**`management=none` 명시한 경우:** 변경 불필요.
26
+
-**`management`를 설정 안 한 경우 (v0.2.0 기본 NONE에 의존, 다른 곳에서 DDL 적용 중):**`management=none`을 명시해서 기존 동작 유지하거나, BUILTIN이 동작하도록 그대로 두기 (멱등적이라 기존 테이블과 충돌 없음).
27
+
9
28
## [0.2.0] — 스키마 관리 옵트인
10
29
11
30
### Changed
@@ -62,6 +81,7 @@ v0.1.0의 자동 마이그레이션에 의존하고 있었다면:
62
81
-`ApiLogAutoConfiguration`을 통한 자동 구성, `@ConditionalOnMissingBean` 오버라이드.
Copy file name to clipboardExpand all lines: docs/changelog.md
+21-1Lines changed: 21 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,6 +6,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
6
6
7
7
## [Unreleased]
8
8
9
+
## [0.3.0] — BUILTIN schema management is the new default
10
+
11
+
### Changed
12
+
13
+
-**BUILTIN is now the default schema management strategy.** v0.2.0 made schema management opt-in with `NONE` as the default, but that left users without Flyway/Liquibase staring at a "table doesn't exist" error on first boot. v0.3.0 flips the default to `BUILTIN` — the starter runs `CREATE TABLE IF NOT EXISTS` automatically via Spring Boot's `DataSourceScriptDatabaseInitializer`, so the table just exists.
14
+
-`V1.0__create_api_log.sql` now uses `IF NOT EXISTS` clauses, making it idempotent and safe to re-run on every boot. Flyway is fine with this; the version row in `flyway_schema_history` is what matters, not whether the SQL did anything.
15
+
16
+
### Strategy summary (after v0.3.0)
17
+
18
+
-`api.log.schema.management=builtin` (default) — starter creates the table on startup
19
+
-`api.log.schema.management=flyway` — starter registers a `FlywayConfigurationCustomizer` (requires Flyway on classpath)
20
+
-`api.log.schema.management=none` — starter does not touch the schema; you apply the DDL yourself
21
+
22
+
### Migration from v0.2.0
23
+
24
+
-**You had `management=flyway` set explicitly:** no change needed.
25
+
-**You had `management=none` set explicitly:** no change needed.
26
+
-**You did not set `management` (relying on the v0.2.0 default `NONE` and applying the DDL elsewhere):** either set `management=none` explicitly to preserve old behavior, or let BUILTIN take over (it's idempotent, so it won't fight your existing table).
27
+
9
28
## [0.2.0] — Schema management opt-in
10
29
11
30
### Changed
@@ -62,6 +81,7 @@ First public release. Repackaged as a standalone Spring Boot starter.
62
81
- Auto-configuration via `ApiLogAutoConfiguration` with `@ConditionalOnMissingBean` overrides.
63
82
- 31 tests including PostgreSQL integration via Testcontainers.
-**PostgreSQL `DataSource`** — 스타터가 DB 접속 정보를 만들어주지는 않습니다
75
53
-**`ObjectMapper` 빈** — Spring Boot 자동 구성으로 충분
76
-
-`api_log` 테이블 생성 방법 — DDL을 직접 적용하거나, 번들 Flyway 마이그레이션을 옵트인 (아래)
54
+
55
+
여기까지. 기본 설정이면 `api_log` 테이블은 첫 부팅에 자동 생성됩니다.
77
56
78
57
```yaml title="application.yml"
79
58
spring:
@@ -85,11 +64,12 @@ spring:
85
64
virtual:
86
65
enabled: true # Java 21+ 권장
87
66
67
+
# 둘 다 합리적인 기본값 — 비기본 동작이 필요할 때만 명시.
88
68
api:
89
69
log:
90
70
enabled: true # 기본값 — false면 전체 인프라 비활성화
91
71
schema:
92
-
management: none # 기본값 — 아래 "스키마 관리" 참고
72
+
management: builtin# 기본값 — 아래 "스키마 관리" 참고
93
73
```
94
74
95
75
## 자동 구성이 하는 일
@@ -99,28 +79,40 @@ api:
99
79
- `ApiLogService`— 영속화 오케스트레이터 (`ObjectMapper` 빈이 있어야 활성화)
100
80
- `ApiEventListener`— 이벤트를 서비스로 연결하는 `@EventListener` (async)
101
81
- `RetryConfig`— Spring Retry 통합을 위한 `@EnableRetry` 활성화
82
+
- `ApiLogSchemaInitializer`— 부팅 시 `CREATE TABLE IF NOT EXISTS` 실행 (`schema.management=builtin` 활성화 시, 즉 기본값)
102
83
- JPA `@EntityScan` 및 `@EnableJpaRepositories` (`kr.devslab.apilog.model`, `kr.devslab.apilog.repository`)
103
84
104
85
모든 빈은 `@ConditionalOnMissingBean`. 직접 빈을 정의하면 오버라이드됩니다.
105
86
106
87
## 스키마 관리 { #schema-management }
107
88
108
-
`api_log` 테이블은 **자동으로 생성되지 않습니다.** `api.log.schema.management`로 어떻게 만들지 선택합니다:
89
+
`api.log.schema.management`로 `api_log` 테이블 생성 방식 선택:
109
90
110
-
=== "NONE (기본) — DDL 직접 적용"
91
+
=== "BUILTIN (기본) — 스타터가 처리"
111
92
112
-
[스키마 레퍼런스](../reference/schema.md)의 SQL을 다음 중 하나에 넣으세요:
93
+
매 부팅마다 스타터가 번들된 `V1.0__create_api_log.sql`을 사용자의 `DataSource`에 실행합니다. DDL이 `CREATE TABLE IF NOT EXISTS` / `CREATE INDEX IF NOT EXISTS`이라 멱등적 — 테이블이 이미 있으면 매번 no-op.
113
94
114
-
- 본인 프로젝트의 Flyway 마이그레이션, 또는
115
-
- 본인 프로젝트의 Liquibase changelog, 또는
116
-
- 배포 시 수동 `psql` 실행, 또는
117
-
- 본인이 이미 쓰고 있는 스키마 관리 흐름
95
+
추가 의존성 없음. 외부 마이그레이션 도구 없음. 그냥 동작.
118
96
119
-
**기본값**입니다 — 운영 환경 대부분은 이미 마이그레이션을 관리하고 있고, 서드파티 라이브러리가 자기 마음대로 스키마에 손대는 걸 원하지 않기 때문입니다.
97
+
Spring Boot의 [`DataSourceScriptDatabaseInitializer`](https://docs.spring.io/spring-boot/api/java/org/springframework/boot/jdbc/init/DataSourceScriptDatabaseInitializer.html)를 통해 적용되므로 JPA 엔티티 검증보다 먼저 실행 — 빈 DB에서 Hibernate `ddl-auto=validate`가 실패하지 않음.
0 commit comments