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

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title	source_type	url	archive_url	related_branches	related_projects	tags	created
official-doc / Keycloak — Configuring the Database (KC_DB / db-url / db-username / db-password)	official-doc	https://www.keycloak.org/server/db		feature-keycloak-docker-compose-stack	keycloak-patterns	official-doc keycloak-patterns persistence keycloak postgresql	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>)
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 요약: (미작성)