[Python] psycopg2에서 ALTER TABLE 실행하는 올바른 방법

데이터베이스 작업 중 테이블 구조를 변경해야 할 때, ALTER TABLE 명령을 사용하게 됩니다. 하지만 pandas.read_sql_query()로 이 명령을 실행하려고 하면 오류가 발생합니다. 이번 글에서는 그 이유와 함께, psycopg2를 사용해 ALTER TABLE을 올바르게 실행하는 방법을 정리했습니다.

1. 왜 pd.read_sql_query()로는 ALTER TABLE이 안 될까?

pandas.read_sql_query()는 SELECT 결과를 DataFrame으로 읽어오는 용도로 만들어졌습니다.
즉, 쿼리 실행 후 결과 집합을 반환해야 하는데, ALTER TABLE은 반환값이 없습니다.
따라서 아래와 같은 에러가 발생합니다.

pandas.io.sql.DatabaseError: Execution failed on sql 'ALTER TABLE ...': no results to fetch

이 함수는 데이터를 조회할 때만 사용해야 하고, 테이블 구조를 바꾸는 명령에는 적합하지 않습니다.

2. psycopg2에서 ALTER TABLE 실행하는 기본 방법

DDL(데이터 정의어) 명령은 cursor.execute()로 실행하는 것이 정석입니다.
아래는 PostgreSQL에 연결해 ALTER TABLE을 수행하는 기본 예시입니다.

import psycopg2
import pandas as pd

# PostgreSQL 연결
conn = psycopg2.connect(
    host="localhost",
    dbname="mydb",
    user="myuser",
    password="mypassword",
    port=5432
)

cur = conn.cursor()

# ALTER TABLE 실행
alter_sql = """
ALTER TABLE users
ADD COLUMN last_login TIMESTAMP;
"""
cur.execute(alter_sql)

# 변경사항 커밋
conn.commit()

print("테이블 변경 완료")

# 결과 확인 (SELECT만 pandas로 가능)
df = pd.read_sql_query("SELECT * FROM users LIMIT 5;", conn)
print(df.head())

# 연결 종료
cur.close()
conn.close()

3. 실행 시 주의할 점

1. conn.commit()은 필수
   • PostgreSQL은 트랜잭션 기반으로 작동하기 때문에, ALTER TABLE 같은 변경 명령 후 반드시 commit()을 호출해야 실제로 반영됩니다.
2. DDL은 반환값이 없다
   • read_sql_query()처럼 결과를 기대하는 함수는 사용할 수 없습니다.
3. 에러 처리 시 rollback() 필요
   • 명령 실행 중 오류가 발생하면 반드시 롤백해야 연결 상태가 복구됩니다.

   try:
       cur.execute("ALTER TABLE users ADD COLUMN age INTEGER;")
       conn.commit()
   except Exception as e:
       conn.rollback()
       print("에러 발생:", e)

4. ALTER TABLE과 SELECT 함께 쓰기

테이블 구조를 변경한 뒤 데이터를 확인하고 싶다면, 다음처럼 순차적으로 실행할 수 있습니다.

try:
    cur.execute("ALTER TABLE users ADD COLUMN status TEXT;")
    conn.commit()
except psycopg2.errors.DuplicateColumn:
    # 이미 컬럼이 있을 경우 예외 처리
    conn.rollback()

df = pd.read_sql_query("SELECT * FROM users;", conn)

5. 정리

작업 종류	사용 함수	예시
SELECT 결과를 DataFrame으로 읽기	pd.read_sql_query()	pd.read_sql_query("SELECT ...", conn)
ALTER / INSERT / UPDATE / CREATE 실행	cursor.execute()	cur.execute("ALTER TABLE ...")
변경 반영	conn.commit()	DDL 실행 후 필수
오류 복구	conn.rollback()	예외 발생 시 필수

6. 마무리 및 배운 점

pandas.read_sql_query()는 조회 전용 함수이므로, 스키마 변경이나 데이터 삽입 같은 명령에는 적합하지 않습니다.
psycopg2를 사용할 때는 cursor.execute()와 트랜잭션(commit/rollback)을 올바르게 관리해야 안전한 데이터베이스 작업이 가능합니다.

이 방식을 익혀두면 이후 테이블 변경, 데이터 마이그레이션, 자동화 스크립트 작성 등에서도 안정적으로 PostgreSQL을 제어할 수 있습니다.