파이썬 DB-API 2.0 Connection Cursor paramstyle 예외 계층 완벽 가이드

🔗 Connection 객체 이해하기

파이썬 DB-API 2.0에서 Connection 객체는 데이터베이스와 애플리케이션을 이어주는 핵심 통로입니다.
이 객체를 생성해야 SQL 명령을 실행하거나 트랜잭션을 관리할 수 있으며, 보통 connect() 함수로 생성합니다.
데이터베이스에 따라 함수명과 매개변수는 다를 수 있지만, 공통적으로 DB-API 2.0 규격을 따릅니다.

Connection은 단순히 연결 상태를 유지하는 것 이상의 역할을 합니다.
SQL 실행을 위한 Cursor 객체 생성, commit()과 rollback()을 통한 트랜잭션 제어, 연결 해제를 위한 close() 등 데이터의 안정성과 무결성을 보장하는 기능을 제공합니다.

🔑 트랜잭션 관리

대부분의 데이터베이스 작업은 트랜잭션 단위로 이루어집니다.
Connection 객체는 이러한 트랜잭션을 명시적으로 관리할 수 있도록 commit()과 rollback() 메서드를 제공합니다.
이를 통해 데이터 변경 작업을 확정하거나 취소할 수 있으며, 이는 데이터 안정성 확보에 매우 중요합니다.

📌 Connection 사용 예시

import sqlite3

# 데이터베이스 연결
conn = sqlite3.connect("example.db")

# 커서 생성
cur = conn.cursor()

# SQL 실행
cur.execute("CREATE TABLE IF NOT EXISTS users(id INTEGER PRIMARY KEY, name TEXT)")

# 트랜잭션 반영
conn.commit()

# 연결 종료
conn.close()

🛠️ Cursor의 역할과 활용법

DB-API 2.0에서 Cursor 객체는 SQL 문장을 실행하고 그 결과를 관리하는 핵심 도구입니다.
Connection으로 데이터베이스와 연결된 후, 실제 쿼리를 실행하는 작업은 Cursor가 담당합니다.
즉, Cursor는 데이터베이스와의 대화창 역할을 하며, SELECT, INSERT, UPDATE, DELETE 등 모든 SQL 실행의 주체라고 할 수 있습니다.

Cursor는 단순히 SQL을 실행하는 것뿐만 아니라 결과 집합을 가져오는 다양한 메서드를 제공합니다.
예를 들어 fetchone(), fetchall(), fetchmany() 등을 통해 원하는 만큼 데이터를 읽어올 수 있습니다.
또한 반복문과 함께 사용하면 대용량 데이터도 효율적으로 처리할 수 있습니다.

📥 SQL 실행과 결과 조회

Cursor를 사용하면 SQL 실행 후 결과를 손쉽게 가져올 수 있습니다.
SELECT문을 실행하면 Cursor는 결과 집합을 내부 버퍼에 보관하고, fetch 메서드를 통해 데이터를 하나씩 혹은 일괄적으로 꺼낼 수 있습니다.
이 방식은 메모리 사용을 효율적으로 관리하는 데 큰 장점이 있습니다.

📌 Cursor 사용 예시

import sqlite3

conn = sqlite3.connect("example.db")
cur = conn.cursor()

# 데이터 삽입
cur.execute("INSERT INTO users (name) VALUES (?)", ("홍길동",))

# 데이터 조회
cur.execute("SELECT * FROM users")
rows = cur.fetchall()

for row in rows:
    print(row)

conn.commit()
conn.close()

⚙️ paramstyle 종류와 차이점

DB-API 2.0은 데이터베이스 쿼리에서 파라미터를 안전하게 전달하기 위한 표준 형식을 정의합니다.
이를 paramstyle이라고 하며, 드라이버마다 지원하는 형식이 다를 수 있습니다.
paramstyle은 단순히 문법적인 차이만 있는 것이 아니라, SQL 인젝션을 예방하고 코드 가독성을 높이는 중요한 역할을 합니다.

대표적으로 다섯 가지 paramstyle이 있으며, 이를 이해하고 사용하는 것이 데이터베이스 프로그래밍에서 매우 중요합니다.
아래는 DB-API 2.0에서 정의한 paramstyle 종류와 특징입니다.

📝 paramstyle 종류

📌 paramstyle 활용 예시

# SQLite qmark 방식
cur.execute("SELECT * FROM users WHERE id = ?", (1,))

# MySQL format 방식
cur.execute("SELECT * FROM users WHERE id = %s", (1,))

# pyformat 방식
cur.execute("SELECT * FROM users WHERE id = %(id)s", {"id": 1})

🔌 예외 계층 구조 이해하기

DB-API 2.0은 데이터베이스 접근 중 발생할 수 있는 오류를 일관되게 처리하기 위해 예외 계층(Exception hierarchy)을 정의합니다.
이는 데이터베이스 드라이버마다 다른 오류 체계를 단일한 방식으로 다룰 수 있도록 만들어졌습니다.
즉, 코드에서 예외 처리를 할 때 특정 DB 모듈에 종속되지 않고 공통된 구조로 대응할 수 있다는 장점이 있습니다.

DB-API의 모든 예외 클래스는 StandardError를 상속하며, 대표적으로 Warning과 Error가 최상위 레벨에 위치합니다.
Error는 다시 세분화되어, 상황에 맞는 보다 구체적인 예외 처리를 가능하게 합니다.

📂 예외 계층 구조

• ⚠️Warning : 비치명적인 경고 메시지
• ❌Error : 모든 에러의 상위 클래스
• 🔑InterfaceError : 드라이버 인터페이스 관련 오류
• 📡DatabaseError : 데이터베이스와 관련된 일반 오류
• 🔒OperationalError : 접속 끊김, 트랜잭션 문제 등 운영 관련 오류
• 🗂️IntegrityError : 무결성 제약 조건 위반
• 💾ProgrammingError : SQL 문법 오류, 잘못된 파라미터 등
• 🧩NotSupportedError : 지원되지 않는 기능 호출 시

📌 예외 처리 예시

import sqlite3
from sqlite3 import DatabaseError, IntegrityError

try:
    conn = sqlite3.connect("example.db")
    cur = conn.cursor()
    cur.execute("INSERT INTO users (id, name) VALUES (1, '홍길동')")
    conn.commit()
except IntegrityError as e:
    print("무결성 제약 조건 위반:", e)
except DatabaseError as e:
    print("데이터베이스 오류:", e)
finally:
    conn.close()

💬 예외 계층을 잘 이해하면 상황별로 적절한 오류 처리가 가능해지고, 애플리케이션 안정성을 크게 높일 수 있습니다.

💡 DB-API 2.0을 활용한 실전 예제

앞서 살펴본 Connection, Cursor, paramstyle, 예외 계층 개념은 따로 떼어놓고 이해하기보다는 실제 코드에서 함께 활용해야 그 의미가 명확해집니다.
실제 애플리케이션에서 데이터베이스를 사용하는 전형적인 흐름은 다음과 같습니다:
데이터베이스 연결 → Cursor 생성 → SQL 실행 및 결과 처리 → 트랜잭션 확정 또는 취소 → 연결 종료.
아래 예제는 이러한 과정을 한눈에 보여줍니다.

🖥️ SQLite를 활용한 예제

import sqlite3
from sqlite3 import IntegrityError

try:
    # 1. 데이터베이스 연결
    conn = sqlite3.connect("example.db")
    cur = conn.cursor()

    # 2. 테이블 생성
    cur.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")

    # 3. 데이터 삽입 (paramstyle 사용)
    cur.execute("INSERT INTO users (name) VALUES (?)", ("홍길동",))

    # 4. 데이터 조회
    cur.execute("SELECT * FROM users")
    rows = cur.fetchall()
    for row in rows:
        print(row)

    # 5. 트랜잭션 확정
    conn.commit()

except IntegrityError as e:
    print("데이터 무결성 오류:", e)
finally:
    # 6. 연결 종료
    conn.close()

이 예제는 DB-API 2.0의 핵심 개념을 모두 포함합니다.
Connection으로 연결을 만들고, Cursor를 통해 SQL을 실행하며, 파라미터 바인딩에는 안전한 paramstyle을 사용합니다.
또한 예외 계층을 활용해 무결성 오류를 처리하고, 트랜잭션을 commit하여 데이터의 안정성을 보장합니다.

📌 실무 적용 팁

💬 DB-API 2.0은 단순히 데이터베이스 연결 도구가 아니라, 안정성과 확장성을 보장하는 프로그래밍 표준입니다. 이를 잘 이해하면 파이썬 기반의 데이터 처리 애플리케이션을 훨씬 더 강력하게 만들 수 있습니다.

❓ 자주 묻는 질문 (FAQ)