FastAPI ch09 의존성 충돌 및 데이터베이스 연결 트러블슈팅 리포트

FastAPI ch09 의존성 충돌 및 데이터베이스 연결 트러블슈팅 리포트

본 포스팅은 깃허브 클라우드 워크스페이스(GitHub Codespaces)의 Python 3.12 환경에서 예제 프로젝트(ch09/planner)를 구동하는 과정 중 발생한 패키지 버전 불일치 오류와 데이터베이스(MongoDB) 연결 실패 문제를 소스코드 수정 없이 오직 인프라 설정 및 패키지 최적화만으로 해결한 기술적 기록입니다.

💡 핵심 요약: Python 3.12에서 발생한 asyncio 및 email-validator 버전 오류를 상위 호환 패키지 세트로 격파하고, 도커(Docker) 기반 데이터베이스 다중 가동 및 pip freeze 역추적을 통해 인프라 환경을 완벽하게 동기화했습니다.
Issue 1: Python 3.12 라이브러리 문법 삭제로 인한 ImportError

[증상] 책의 오리지널 requirements.txt 기반 패키지 설치 후 서버 구동(python main.py) 시, asyncio 하위 모듈 진입 단계에서 시스템이 전면 중단되는 오류가 발생했습니다.

ImportError: cannot import name 'coroutine' from 'asyncio' (/home/codespace/.python/current/lib/python3.12/asyncio/__init__.py)

[원인] 파이썬 3.12 버전 번역기부터 과거의 레거시 문법인 asyncio.coroutine이 전면 삭제되었으나, 예제에 고정된 구버전 프레임워크(FastAPI 구버전, Motor 구버전 등)가 해당 문법을 여전히 참조하고 있어 발생한 호환성 충돌이었습니다.

[해결] 소스코드를 건드리지 않는 원칙에 따라, 기존 낡은 패키지 주머니를 완전히 삭제한 후 파이썬 3.12 환경을 정식 지원하는 최적의 상위 호환 버전 세트를 가상환경 내에 수동으로 재구성하여 일괄 클린 설치를 집행했습니다.

pip uninstall -y fastapi uvicorn motor beanie passlib python-jose email-validator
pip install fastapi==0.104.1 uvicorn==0.24.0 motor==3.3.2 beanie==1.25.0 email-validator==2.1.0
Issue 2: MongoDB 연결 설정 미비 및 다중 터미널 가동 문제

[증상] 패키지 버전 충돌을 격파한 후, 애플리케이션 시작 대기(Waiting for application startup) 로그 출력 직후 데이터베이스 연결 자격증명이 누락되었다는 구성 오류가 연쇄적으로 분출되었습니다.

pymongo.errors.ConfigurationError: No default database name defined or provided.
ERROR: Application startup failed. Exiting.

[원인] 백엔드 서비스(FastAPI)가 기동될 때 데이터를 적재할 식재료 창고인 MongoDB 데이터베이스 엔진이 로컬 시스템 내에 가동되고 있지 않았으며, 환경 변수 수첩(.env) 내의 접속 경로 포트 번호가 클라우드 컨테이너의 포트 포워딩 환경과 일치하지 않아 발생한 통신 단절이었습니다.

[해결] 첫째, + 버튼을 활용해 **독립적인 2번 터미널(알바생)을 추가 개설**하고, 백그라운드 환경에서 식재료 창고를 상시 열어두는 도커 컴포즈 오케스트레이션 명령을 단독 실행시켰습니다.

docker compose -f docker-compose.xml up -d database

둘째, 깃허브 클라우드가 무작위로 매핑한 포트 가상 번호(예: 32768)를 정확히 추적하여 프로젝트 내 비밀 수첩인 .env 파일의 DATABASE_URL 주소 값을 물리적으로 동기화 튜닝했습니다. 그 결과 서버 재시작 시 Application startup complete와 함께 초록색 200 OK 통신망이 완벽하게 결속되었습니다.

Infrastructure Freezing: 재현 가능성을 위한 최종 동기화

[결과 보존] 트러블슈팅이 완전히 종결된 직후, 다음 챕터 학습 시 동일한 시행착오를 차단하기 위해 pip freeze 명령을 사용하여 현재 완벽하게 정제된 파이썬 3.12용 의존성 환경 구조를 설정 파일에 영구 박제(Freeze)했습니다.

pip freeze > requirements.txt

동시에 실시간 기계어 변환 과정에서 생성되는 캐시 찌꺼기 파일(.pyc)들이 깃의 추적 목록을 더럽히지 않도록 만능 블랙리스트 수첩 규칙(__pycache__/)을 .gitignore에 심어 줌으로써, 소스 제어창을 완전히 투명하게 리팩토링하고 최종 세이브포인트(Commit)를 깔끔하게 마무리했습니다.

댓글

댓글 쓰기

인기 포스츠

"내 말이 그 말이야!" 원어민들이 매일 쓰는 맞장구 영어 표현 3가지

"내 말이 그 말이야!" 원어민들이 매일 쓰는 맞장구 영어 표현 3가지 미드나 영화를 보다 보면 상대방의 말에 격하게 공감할 때 쓰는 표현들이 정말 자주 나옵니다. 단순히 "Yes"나 "I agree"를 넘어, 원어민 뉘앙스를 100% 살려줄 수 있는 진짜 리얼한 맞장구 표현 3가지를 정리해 드릴게요! 💡 핵심 요약: You can say that again: "두 말하면 잔소리지!" (격한 공감) Tell me about it: "내 말이 그 말이야!" (부정적이거나 힘든 상황에 공감) You hit the nail on the head: "정확히 맞혔어!, 핵심을 찔렀네!" (정답일 때) 1. 격하게 동의할 때: You can say that again 직역하면 "그 말을 다시 해도 된다"이지만, 실제로는 "네 말이 100% 맞아", "두 말하면 잔소리지" 라는 뜻으로 쓰입니다. 상대방의 의견에 완벽하게 동의할 때 사용하기 아주 좋은 표현입니다. A: Today is so hot. (오늘 진짜 덥다.) B: You can say that again! (두 말하면 잔소리지!) 2. 힘들거나 짜증 나는 상황에 공감할 때: Tell me about it 이 표현은 "그것에 대해 말해줘"라는 뜻이 절대 아닙니다! "말 안 해도 다 안다", "내 말이 그 말이야" 라는 의미로, 주로 상대방이 불평을 하거나 힘든 상황을 털어놓을 때 '나도 그 마음 정말 잘 안다' 는 뉘앙스로 맞장구칠 때 씁니다. 반어법적인 뉘앙스가 섞여 있어요. A: Traffic is terrible today. (오늘 차 진짜 막힌다.) B: Tell me about it...
Read more »

"인생에 참여하라" 삶을 변화시키는 영어 표현 2가지

[DAILY CINEMA English #4 - FINAL] "인생에 참여하라" 삶을 변화시키는 영어 표현 2가지 원래 유튜브 영상 주소: https://youtube.com 안녕하세요! 시네마틱 영어 시리즈를 마무리하는 마지막 네 번째 시간입니다. 상단에 기재된 Life of Riza의 고유 영상 링크를 클릭하셔서 마지막 에피소드를 감상해 보세요. 수동적인 기다림을 끝내고 우리의 삶에 적극적으로 뛰어들게 만드는 원어민 실전 표현 2가지를 학습해 보겠습니다. 1. Actively participate in ~ 뜻: ~에 적극적으로 참여하다 / 주도적으로 동참하다 관객석에 앉아 내 인생이라는 영화를 구경만 하는 것이 아니라, 무대 위 주인공이 되어 내 삶을 스스로 이끌고 치열하게 살아가는 태도를 뜻하는 깊이 있는 표현입니다. 💡 핵심 요약 (Example): "The only way to get through this thing we call life is to actively participate in it." (우리가 인생이라 부르는 이 여정을 통과하는 유일한 방법은 그 안에 적극적으로 참여하는 거야.) 2. Take risks 뜻: 위험을 감수하다 / 과감히 도전하다 실패나 좌절이 두려워 안전지대에만 머무르는 것이 아니라, 내가 원하는 것이 무엇인지 찾고 성장하기 위해 불확실성을 무릅쓰고 용기를 내는 행동을 의미합니다. 💡 핵심 요약 (Example): "You have to do things; you have to take risks to find out who you really are." (무언가를 시도해야 해. 우리가 진짜 누구인지 알아내려면 위험을 감수하고 도전해야만 해.) 🎬 크리에이터 소개 및 연재 이력 (Creator Credit) 본 연재 시리즈는 글로벌 시네마틱 ...
Read more »

2. Local Post Workspace Update and Technical SEO Template Deployment

한국어 (KO) English (EN) 2. 로컬 포스트 연습장 업데이트 및 테크니컬 SEO 템플릿 안착 블로그의 장기적인 유입을 위해서는 단순히 글을 쓰는 것을 넘어 구글 검색 엔진이 좋아하는 구조를 갖추어야 합니다. 이를 위해 로컬 집필 환경인 index.html 연습장에 테크니컬 SEO(검색엔진 최적화) 문법 체계를 완전히 통합했습니다. 💡 핵심 요약: 단순 디자인 클래스(div) 대신 계층형 제목 태그(H2, H3)와 메타 데이터를 혼합하면, 구글 봇이 글의 핵심 맥락을 가장 정확하게 수집해 가며 검색 노출 점수에 가산점을 받게 됩니다. 2-1. 통합 템플릿의 핵심 고도화 내용 시맨틱 태그 전환 : 기존 구조의 한계를 탈피하고 <h2> (중제목)와 <h3> (소제목) 위계 서열을 확립하여 검색 봇 친화적 구조 완성 메타 키워드 내장 : 화면에는 보이지 않는 meta name="keywords" 영역을 주입하여 타겟팅 검색 유입 유도 하단 해시태그 레이아웃 : 얇은 점선과 주황색 포인트 칩을 입힌 노출형 #TAGS 바를 구현하여 직관적인 카테고리 가독성 확보 2-2. 실전 집필용 SEO 마스터 템플릿 소스코드 앞으로 새 글을 쓸 때마다 복사해서 사용할 수 있는 정석 뼈대 레이아웃 코드 가이드라인입니다. <!-- 포스트 시작 --> <div class="bilingual-post"> <!-- 언어 선택 버튼 구역 --> <div class="lang-toggle-container"> <button id="btn-ko" class="lang-btn active" onclick=...
Read more »