llm-wiki/raw/official-docs/keycloak-configuring-database.md

---
title: official-doc / Keycloak — Configuring the Database (KC_DB / db-url / db-username / db-password)
source_type: official-doc
url: https://www.keycloak.org/server/db
archive_url:
related_branches: [feature-keycloak-docker-compose-stack]
related_projects: [keycloak-patterns]
tags: [official-doc, keycloak-patterns, persistence, keycloak, postgresql]
created: 2026-07-16
---

# Keycloak — Configuring the Database

> Layer: `raw/official-docs/` — Keycloak 공식 Server Guides 의 "Configuring the database" 페이지 (`/server/db`) 발췌. `KC_DB=postgres` vendor 선택값과 `KC_DB_URL` / `KC_DB_USERNAME` / `KC_DB_PASSWORD` JDBC 연결 환경변수의 정확한 이름·형식 근거.

## source_type 허용값

- `official-doc` — Keycloak (Red Hat) 공식 Server Guides reference 페이지.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-keycloak-docker-compose-stack]] | D2 — Keycloak 기본 `dev-file` 대신 PostgreSQL 을 database 로 사용하는 결정. 구체적으로 `KC_DB=postgres` vendor 값과 `KC_DB_URL` / `KC_DB_USERNAME` / `KC_DB_PASSWORD` JDBC 연결 환경변수 (Keycloak 26.x 컨테이너 기준) 근거 |

## 출처 / Source

- 원본 URL: https://www.keycloak.org/server/db
- 아카이브 URL: (미수집)
- 저자 / 조직: Keycloak (Red Hat) — Server Guides ("Configuring the database")
- 발행일: rolling docs (버전 미고정 페이지)
- 마지막 확인일: 2026-07-16

## 왜 저장했는지 / Why archived

`feature-keycloak-docker-compose-stack` 의 D2 (PostgreSQL 사용) 가 기존에 `UNSUPPORTED_DECISION` (verbatim 부재) 로 라벨되어 있었음. 본 자료는 그 gap 을 메우는 공식 vendor doc — `db`/`KC_DB` 가 vendor 선택 키이고 `postgres` 가 지원 값임을, 그리고 `KC_DB_URL`/`KC_DB_USERNAME`/`KC_DB_PASSWORD` 의 정확한 이름과 JDBC URL 형식을 직접 인용으로 확보하기 위해 저장.

## 핵심 인용 / Key quotes (verbatim, 3~5문장)

> [§Supported databases] "By default, the server uses the dev-file database. This is the default database that the server will use to persist data and only exists for development use-cases. The dev-file database is not suitable for production use-cases, and must be replaced before deploying to production."

> [§Relevant options — `db`] "The database vendor." ... "Env: KC_DB" ... "dev-file, dev-mem, mariadb, mssql, mysql, oracle, postgres, tidb"

> [§Configuring a database] "# The database vendor.
db=postgres

# The username of the database user.
db-username=keycloak

# The password of the database user.
db-password=change_me

# Sets the hostname of the default JDBC URL of the chosen vendor
db-url-host=keycloak-postgres"

> [§Relevant options — `db-url` / §Overriding default connection settings] "The full database JDBC URL. If not provided, a default URL is set based on the selected database vendor. For instance, if using postgres, the default JDBC URL would be jdbc:postgresql://localhost/keycloak." ... "bin/kc.[sh|bat] start --db postgres --db-url jdbc:postgresql://mypostgres/mydatabase"

> [§Relevant options — `db-username` / `db-password`] "The username of the database user." ... "Env: KC_DB_USERNAME" ... "The password of the database user." ... "Env: KC_DB_PASSWORD"

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| KC-DB-C1 | Keycloak 서버는 기본값으로 `dev-file` database 를 사용하며, 이는 개발 용도로만 존재하고 production 배포 전에 반드시 교체되어야 한다 | [§Supported databases] "By default, the server uses the dev-file database. ... The dev-file database is not suitable for production use-cases, and must be replaced before deploying to production." | `official-vendor-doc` | 기본 `dev-file` db 를 다른 production-grade RDBMS 로 교체해야 하는 근거 일반 | PostgreSQL 이 유일한 대안이라는 뜻은 아님 — `mariadb`/`mssql`/`mysql`/`oracle`/`tidb` 도 동일하게 지원됨 (KC-DB-C2) |
| KC-DB-C2 | `db` 설정 키 (CLI `--db`, 환경변수 `KC_DB`) 가 database vendor 를 선택하며, 허용값 목록에 `postgres` 가 공식 포함됨 (`dev-file, dev-mem, mariadb, mssql, mysql, oracle, postgres, tidb`) | [§Relevant options — `db`] "The database vendor." / "Env: KC_DB" / "dev-file, dev-mem, mariadb, mssql, mysql, oracle, postgres, tidb" | `official-vendor-doc` | `KC_DB=postgres` 환경변수 사용의 vendor-value 정확성 | 이 표가 어느 Keycloak 버전 범위에 적용되는지는 본 페이지에 버전 고정 표기 없음 (rolling docs) |
| KC-DB-C3 | Keycloak 공식 최소 설정 예시는 "the minimum settings needed to connect to the database" 로 `db=postgres`, `db-username=keycloak`, `db-password=change_me`, `db-url-host=keycloak-postgres` 4개 키 조합을 제시한다 | [§Configuring a database] `db=postgres` / `db-username=keycloak` / `db-password=change_me` / `db-url-host=keycloak-postgres` (연속 코드 블록) | `official-vendor-doc` | 컨테이너/`.env` 환경변수 등가형 (`KC_DB`, `KC_DB_USERNAME`, `KC_DB_PASSWORD`, `KC_DB_URL_HOST`) 사용 패턴 | `db-url-host` 조합과 `db-url`(`KC_DB_URL`) 전체 JDBC URL 지정 중 docker-compose 컨텍스트에서 어느 쪽이 더 권장되는지는 본 인용이 특정하지 않음 — 문서는 둘을 대등한 대안으로 제시 |
| KC-DB-C4 | `db-url` (환경변수 `KC_DB_URL`) 은 "the full database JDBC URL" 이며, 미지정 시 vendor 별 기본 URL 이 생성되고(postgres 기본형: `jdbc:postgresql://localhost/keycloak`), 명시적으로 override 하는 예시 형식은 `--db-url jdbc:postgresql://mypostgres/mydatabase` 이다 | [§Relevant options — `db-url`] "The full database JDBC URL. If not provided, a default URL is set based on the selected database vendor. For instance, if using postgres, the default JDBC URL would be jdbc:postgresql://localhost/keycloak." / [§Overriding default connection settings] "bin/kc.[sh|bat] start --db postgres --db-url jdbc:postgresql://mypostgres/mydatabase" | `official-vendor-doc` | 브랜치의 `KC_DB_URL` 환경변수에 들어갈 정확한 JDBC URL 문법 (`jdbc:postgresql://<host>[:<port>]/<database>`) | 브랜치의 docker-compose 네트워크에서 실제 사용할 hostname/port/db 이름 값 자체는 이 자료가 정하지 않음 (로컬 서비스 명명은 branch 자체 결정) |
| KC-DB-C5 | `db-username` (환경변수 `KC_DB_USERNAME`) 은 "the username of the database user", `db-password` (환경변수 `KC_DB_PASSWORD`) 는 "the password of the database user" 로 공식 정의됨 | [§Relevant options — `db-username`/`db-password`] "The username of the database user." / "Env: KC_DB_USERNAME" / "The password of the database user." / "Env: KC_DB_PASSWORD" | `official-vendor-doc` | 브랜치 TODO 에 등장하는 `KC_DB_USERNAME`/`KC_DB_PASSWORD` 환경변수명이 정확함을 확인 | secret 을 `.env` 파일 vs Docker secret 중 어느 방식으로 주입할지는 이 자료가 규정하지 않음 (운영 선택) |

### Strength 참고

모든 claim 이 `official-vendor-doc` — Keycloak (Red Hat) 공식 Server Guides reference 페이지의 직접 인용.

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `KC-DB-C1`: 기본 `dev-file` db 는 production 부적합 — 교체 필요성의 공식 근거
  - `KC-DB-C2`: `KC_DB=postgres` 가 공식 지원 vendor 값
  - `KC-DB-C3`: `db`/`db-username`/`db-password`/`db-url-host` 4개 키가 공식 "minimum settings" 조합
  - `KC-DB-C4`: `KC_DB_URL` 의 정확한 JDBC URL 문법과 postgres 기본형
  - `KC-DB-C5`: `KC_DB_USERNAME` / `KC_DB_PASSWORD` 가 정확한 환경변수명
- 이 자료가 증명하지 않는 것:
  - PostgreSQL 이 MySQL/MariaDB 등 다른 지원 vendor 대비 "더 나은" 선택이라는 것 (branch 의 D2 는 "prod-like 환경 학습" 이유로 자체 결정한 것 — 이 자료는 postgres 가 *지원됨*을 증명할 뿐, *권장됨*을 증명하지 않음)
  - Keycloak 26.x 라는 특정 버전에서 이 표가 정확히 동일하다는 것 (페이지가 rolling docs — 버전 고정 스냅샷 아님)
  - docker-compose 서비스명 해석 (`keycloak-postgres`, `postgres` 등) 자체의 정확성 — Docker 네트워크 동작이지 Keycloak 문서 범위 밖
  - `$` 포함 비밀번호의 `KCRAW_DB_PASSWORD` 대체 필요 여부가 branch 의 실제 `.env` 비밀번호에 해당하는지 (본 raw 는 해당 옵션의 존재만 확인, 적용 여부는 branch 개별 확인 필요)
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - `docker compose up -d` 후 실제 `KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak` 형식으로 접속 성공하는지 (compose service name 이 hostname 역할)
  - Keycloak 26.x 컨테이너 이미지에서 이 env var 세트가 그대로 동작하는지 (버전 pin 검증)

## 메모 / Notes

- WebFetch 툴의 첫 2회 호출이 원문을 한국어로 paraphrase/요약해 verbatim 요건을 만족하지 못함 (small model 처리 특성) → `curl` 로 원본 HTML 직접 확보 후 태그 스트립으로 verbatim 텍스트 재구성, self-grep 전량 통과.
- 페이지는 "Relevant options" 표 (§_relevant_options 앵커) 아래에 `db`, `db-url`, `db-username`, `db-password` 등 전체 config reference 를 갖고 있음 — 추후 `db-schema`, `db-pool-*`, `db-tls-mode` 등 다른 옵션도 필요 시 이 페이지에서 추가 발췌 가능.
- [[raw/official-docs/keycloak-server-containers-docker]] 의 `KC-CONTAINER-C5` (환경변수 이름 verbatim 부재로 `needs-confirmation`) 를 본 자료가 `KC_DB`/`KC_DB_URL`/`KC_DB_USERNAME`/`KC_DB_PASSWORD` 범위에서 보강함.

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/keycloak-server-containers-docker]] — 컨테이너 실행 일반 (`KC_HOSTNAME`, `start-dev`), `KC_DB` 계열 env var 이름은 여기서 `needs-confirmation` 이었음 — 본 자료가 확정
  - [[raw/official-docs/keycloak-getting-started-docker]] — Docker quickstart
- 이 자료를 인용한 wiki 요약: (미작성)