FastAPI에서 settings 사용하는 방법 - pydantic-settings

1. pydantic-settings 소개

   - pydantic-settings는 애플리케이션의 설정을 손쉽게 관리할 수 있도록 돕는 라이브러리이다.
   - 이전에는 Pydantic의 BaseSettings를 사용하여 설정을 관리했지만, Pydantic v2에서는 pydantic-settings가 별도의 패키지로 분리되었다.

 

2. 주요 기능

   - 환경 변수, .env 파일, 설정 파일에서 값을 로드
   - 기본값 설정 및 유효성 검사 지원
   - pydantic의 강력한 데이터 검증 기능 활용 가능
   - 계층적인 설정 관리 지원

 

3. pydantic-settings 설치

   - Pydantic v2를 사용한다면 pydantic-settings를 별도로 설치해야 한다.

pip install pydantic-settings

 

4. 기본 사용법

   - Pydantic v2에서는 BaseSettings 대신 pydantic_settings.SettingsConfigDict를 사용한다.

 

   1) 환경 변수에서 설정 불러오기

from pydantic import BaseModel
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    # 애플리케이션 설정
    app_name: str = "MyApp"
    debug: bool = False
    database_url: str
    
    # 설정을 불러오는 방법을 지정하는 설정
    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")

# 설정 인스턴스 생성
settings = Settings()

# 설정 값 출력
print(settings.app_name)
print(settings.debug)
print(settings.database_url)

 

   2) .env 파일 예시

DATABASE_URL=postgresql://user:password@localhost:5432/mydb
APP_NAME=AwesomeApp
DEBUG=true

 

5. 기본 사용법

   - SettingsConfigDict 설정 옵션

옵션명	설명
env_file	.env 파일의 경로 지정 (기본값: None)
env_file_encoding	.env 파일의 인코딩 지정 (기본값: utf-8)
env_prefix	환경 변수 앞에 붙일 접두사 지정
extra	ignore, allow, forbid 중 선택 가능 (ignore: 추가 필드 무시, allow: 허용, forbid: 예외 발생)
case_sensitive	환경 변수의 대소문자 구분 여부 (False일 경우 소문자로 변환)
validate_assignment	값을 할당할 때 즉시 유효성 검사 수행 여부

 

   1) env_prefix 사용 예제

      - 환경 변수의 접두사를 설정할 수 있다.

class Settings(BaseSettings):
    api_key: str
    model_config = SettingsConfigDict(env_prefix="MYAPP_")  # 환경 변수 접두사

settings = Settings()

 

   2) .env 파일

MYAPP_API_KEY=abcdef123456

 

   3) 필드별 환경 변수 지정

      - 각 필드마다 환경 변수를 지정할 수도 있다.

      - 이렇게 하면 DB_HOST → db_host, DB_PORT → db_port 로 자동 매핑된다.

class Settings(BaseSettings):
    db_host: str = "localhost"
    db_port: int = 5432
    db_user: str
    db_password: str
    
    model_config = SettingsConfigDict(env_file=".env")
    
    class Config:
        env_prefix = "DB_"  # 모든 환경 변수 앞에 DB_ 추가

settings = Settings()

 

   4) .env 파일

DB_HOST=mydbserver.com
DB_PORT=3306
DB_USER=admin
DB_PASSWORD=secret

 

6. SecretStr를 사용한 보안 관리

   - 비밀번호나 API 키와 같은 민감한 정보는 pydantic.SecretStr을 사용할 수 있다.

from pydantic import SecretStr

class Settings(BaseSettings):
    db_password: SecretStr

    model_config = SettingsConfigDict(env_file=".env")

settings = Settings()
print(settings.db_password)  # 출력 시 '**********' 로 가려짐
print(settings.db_password.get_secret_value())  # 실제 값 가져오기

 

   1) .env 파일

DB_PASSWORD=mysecretpassword

 

7. 중첩 설정 (Nested Settings)

   1) Pydantic 모델을 활용하면 중첩된 설정을 만들 수도 있다.

class DatabaseSettings(BaseModel):
    host: str
    port: int
    user: str
    password: str

class Settings(BaseSettings):
    database: DatabaseSettings
    
    model_config = SettingsConfigDict(env_prefix="APP_")

settings = Settings(
    database={"host": "localhost", "port": 5432, "user": "admin", "password": "secret"}
)
print(settings.database.host)

 

   2) 환경 변수로 설정 가능

APP_DATABASE={"host": "localhost", "port": 5432, "user": "admin", "password": "secret"}

 

8. .env 파일 없이 환경 변수 직접 지정

import os

os.environ["DATABASE_URL"] = "postgresql://user:password@localhost:5432/mydb"

class Settings(BaseSettings):
    database_url: str

settings = Settings()
print(settings.database_url)  # 환경 변수에서 직접 가져옴

 

9. 옵션값 설정

class Settings(BaseSettings):
    API_KEY: str  # 필수값
    DEBUG: bool = False  # 옵션값 (기본값 제공)
    TIMEOUT: int = 30  # 옵션값 (기본값 제공)

settings = Settings()
print(settings.DEBUG)  # 환경변수에 DEBUG가 없으면 기본값(False) 사용

 

10. .env 파일 없이 .yaml 또는 .json 설정 파일 로드 python 복사 편집

import json

class Settings(BaseSettings):
    app_name: str

    model_config = SettingsConfigDict(env_file="config.json")

# JSON 설정 파일 예시
json_config = {"APP_NAME": "MyAwesomeApp"}
with open("config.json", "w") as f:
    json.dump(json_config, f)

settings = Settings()
print(settings.app_name)  # MyAwesomeApp

 

 

- reference : 

https://chaechae.life/blog/fastapi-settings

FastAPI Settings - Pydantic Settings 관리하기