v0.2.0: Make schema management opt-in

Schema management for the api_log table is now opt-in via api.log.schema.management
(default: NONE). Previously the starter force-installed Flyway and auto-applied the
bundled migration, which broke consumers who:
  - already had the table managed elsewhere (Liquibase, manual DDL),
  - had a name collision in classpath:db/migration/,
  - didn't want Flyway at all.

Changes:
- ApiLogProperties.Schema.Management enum (NONE, FLYWAY) under api.log.schema.management
- ApiLogFlywayConfig: registers a FlywayConfigurationCustomizer when
  schema.management=flyway and Flyway is on the classpath; appends
  classpath:db/api-log to spring.flyway.locations (additive, doesn't replace).
- pom.xml: flyway-core / flyway-database-postgresql now <optional>true</optional>
- Migration relocated: classpath:db/migration/ → classpath:db/api-log/
- Tests opt in via src/test/resources/application.properties

Docs updated:
- Installation: explains the NONE | FLYWAY choice and the optional Flyway dep
- Quickstart: explicitly sets schema.management=flyway with Flyway dep instructions
- Configuration reference: new property documented
- Schema reference: clarifies "not auto-created by default"
- Changelog: 0.2.0 entry with v0.1.0 migration guide

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jlc488

CHANGELOG.md

@@ -7,29 +7,22 @@ The source of truth for the entries below is [docs/changelog.md](docs/changelog.
 
 ## [Unreleased]
 
-### Changed
-
-- **Restructured as standalone Spring Boot Starter library.**
-    - `groupId`: `com.devs.lab` → `kr.devslab`
-    - `artifactId`: `api-log-starter` → `api-log-spring-boot-starter`
-    - Java package: `com.devs.lab.test.*` → `kr.devslab.apilog.*`
-- Removed demo application (`ApiLogApplication`, `compose.yaml`, `Dockerfile.postgres`) — pure library now
-- Removed app-only dependencies: `spring-boot-devtools`, `spring-boot-docker-compose`, `spring-boot-starter-actuator`
+## [0.2.0] — Schema management opt-in
 
-### Fixed
-
-- Flyway migration path: `db.migration/` → `db/migration/` (the dot version wasn't a standard Flyway location and never auto-applied)
+### Changed
 
-### Added
+- **BREAKING: schema management is now opt-in.** v0.1.0 force-installed Flyway and auto-ran the bundled migration. v0.2.0 makes the consumer choose:
+    - `api.log.schema.management=none` (default) — apply the DDL yourself
+    - `api.log.schema.management=flyway` — starter customizes Flyway to include its location
+- `flyway-core` / `flyway-database-postgresql` now `<optional>true</optional>` — consumers using `management=flyway` must declare Flyway themselves.
+- Migration moved: `classpath:db/migration/` → `classpath:db/api-log/` (avoids collision with consumer's default Flyway location).
 
-- `LICENSE` (Apache 2.0) + `NOTICE`
-- Full `pom.xml` metadata for Maven Central publishing
-- Bilingual README (English default + `README.ko.md`)
-- Full documentation site at [api-log.devslab.kr](https://api-log.devslab.kr)
+See [docs/changelog.md](docs/changelog.md#020--schema-management-opt-in) for the full migration guide from v0.1.0.
 
 ## [0.1.0] — Initial release
 
 First public release. See [docs/changelog.md](docs/changelog.md#010--initial-release) for details.
 
-[Unreleased]: https://github.com/devslab-kr/api-log/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/devslab-kr/api-log/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/devslab-kr/api-log/releases/tag/v0.2.0
 [0.1.0]: https://github.com/devslab-kr/api-log/releases/tag/v0.1.0

README.ko.md

@@ -165,7 +165,7 @@ CompletableFuture<ApiResponse> future = restApiClient.postAsync("/api/users", us
 <dependency>
     <groupId>kr.devslab</groupId>
     <artifactId>api-log-spring-boot-starter</artifactId>
-    <version>0.1.0-SNAPSHOT</version>
+    <version>0.2.0</version>
 </dependency>
 ```
 
@@ -222,11 +222,26 @@ spring:
   threads:
     virtual:
       enabled: true   # 권장 (Java 21+)
+
+api:
+  log:
+    enabled: true              # 기본값 — false면 전체 인프라 비활성화
+    schema:
+      management: none         # 기본값 — 아래 "스키마 관리" 참고
 ```
 
 - **PostgreSQL DataSource** (JSONB 컬럼 사용 위해 필수)
 - **ObjectMapper** Bean (Spring Boot 기본 구성으로 충분)
-- 스타터에 포함된 Flyway 마이그레이션 `V1.0__create_api_log.sql`이 자동 적용됨
+- `api_log` 테이블 생성 방법 — DDL을 직접 적용하거나, 번들 Flyway 마이그레이션을 옵트인
+
+### 스키마 관리 (v0.2.0 변경)
+
+`api_log` 테이블은 **자동으로 생성되지 않습니다.** 두 가지 옵션:
+
+1. **DDL 직접 적용** (기본값, 운영 권장) — [스키마 레퍼런스](https://api-log.devslab.kr/ko/reference/schema/) 참고. 본인 Flyway/Liquibase/수동 흐름에 SQL을 넣으세요.
+2. **번들 마이그레이션 옵트인** — Flyway 의존성 추가 + `api.log.schema.management=flyway`. 스타터가 `spring.flyway.locations`에 `classpath:db/api-log` 추가.
+
+전체 설치 가이드: [api-log.devslab.kr/ko/getting-started/installation](https://api-log.devslab.kr/ko/getting-started/installation/).
 
 ## 🧪 테스트
 

README.md

@@ -73,30 +73,40 @@ PostgreSQL  (api_log · JSONB columns)
 <dependency>
     <groupId>kr.devslab</groupId>
     <artifactId>api-log-spring-boot-starter</artifactId>
-    <version>0.1.0-SNAPSHOT</version>
+    <version>0.2.0</version>
 </dependency>
 ```
 
 ### Gradle
 
 ```kotlin
-implementation("kr.devslab:api-log-spring-boot-starter:0.1.0-SNAPSHOT")
+implementation("kr.devslab:api-log-spring-boot-starter:0.2.0")
 ```
 
 ## Configuration
 
 ```yaml
 api:
   log:
-    enabled: true   # default: true
+    enabled: true              # default — set to false to disable the whole infrastructure
+    schema:
+      management: none         # default — see "Schema" below
 ```
 
 You bring your own:
 
 - `DataSource` pointing at a PostgreSQL database
 - `ObjectMapper` bean (Spring Boot's auto-config is fine)
+- Either the `api_log` table created via your own migration tool, OR the bundled Flyway migration (opt in below)
 
-The Flyway migration `V1.0__create_api_log.sql` ships with the starter — Spring Boot will pick it up if Flyway is on the classpath.
+### Schema
+
+The `api_log` table is **not** created automatically. Two options:
+
+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.
+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.
+
+Full installation guide: [api-log.devslab.kr/getting-started/installation](https://api-log.devslab.kr/getting-started/installation/).
 
 ## Using `RestApiClientUtil`
 

docs/changelog.ko.md

@@ -6,39 +6,62 @@
 
 ## [Unreleased]
 
+## [0.2.0] — 스키마 관리 옵트인
+
+### Changed
+
+- **BREAKING: 스키마 관리가 옵트인 방식으로 변경.** v0.1.0은 Flyway를 강제로 깔고 번들 마이그레이션을 자동 실행했습니다. v0.2.0부터는 사용자가 선택:
+    - `api.log.schema.management=none` (기본) — DDL 직접 적용 (Liquibase, 수동 `psql`, 자체 Flyway 흐름)
+    - `api.log.schema.management=flyway` — 스타터가 `FlywayConfigurationCustomizer`를 등록해 자기 마이그레이션 위치를 Flyway에 추가
+- `flyway-core`, `flyway-database-postgresql`이 `<optional>true</optional>`로 변경 — `management=flyway` 쓰는 사용자가 직접 Flyway 의존성 추가 필요.
+- 마이그레이션 위치 이동: `classpath:db/migration/V1.0__create_api_log.sql` → `classpath:db/api-log/V1.0__create_api_log.sql` (사용자 기본 Flyway 위치와 충돌 방지).
+
+### v0.1.0에서 마이그레이션
+
+v0.1.0의 자동 마이그레이션에 의존하고 있었다면:
+
+1. `org.flywaydb:flyway-core` (+ runtime의 `flyway-database-postgresql`)를 본인 의존성에 추가.
+2. 설정에 `api.log.schema.management=flyway` 추가.
+
+스키마를 직접 적용하고 싶다면 (운영 환경 권장):
+
+1. [스키마 레퍼런스](reference/schema.md)의 SQL을 본인 마이그레이션 도구에 복사.
+2. `api.log.schema.management`는 기본값(`none`) 그대로.
+
+## [0.1.0] — 첫 공개
+
+첫 공개 릴리스. 독립 Spring Boot starter로 재패키징.
+
 ### Changed
 
 - **독립 Spring Boot Starter 라이브러리로 재구성.**
     - `groupId`: `com.devs.lab` → `kr.devslab`
     - `artifactId`: `api-log-starter` → `api-log-spring-boot-starter`
     - Java 패키지: `com.devs.lab.test.*` → `kr.devslab.apilog.*`
-- 데모 애플리케이션 제거 (`ApiLogApplication`, `compose.yaml`, `Dockerfile.postgres`) — 순수 라이브러리
-- 앱 전용 의존성 제거: `spring-boot-devtools`, `spring-boot-docker-compose`, `spring-boot-starter-actuator`
-- 빌드에서 `spring-boot-maven-plugin` 제거 (라이브러리, 실행 jar 아님)
+- 데모 애플리케이션 제거 (`ApiLogApplication`, `compose.yaml`, `Dockerfile.postgres`) — 순수 라이브러리.
+- 앱 전용 의존성 제거: `spring-boot-devtools`, `spring-boot-docker-compose`, `spring-boot-starter-actuator`.
+- 빌드에서 `spring-boot-maven-plugin` 제거 (라이브러리, 실행 jar 아님).
 
 ### Fixed
 
-- Flyway 마이그레이션 경로: `db.migration/` → `db/migration/` (점 버전은 표준 Flyway 위치가 아니라 자동 적용되지 않았음)
+- Flyway 마이그레이션 경로: `db.migration/` → `db/migration/` (점 버전은 표준 Flyway 위치가 아니라 자동 적용되지 않았음).
 
 ### Added
 
-- `LICENSE` (Apache 2.0) + `NOTICE`
-- Maven Central 발행에 필요한 `pom.xml` 메타데이터 (licenses, SCM, developers, organization)
-- 양국어 README (영문 기본 + `README.ko.md`)
-- 본 문서 사이트
-
-## [0.1.0] — 첫 공개
-
-첫 공개 릴리스. 독립 Spring Boot starter로 재패키징.
+- `LICENSE` (Apache 2.0) + `NOTICE`.
+- Maven Central 발행에 필요한 `pom.xml` 메타데이터 (licenses, SCM, developers, organization).
+- 양국어 README (영문 기본 + `README.ko.md`).
+- 본 문서 사이트.
 
 ### 하이라이트
 
-- `ApplicationEventPublisher`를 통한 비동기, 이벤트 드리븐 API 호출 로깅
-- `RestApiClientUtil` 내장 HTTP 클라이언트 — `GET` / `POST` × `sync` / `async` × `raw` / `typed`
-- 요청/응답/에러 본문의 PostgreSQL JSONB 저장
-- Spring Retry 통합과 `RETRY_ERROR` 이벤트
-- `ApiLogAutoConfiguration`을 통한 자동 구성, `@ConditionalOnMissingBean` 오버라이드
-- Testcontainers 기반 PostgreSQL 통합 테스트 31개
+- `ApplicationEventPublisher`를 통한 비동기, 이벤트 드리븐 API 호출 로깅.
+- `RestApiClientUtil` 내장 HTTP 클라이언트 — `GET` / `POST` × `sync` / `async` × `raw` / `typed`.
+- 요청/응답/에러 본문의 PostgreSQL JSONB 저장.
+- Spring Retry 통합과 `RETRY_ERROR` 이벤트.
+- `ApiLogAutoConfiguration`을 통한 자동 구성, `@ConditionalOnMissingBean` 오버라이드.
+- Testcontainers 기반 PostgreSQL 통합 테스트 31개.
 
-[Unreleased]: https://github.com/devslab-kr/api-log/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/devslab-kr/api-log/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/devslab-kr/api-log/releases/tag/v0.2.0
 [0.1.0]: https://github.com/devslab-kr/api-log/releases/tag/v0.1.0

docs/changelog.md

@@ -6,39 +6,62 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ## [Unreleased]
 
+## [0.2.0] — Schema management opt-in
+
+### Changed
+
+- **BREAKING: schema management is now opt-in.** v0.1.0 force-installed Flyway and auto-ran the bundled migration. v0.2.0 makes the consumer choose:
+    - `api.log.schema.management=none` (default) — apply the DDL yourself (Liquibase, manual `psql`, your own Flyway flow)
+    - `api.log.schema.management=flyway` — starter registers a `FlywayConfigurationCustomizer` that adds its location to your Flyway setup
+- `flyway-core` and `flyway-database-postgresql` are now `<optional>true</optional>` — consumers who want `management=flyway` must declare Flyway in their own build.
+- Migration relocated from `classpath:db/migration/V1.0__create_api_log.sql` to `classpath:db/api-log/V1.0__create_api_log.sql` so it no longer collides with the consumer's default Flyway location.
+
+### Migration guide (from v0.1.0)
+
+If you were depending on v0.1.0's auto-migration:
+
+1. Add `org.flywaydb:flyway-core` (and `flyway-database-postgresql` runtime) to your dependencies.
+2. Set `api.log.schema.management=flyway` in your config.
+
+If you'd rather apply the schema yourself (recommended for production):
+
+1. Copy the SQL from [Schema reference](reference/schema.md) into your migration tool of choice.
+2. Leave `api.log.schema.management` at its default (`none`).
+
+## [0.1.0] — Initial release
+
+First public release. Repackaged as a standalone Spring Boot starter.
+
 ### Changed
 
 - **Restructured as standalone Spring Boot Starter library.**
     - `groupId`: `com.devs.lab` → `kr.devslab`
     - `artifactId`: `api-log-starter` → `api-log-spring-boot-starter`
     - Java package: `com.devs.lab.test.*` → `kr.devslab.apilog.*`
-- Removed demo application (`ApiLogApplication`, `compose.yaml`, `Dockerfile.postgres`) — pure library now
-- Removed app-only dependencies: `spring-boot-devtools`, `spring-boot-docker-compose`, `spring-boot-starter-actuator`
-- Removed `spring-boot-maven-plugin` from build (library, not executable jar)
+- Removed demo application (`ApiLogApplication`, `compose.yaml`, `Dockerfile.postgres`) — pure library.
+- Removed app-only dependencies: `spring-boot-devtools`, `spring-boot-docker-compose`, `spring-boot-starter-actuator`.
+- Removed `spring-boot-maven-plugin` from build (library, not executable jar).
 
 ### Fixed
 
-- Flyway migration path: `db.migration/` → `db/migration/` (the dot version wasn't a standard Flyway location and never auto-applied)
+- Flyway migration path: `db.migration/` → `db/migration/` (the dot version wasn't a standard Flyway location and never auto-applied).
 
 ### Added
 
-- `LICENSE` (Apache 2.0) + `NOTICE`
-- Full `pom.xml` metadata (licenses, SCM, developers, organization) required for Maven Central publishing
-- Bilingual README (English default + `README.ko.md`)
-- This documentation site
-
-## [0.1.0] — Initial release
-
-First public release. Repackaged as a standalone Spring Boot starter.
+- `LICENSE` (Apache 2.0) + `NOTICE`.
+- Full `pom.xml` metadata (licenses, SCM, developers, organization) required for Maven Central publishing.
+- Bilingual README (English default + `README.ko.md`).
+- This documentation site.
 
 ### Highlights
 
-- Async, event-driven API call logging via `ApplicationEventPublisher`
-- `RestApiClientUtil` bundled HTTP client with `GET` / `POST` × `sync` / `async` × `raw` / `typed`
-- PostgreSQL JSONB storage for request/response/error bodies
-- Spring Retry integration with `RETRY_ERROR` events
-- Auto-configuration via `ApiLogAutoConfiguration` with `@ConditionalOnMissingBean` overrides
-- 31 tests including PostgreSQL integration via Testcontainers
+- Async, event-driven API call logging via `ApplicationEventPublisher`.
+- `RestApiClientUtil` bundled HTTP client with `GET` / `POST` × `sync` / `async` × `raw` / `typed`.
+- PostgreSQL JSONB storage for request/response/error bodies.
+- Spring Retry integration with `RETRY_ERROR` events.
+- Auto-configuration via `ApiLogAutoConfiguration` with `@ConditionalOnMissingBean` overrides.
+- 31 tests including PostgreSQL integration via Testcontainers.
 
-[Unreleased]: https://github.com/devslab-kr/api-log/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/devslab-kr/api-log/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/devslab-kr/api-log/releases/tag/v0.2.0
 [0.1.0]: https://github.com/devslab-kr/api-log/releases/tag/v0.1.0