🐍 SQLAlchemy 기본 문법 (한 번에 끝내기)

1) SQLAlchemy는 무엇을 해결하나? 🧪

SQLAlchemy는 Python 객체로 작업하면, 내부에서 SQL을 자동 생성해 DB와 대화하게 만든다.
즉, “객체지향 세계”와 “관계형 DB 세계” 사이의 번역(매핑)을 자동화한다.

📌 전통적인 방식 vs ORM 방식

구분	직접 SQL	ORM (SQLAlchemy)
쿼리 작성	SQL 문자열을 직접 작성	Python 코드(모델/쿼리 객체)로 작성
결과 형태	튜플/딕셔너리	Python 객체
변경 대응	DB 교체/스키마 변경 시 수정량 큼	연결 문자열/모델 중심으로 대응

---

2) Engine → Base/Model → Session → CRUD 🔄

흐름도

[Python App]
   |
   v
+-------------------+
| Engine (DB 연결)   | create_engine("...")
+-------------------+
   |
   v
+-------------------+
| Session (대화창구)  | Session(engine)
+-------------------+
   |
   v
+-------------------+
| Model (테이블 매핑)  | class User(Base): ...
+-------------------+
   |
   v
+-------------------+
| CRUD + Commit/RB  | add/get/select/delete
+-------------------+

핵심 관찰 포인트 ✅
• Engine은 “DB로 가는 길”
• Session은 “DB와 대화하는 창구”이자 “변경사항을 모아두는 작업대”
• Model은 “테이블 ↔ 클래스” 매핑 규칙
• commit()이 실행되는 순간 INSERT/UPDATE/DELETE가 실제로 반영됨

---

3) 설치 및 준비 🧰

필요 패키지
• SQLAlchemy (ORM)
• DB 드라이버 (MySQL/MariaDB면 PyMySQL 등)

pip install sqlalchemy pymysql

---

4) 연결 문자열(DSN) 구조 이해하기 🔌

연결 문자열은 이런 형태다.

DB종류+드라이버://사용자:비밀번호@호스트:포트/DB이름
"mysql+pymysql://root:1234@localhost:3306/mydb",

예시 조각	의미
mysql+pymysql	MySQL + PyMySQL 드라이버 사용
root:1234	계정/비밀번호
localhost:3306	호스트/포트
mydb	DB 스키마 이름

주의 ⚠️
비밀번호를 코드에 박아두면 바로 사고로 이어진다.
.env / OS env / Secrets Manager 등으로 분리하는 습관이 중요!

---

5) Engine/Base/Model/Session/CRUD 한 번에 🧩

DB는 MySQL/MariaDB 기준이고, DB명/계정/비번은 환경에 맞게 바꿔야 한다.

# sqlalchemy_basic.py
# SQLAlchemy 기본 흐름: Engine -> Base/Model -> Session -> CRUD
# 실행 전:
# pip install sqlalchemy pymysql

from datetime import datetime
from sqlalchemy import create_engine, Column, Integer, String, Boolean, DateTime, select
from sqlalchemy.orm import declarative_base, Session

# ============================================================
# 1) Engine: DB로 가는 "연결 통로"
# ============================================================
# echo=True : SQLAlchemy가 생성한 SQL을 콘솔에 찍어준다 (학습 시 유용)
# pool_pre_ping=True : 죽은 커넥션을 자동 감지 (실무에서 꽤 도움됨)
engine = create_engine(
    "mysql+pymysql://root:1234@localhost:3306/mydb",
    echo=True,
    pool_pre_ping=True,
)

# ============================================================
# 2) Base: 매핑 자동화의 출발점
# ============================================================
# Base를 상속받는 클래스는 "테이블과 연결될 후보"가 된다
Base = declarative_base()

# ============================================================
# 3) Model: 테이블을 클래스로 정의
# ============================================================
class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, autoincrement=True)
    username = Column(String(50), nullable=False)
    email = Column(String(255), unique=True, nullable=False)

    is_active = Column(Boolean, default=True, nullable=False)
    created_at = Column(DateTime, default=datetime.now, nullable=False)

    def __repr__(self):
        return f"User(id={self.id}, username='{self.username}', email='{self.email}')"

# ============================================================
# 4) 테이블 생성: 모델 -> 실제 DB 반영
# ============================================================
# create_all()은 "없을 때만" 만든다
# 스키마 변경(컬럼 추가/수정/삭제)은 보통 Alembic 같은 마이그레이션 도구로 한다
Base.metadata.create_all(engine)

# ============================================================
# 5) Session: DB와 대화하는 창구 + 변경사항을 모으는 작업대(Unit of Work)
# ============================================================
# 핵심:
# - add()/delete()는 "예약"에 가깝다
# - commit()에서 실제로 INSERT/UPDATE/DELETE가 반영된다
# - 예외 발생 시 rollback()이 안전벨트다

def main():
    # -----------------------------
    # Create (INSERT)
    # -----------------------------
    with Session(engine) as session:
        try:
            user = User(username="jay", email="jay@example.com")
            session.add(user)

            # flush는 "DB에 SQL을 보내 PK를 받아오는 단계"까지 수행할 수 있다
            # commit 전에 user.id가 필요할 때 유용하다
            session.flush()
            print("생성된 PK:", user.id)

            session.commit()
        except Exception as e:
            session.rollback()
            raise e

    # -----------------------------
    # Read (SELECT)
    # -----------------------------
    with Session(engine) as session:
        # 1) PK로 단일 조회
        found = session.get(User, 1)
        print("PK 조회:", found)

        # 2) 조건 조회 (SQLAlchemy 2.0 스타일)
        stmt = select(User).where(User.username == "jay")
        user_jay = session.scalars(stmt).first()
        print("조건 조회:", user_jay)

        # 3) 전체 조회
        stmt_all = select(User)
        users = session.scalars(stmt_all).all()
        print("전체 조회:", users)

    # -----------------------------
    # Update (UPDATE)
    # -----------------------------
    with Session(engine) as session:
        try:
            target = session.get(User, 1)
            if target:
                target.username = "jay_edited"
                # 변경 감지는 SQLAlchemy가 한다 (dirty tracking)
                session.commit()
                print("수정 완료:", target)
            else:
                print("수정 대상 없음")
        except Exception as e:
            session.rollback()
            raise e

    # -----------------------------
    # Delete (DELETE)
    # -----------------------------
    with Session(engine) as session:
        try:
            target = session.get(User, 1)
            if target:
                session.delete(target)
                session.commit()
                print("삭제 완료:", target)
            else:
                print("삭제 대상 없음")
        except Exception as e:
            session.rollback()
            raise e

if __name__ == "__main__":
    main()
    

---

6) “commit() 전에는 DB에 반영 안 된다”의 의미 💾

add()는 곧바로 INSERT가 아니라 “세션 작업대에 올려두는 행위”다.

session.add(user)
=> [Session 작업대]에 user가 올라감 (아직 DB 반영 X)

session.flush()
=> INSERT SQL이 나갈 수 있음 (PK 필요할 때 유용)

session.commit()
=> 트랜잭션 확정, 실제 DB 반영 O

예외 발생
=> session.rollback()으로 되돌림

---

7) 컬럼 타입 매핑 🧾

SQL	SQLAlchemy	예시
INT	Integer	Column(Integer)
VARCHAR(n)	String(n)	Column(String(100))
TEXT	Text	Column(Text)
BOOLEAN	Boolean	Column(Boolean, default=True)
DATETIME	DateTime	Column(DateTime, default=datetime.now)
FLOAT	Float	Column(Float)

컬럼 옵션

from sqlalchemy import Column, Integer, String, Boolean, DateTime
from datetime import datetime

class User(Base):
    __tablename__ = 'users'
    
    id = Column(Integer, primary_key=True, autoincrement=True)  # 자동 증가
    username = Column(String(50), nullable=False)                # NOT NULL
    email = Column(String(255), unique=True)                     # UNIQUE
    is_active = Column(Boolean, default=True)                    # 기본값 설정
    created_at = Column(DateTime, default=datetime.now)          # 생성 시간 자동 기록

---

8) Session 사용법

session은 DB와의 대화 창구이다.

from sqlalchemy.orm import Session

# 방법 1: with 문 사용 (권장)
with Session(engine) as session:
    # 작업 수행
    pass
    # with 블록 종료 시 자동으로 session 닫힘

######################################

# 방법 2: 직접 생성/종료
session = Session(engine)
try:
    # 작업 수행
    pass
finally:
    session.close()

---

9) 정리 ✅

SQLAlchemy는 “객체로 작업하면 SQL을 만들어주는 ORM”이고, 기본 뼈대는 Engine → Base/Model → Session → CRUD다.

• Engine: DB 연결 정보
• Base/Model: 테이블 매핑 규칙
• Session: 대화창구 + 변경사항 추적
• commit(): 실제 DB 반영 트리거
• rollback(): 예외 시 안전벨트

다음 파트에서 보통 이어지는 주제는 relationship(), lazy/eager loading, 세션 생명주기, 트랜잭션 전략이다.
이걸 배우면 “점(.) 접근이 왜 위험할 수도 있는지”가 완전히 정리된다.