`can't adapt type 'UUID'` — uuid 파라미터를 넘기면 500

증상

psycopg2.ProgrammingError: can't adapt type 'UUID'

uuid.UUID 값이나 uuid[] 리스트를 파라미터로 넘긴 INSERT/SELECT가 죽고, 그 위의 엔드포인트가 500을 낸다. 같은 쿼리가 SQL 클라이언트에서는 잘 돈다.

원인

psycopg2는 uuid.UUID를 기본으로 어댑트하지 않는다. 문자열로 넘길 때는 되고, UUID 객체를 넘기는 순간 터진다. 배열이면 원소마다 같은 문제다.

해법

임포트 직후 한 번 등록한다.

import psycopg2.extras
psycopg2.extras.register_uuid()

프로세스당 한 번이면 된다. 커넥션마다 부르면 무해하지만 의미 없다.

검증

쿼리를 실제로 보내기 전에 mogrify로 바인딩 결과를 찍는다.

cur.mogrify("SELECT %s, %s", (uuid.uuid4(), [uuid.uuid4()]))
# b"SELECT '...'::uuid, ARRAY['...'::uuid]"   ← 이 꼴이면 등록된 것

★ 어댑터 등록은 임포트 직후 한 곳에서. 어떤 모듈에서는 되고 어떤 모듈에서는 안 되는 500은 등록 위치가 흩어져 있다는 뜻이다.

---

---