This release is a pre-release and may not be stable for production use.
django-sqlalchemy-bridge
⚠️ 실험적 프로젝트입니다 (Experimental). API·동작·지원 범위가 예고 없이 바뀔 수 있고, 운영 환경에서 쓰는 것을 권하지 않습니다.
상태: 0.1 (알파). 첫 API(모델 →
sa.Table,execute,stream,bulk_update/bulk_insert,arun)를 담은 첫 릴리스입니다. 0.x 동안은 마이너 버전 사이에도 API가 바뀔 수 있으니 버전을 고정해 쓰세요.
Django가 연 연결과 트랜잭션 안에서 SQLAlchemy 2.x Core 표현식(대량 DML, CTE, 윈도 함수, 복잡한 조인)을 쓰게 해 주는 라이브러리입니다.
왜 쓰나
표현력 때문입니다. Django ORM 으로 쓰기 어려운 SQL(재귀 CTE, 여러 CTE, INSERT … ON CONFLICT … RETURNING, UPDATE … FROM, INSERT … SELECT, PostgreSQL 의 LATERAL·DISTINCT ON·데이터를 바꾸는 CTE)을 raw SQL 문자열 대신 SQLAlchemy 식으로 씁니다. 그러면서도 연결·트랜잭션·값 변환은 Django 의 것을 그대로 씁니다. atomic() 안에서 ORM 쿼리와 섞여 돌고, 결과의 datetime·Decimal·JSON 은 ORM 이 읽은 값과 같습니다. raw SQL 과 달리 테이블·컬럼 이름이 모델에서 나오므로 오타가 실행 전에 드러나고, 백엔드마다 SQL 을 따로 쓰지 않아도 되는 경우가 많습니다.
성능은 목적이 아닙니다. 대량 쓰기에서는 따라옵니다. bulk_update는 Django bulk_update보다 한 자릿수 이상, bulk_insert는 Django bulk_create보다 빠릅니다(PostgreSQL 에서 25% 안팎, method="copy"면 2배 이상). 같은 SQL 이면 실행 시간이 DB 에서 정해져 ORM 과 거의 같고(아래 "성능과 메모리"), ORM 으로는 쿼리를 더 보내거나 행을 파이썬으로 옮겨야 하는 요청에서 빨라집니다. 반대로 ORM 이 더 빠른 요청도 있습니다(아래 "같은 요청, 두 구현").
언제 ORM 을 쓰나. ORM 으로 자연스럽게 써지는 쿼리, 한 행씩 읽고 쓰는 CRUD, signal·save()·필드 default·검증이 따라와야 하는 쓰기는 ORM 을 쓰세요. 브리지의 쓰기는 모델 계층을 거치지 않습니다(아래 "대량 쓰기"의 경고). 자세한 경우는 "브리지가 도움이 안 되는 경우"에 있습니다.
예제
아래 코드는 테스트(tests/test_examples.py)에서 그대로 돌고, README 가 그 코드와 어긋나면 테스트가 실패합니다. 모델은 작은 상점(tests/testapp/models.py의 Category·Product·Sale·DailyStock·PriceChange)이고, 테스트 파일에는 LATERAL·DISTINCT ON·여러 CTE·윈도 함수·INSERT … SELECT·ON CONFLICT DO NOTHING·데이터를 바꾸는 CTE 예제가 더 있습니다. 모든 예제는 SQLite·PostgreSQL·MySQL·Oracle 에서 돌고, 그 DB 에 없는 문법(PostgreSQL 전용 DISTINCT ON 등, MySQL·Oracle 에 없는 ON CONFLICT·RETURNING, Oracle 에 없는 UPDATE … FROM)만 건너뜁니다. 예제 코드의 import 는 import datetime, from zoneinfo import ZoneInfo, import sqlalchemy as sa, from django.db import connection, transaction, from sqlalchemy.dialects import mysql, postgresql, sqlite, from django_sqlalchemy_bridge import execute, table_for입니다.
재귀 CTE: 카테고리 하나의 하위 트리를 깊이와 함께.
categories = table_for(Category)
tree = (
sa.select(categories.c.id, categories.c.name, sa.literal_column("0").label("depth"))
.where(categories.c.id == sa.bindparam("root"))
.cte("tree", recursive=True)
)
tree = tree.union_all(
sa.select(categories.c.id, categories.c.name, tree.c.depth + 1).join(tree, categories.c.parent_id == tree.c.id)
)
subtree = sa.select(tree.c.name, tree.c.depth).order_by(tree.c.depth, tree.c.name)
rows = execute(subtree, {"root": clothes.pk})
# [("의류", 0), ("상의", 1), ("하의", 1)]
업서트: 같은 (상품, 날짜) 행이 있으면 수량을 더하고, 결과 행을 돌려받습니다. ON CONFLICT는 백엔드마다 SQLAlchemy 구성자가 달라 vendor 로 고릅니다. RETURNING의 날짜·시각도 ORM 처럼 변환됩니다.
daily_stock = table_for(DailyStock)
insert = postgresql.insert if connection.vendor == "postgresql" else sqlite.insert
stmt = insert(daily_stock) # 컬럼은 아래 params 가 정한다
stmt = stmt.on_conflict_do_update(
index_elements=[daily_stock.c.product_id, daily_stock.c.day],
set_={"quantity": daily_stock.c.quantity + stmt.excluded.quantity, "counted_at": stmt.excluded.counted_at},
).returning(daily_stock.c.day, daily_stock.c.quantity, daily_stock.c.counted_at)
counted_at = datetime.datetime(2026, 10, 26, 18, tzinfo=ZoneInfo("Asia/Seoul"))
params = {"product_id": shirt.pk, "day": counted_at.date(), "quantity": 3, "counted_at": counted_at}
with transaction.atomic():
rows = execute(stmt, params)
# [(datetime.date(2026, 10, 26), 10, datetime.datetime(2026, 10, 26, 9, 0, tzinfo=datetime.timezone.utc))]
MySQL 에는 ON CONFLICT도 RETURNING도 없어 같은 업서트를 ON DUPLICATE KEY UPDATE로 쓰고 rowcount 를 받습니다(넣은 행은 1, 갱신한 행은 2 로 셉니다).
daily_stock = table_for(DailyStock)
stmt = mysql.insert(daily_stock) # 컬럼은 아래 params 가 정한다
stmt = stmt.on_duplicate_key_update(
quantity=daily_stock.c.quantity + stmt.inserted.quantity, counted_at=stmt.inserted.counted_at
)
counted_at = datetime.datetime(2026, 10, 26, 18, tzinfo=ZoneInfo("Asia/Seoul"))
params = {"product_id": shirt.pk, "day": counted_at.date(), "quantity": 3, "counted_at": counted_at}
with transaction.atomic():
count = execute(stmt, params) # 2: MySQL 은 갱신한 행을 2, 넣은 행을 1 로 센다
UPDATE … FROM: 따로 올려 둔 가격표를 바뀐 행에만 적용하고 바뀐 행을 돌려받습니다(SQLite 3.33+, PostgreSQL). MySQL 에서는 .returning() 없이 같은 문장이 UPDATE products, changes SET …로 컴파일되어 rowcount 를 돌려줍니다.
products = table_for(Product)
changes = table_for(PriceChange)
stmt = (
sa.update(products)
.where(products.c.sku == changes.c.sku, products.c.price != changes.c.price)
.values(price=changes.c.price)
.returning(products.c.sku, products.c.price)
)
changed = execute(stmt) # [("SHIRT", Decimal("27.50"))]
aldjemy 와의 관계. aldjemy가 같은 문제를 먼저 풀었지만, SQLAlchemy 내부 비공개 풀 구조에 기대 Django 연결을 공유하는 탓에 SQLAlchemy 2 미만에 묶여 있고, Django 6.0부터는 모델 변환 단계에서도 깨집니다. 이 프로젝트는 SQLAlchemy 에 연결을 넘기지 않고 Django 커서로 실행합니다(아래 "설계 원칙").
같은 요청, 두 구현
실제로 나올 법한 요청 하나를 Django ORM 만으로 푼 코드와 브리지로 푼 코드를 나란히 놓고 쿼리 수와 시간을 쟀습니다. ORM 쪽은 Django 5.2·6.1 에서 되는 가장 나은 방법으로 썼습니다. 여섯 요청 가운데 넷을 싣고, 여섯 개 전부와 ORM 의 다른 구현, SQLite 수치, 메모리는 docs/comparisons.md에 있습니다. 코드는 tests/comparisons.py에서 그대로 옮겼고(두 구현의 결과·남긴 행·쿼리 수를 tests/test_comparisons.py가 SQLite·PostgreSQL·MySQL·Oracle 에서 확인), 표는 아래 환경의 GitHub Actions 러너에서 잰 결과 파일로 만듭니다(측정 방법은 "성능과 메모리"와 같고, 쿼리 수는 SAVEPOINT 를 뺀 값). 브리지 코드의 categories·products·sales·daily_stock·price_changes·archive는 모델마다 table_for(Model)입니다.
PostgreSQL 18.6 (Debian 18.6-1.pgdg13+2) · Python 3.12.3 · Django 6.1.2 · SQLAlchemy 2.1.6 · psycopg 3.3.6 · django-pgbulk 3.3.0 · django-cte 4.0.0 · Intel(R) Xeon(R) Platinum 8370C CPU @ 2.80GHz (4코어, 메모리 16 GiB) · Linux-6.17.0-1022-azure-x86_64-with-glibc2.39 · 반복 5회(+예열 1회) 중 최솟값
카테고리 하위 트리의 매출 합계
카테고리 하나 아래 모든 카테고리의 판매 합계. ORM 은 트리를 걸을 재귀 쿼리가 없어 카테고리를 한 단계씩 내려가거나(깊이만큼 쿼리), 아래처럼 카테고리 전체를 읽어 파이썬에서 걷습니다. 브리지는 재귀 CTE 쿼리 하나입니다.
def subtree_revenue_orm_python(root_id):
# 카테고리 전체의 (id, parent_id) 를 한 번에 읽어 파이썬에서 트리를 걷는다
children = defaultdict(list)
for category_id, parent_id in Category.objects.values_list("id", "parent_id"):
children[parent_id].append(category_id)
ids, stack = [], [root_id]
while stack:
ids.append(stack.pop())
stack += children[ids[-1]]
total = Sale.objects.filter(product__category_id__in=ids).aggregate(total=Sum("amount"))["total"]
return total or Decimal("0")
tree = sa.select(categories.c.id).where(categories.c.id == sa.bindparam("root")).cte("tree", recursive=True)
tree = tree.union_all(sa.select(categories.c.id).join(tree, categories.c.parent_id == tree.c.id))
subtree_revenue = (
sa.select(sa.func.coalesce(sa.func.sum(sales.c.amount), 0))
.join(products, products.c.id == sales.c.product_id)
.where(products.c.category_id.in_(sa.select(tree.c.id)))
)
def subtree_revenue_bridge(root_id):
[(total,)] = execute(subtree_revenue, {"root": root_id})
return total
| 깊이 3 쿼리 | 깊이 3 시간 (ms) | 깊이 5 쿼리 | 깊이 5 시간 (ms) | 깊이 7 쿼리 | 깊이 7 시간 (ms) | 깊이 7 tracemalloc 피크 (MiB) | |
|---|---|---|---|---|---|---|---|
| ORM: 한 단계에 쿼리 하나씩 | 4 | 3.24 | 6 | 9.56 | 8 | 90.1 | 2.3 |
| ORM: 카테고리 전체를 읽어 파이썬에서 | 2 | 1.87 | 2 | 5.58 | 2 | 62.1 | 3.7 |
| 브리지: 재귀 CTE | 1 | 0.98 | 1 | 2.36 | 1 | 25.6 | 0.0 |
결과 파일: bench/results/2026-10-26-postgres-compare.json
브리지가 깊이 5·7 에서 파이썬으로 걷는 ORM 보다 2.4배 빠르고(5.58→2.36 ms, 62.1→25.6 ms), 한 단계씩 내려가는 ORM 보다 3.5배 이상 빠릅니다.
가격표로 바뀐 상품만 갱신하고 바뀐 행 반환
ORM 의 update()는 행을 돌려주지 않아 바뀔 행을 먼저 잠가 읽고 상관 서브쿼리로 UPDATE 합니다. 브리지는 UPDATE … FROM … RETURNING 한 문장입니다(PostgreSQL·SQLite).
def apply_prices_orm_subquery():
# 바뀔 행을 먼저 읽고(UPDATE 는 행을 돌려주지 않는다) 상관 서브쿼리 UPDATE 한 번
new_price = PriceChange.objects.filter(sku=OuterRef("sku")).values("price")
differs = PriceChange.objects.filter(sku=OuterRef("sku")).exclude(price=OuterRef("price"))
with transaction.atomic():
targets = Product.objects.filter(Exists(differs))
changed = list(targets.select_for_update().annotate(new=Subquery(new_price)).values_list("sku", "new"))
targets.update(price=Subquery(new_price))
return sorted(changed)
apply_prices = (
sa.update(products)
.where(products.c.sku == price_changes.c.sku, products.c.price != price_changes.c.price)
.values(price=price_changes.c.price)
.returning(products.c.sku, products.c.price)
)
def apply_prices_bridge(): # UPDATE ... FROM ... RETURNING: PostgreSQL, SQLite
return sorted(execute(apply_prices))
| 상품 1,000 쿼리 | 상품 1,000 시간 (ms) | 상품 10,000 쿼리 | 상품 10,000 시간 (ms) | 상품 10,000 tracemalloc 피크 (MiB) | |
|---|---|---|---|---|---|
ORM: 읽기 + Subquery UPDATE |
2 | 10.5 | 2 | 82.5 | 1.4 |
ORM: 읽기 + bulk_update(batch_size=1000) |
2 | 66.9 | 6 | 765 | 11.0 |
브리지: UPDATE … FROM … RETURNING |
1 | 5.82 | 1 | 54.5 | 1.1 |
결과 파일: bench/results/2026-10-26-postgres-compare.json
브리지가 서브쿼리 ORM 보다 1.5~1.8배 빠릅니다(상품 10,000개 중 5,000개 변경에서 82.5→54.5 ms). 모델로 읽어 bulk_update()하는 흔한 방법보다는 14배 빠릅니다(765 ms).
오래된 판매를 보관 테이블로 옮기기
ORM 에는 INSERT … SELECT가 없어 행을 파이썬으로 읽어 모델을 만들고 bulk_create()한 뒤 지웁니다. 브리지는 INSERT … SELECT와 DELETE 두 문장이라 행이 파이썬을 거치지 않습니다(PostgreSQL 에서는 데이터를 바꾸는 CTE 한 문장도 됩니다).
def archive_sales_orm(cutoff):
# 읽어서 모델로 만들고 bulk_create, 그리고 DELETE
with transaction.atomic():
old = list(Sale.objects.select_for_update().filter(sold_at__lt=cutoff))
SaleArchive.objects.bulk_create(
SaleArchive(id=s.id, product_id=s.product_id, sold_at=s.sold_at, quantity=s.quantity, amount=s.amount)
for s in old
)
Sale.objects.filter(sold_at__lt=cutoff).delete()
return len(old)
columns = ["id", "product_id", "sold_at", "quantity", "amount"]
is_old = sales.c.sold_at < sa.bindparam("cutoff")
copy_old = sa.insert(archive).from_select(columns, sa.select(*[sales.c[name] for name in columns]).where(is_old))
delete_old = sa.delete(sales).where(is_old)
def archive_sales_bridge(cutoff): # INSERT ... SELECT 와 DELETE: 모든 백엔드
with transaction.atomic():
moved = execute(copy_old, {"cutoff": cutoff})
execute(delete_old, {"cutoff": cutoff})
return moved
| 판매 10,000 쿼리 | 판매 10,000 시간 (ms) | 판매 100,000 쿼리 | 판매 100,000 시간 (ms) | 판매 100,000 tracemalloc 피크 (MiB) | |
|---|---|---|---|---|---|
ORM: 읽기 + bulk_create() + delete() |
3 | 153 | 3 | 1,799 | 79.1 |
브리지: INSERT … SELECT + DELETE |
2 | 15.7 | 2 | 157 | 0.0 |
| 브리지: 데이터를 바꾸는 CTE | 1 | 17.1 | 1 | 173 | 0.0 |
결과 파일: bench/results/2026-10-26-postgres-compare.json
브리지가 10~11배 빠르고(판매 100,000건 중 약 절반을 옮기는 데 1,799→157 ms), 클라이언트 메모리를 거의 쓰지 않습니다(tracemalloc 피크 79.1 MiB 대 0.0 MiB).
일별 재고 업서트 후 결과 반환: ORM 이 나은 경우
(상품, 날짜)마다 센 수량을 더하고 없으면 넣은 뒤 결과 행을 돌려받습니다. ORM bulk_create(update_conflicts=True)는 기존 값에 더하지 못해 있는 행을 잠가 읽고 파이썬에서 더한 뒤 한 번에 씁니다. 브리지는 여러 행 VALUES의 INSERT … ON CONFLICT DO UPDATE … RETURNING 한 문장입니다.
def add_stock_orm_bulk(counts):
# 있는 행을 잠가 읽고 파이썬에서 더한 뒤 INSERT ... ON CONFLICT DO UPDATE 한 번으로 쓴다
with transaction.atomic():
have = DailyStock.objects.select_for_update().filter(
product_id__in={c["product_id"] for c in counts}, day__in={c["day"] for c in counts}
)
quantity = {(s.product_id, s.day): s.quantity for s in have}
rows = [
DailyStock(**{**c, "quantity": quantity.get((c["product_id"], c["day"]), 0) + c["quantity"]})
for c in counts
]
DailyStock.objects.bulk_create(
rows, update_conflicts=True, unique_fields=["product", "day"], update_fields=["quantity", "counted_at"]
)
return sorted((r.product_id, r.day, r.quantity, r.counted_at) for r in rows)
def add_stock_bridge(counts): # ON CONFLICT + RETURNING: PostgreSQL, SQLite
insert = postgresql.insert if connection.vendor == "postgresql" else sqlite.insert
stmt = insert(daily_stock).values(counts)
stmt = stmt.on_conflict_do_update(
index_elements=[daily_stock.c.product_id, daily_stock.c.day],
set_={"quantity": daily_stock.c.quantity + stmt.excluded.quantity, "counted_at": stmt.excluded.counted_at},
).returning(daily_stock.c.product_id, daily_stock.c.day, daily_stock.c.quantity, daily_stock.c.counted_at)
return sorted(execute(stmt))
| 100행 쿼리 | 100행 시간 (ms) | 1,000행 쿼리 | 1,000행 시간 (ms) | 5,000행 쿼리 | 5,000행 시간 (ms) | 5,000행 tracemalloc 피크 (MiB) | |
|---|---|---|---|---|---|---|---|
ORM: 행마다 update(), 없으면 create() |
151 | 81.0 | 1,501 | 801 | 7,501 | 4,241 | 3.5 |
ORM: 잠가 읽기 + bulk_create(update_conflicts=True) |
2 | 5.87 | 2 | 38.2 | 2 | 179 | 6.9 |
브리지: ON CONFLICT DO UPDATE … RETURNING |
1 | 8.48 | 1 | 72.9 | 1 | 407 | 16.2 |
결과 파일: bench/results/2026-10-26-postgres-compare.json
쿼리는 브리지가 하나 적지만 ORM bulk_create()가 1.4~2.3배 빠릅니다(5,000행에서 179 대 407 ms). 입력마다 문장이 달라 브리지는 호출마다 행 수 × 컬럼 수만큼 bind 가 있는 VALUES 문장을 SQLAlchemy 로 새로 컴파일하기 때문입니다(로컬 프로파일에서 가장 큰 비용이 컴파일이었습니다). 브리지의 이점은 갱신이 한 문장이라 읽기와 쓰기 사이에 잠금이 필요 없다는 것과, 행마다 update()·create()하는 흔한 방법(5,000행에 쿼리 7,501개, 4,241 ms)보다 10배 빠르다는 데 있습니다.
AI 코딩 에이전트에게
이 라이브러리는 새로 나와 AI 모델의 학습 데이터에 거의 없습니다. 그래서 설치된 패키지 안에 에이전트용 요약 django_sqlalchemy_bridge/llms.txt(저장소 루트 llms.txt와 같은 내용)를 넣어 두었습니다. 언제 쓰고 언제 ORM 을 쓰는지, 꼭 지킬 것(SQLAlchemy Engine·Session을 만들지 않기, 쓰기가 signal·save()를 우회한다는 것, bindparam 재사용), 지원하지 않는 것, 공개 API 시그니처, 위 예제의 요약이 들어 있습니다. 전 세계 사용자의 에이전트가 읽는 파일이라 영어로 씁니다. 내 프로젝트의 AGENTS.md나 CLAUDE.md에 아래를 붙여 두면 에이전트가 설치된 버전의 안내를 읽습니다.
## django-sqlalchemy-bridge
This project runs SQLAlchemy Core statements on Django's connections and transactions with django-sqlalchemy-bridge.
Before writing code with it, read and follow the guide of the installed version (prefix `uv run` in a uv project):
`python -c "import importlib.resources as r; print(r.files('django_sqlalchemy_bridge').joinpath('llms.txt').read_text('utf-8'))"`
Do not create a SQLAlchemy `Engine` or `Session`. Writes through the bridge skip signals and `save()`.
설계 원칙
- 연결과 트랜잭션은 Django가 관리합니다. SQLAlchemy는 SQL을 만들고 컴파일하는 데만 쓰고, 실행은 항상 Django 커서로 합니다. 그래서
atomic(), savepoint,on_commit,execute_wrapper,assertNumQueries, Django 연결 풀, PgBouncer 설정이 그대로 동작합니다.- SQLAlchemy
Connection·ORMSession은 Django 커서를 감싼 가짜 DBAPI 연결 위에서도 쓰지 않습니다(#39 에서 실험). 그 경로에서는 SQLAlchemy 의commit()·rollback()·begin()이 에러 없이 아무 일도 하지 않고, SQLAlchemy 타입 변환이 돌아 시간대가 9시간 밀리거나 Enum 이 이름으로 저장되며(SQLite 에서는 Django 가 쓴 datetime 을 읽지도 못함), dialect 의 연결 훅이 Django 연결을 바꿉니다(SQLite 의FLOOR·REGEXP함수 교체, PostgreSQL notice handler 누적). Oracle 은 첫 연결부터 실패합니다.
- SQLAlchemy
- SQLAlchemy 공개 API를 우선합니다. 공개 API만으로 안 되는 부분(외부에서 받은 행으로 SQLAlchemy
Result를 만드는 경로)은 어댑터 모듈 한 곳에 가두고, 지원하는 SQLAlchemy 버전 범위를 좁게 고정해 CI로 지킵니다. - 테이블 구조의 기준은 Django 모델 하나입니다.
sa.Table은 Django 모델에서 만들고, 마이그레이션은 Django가 맡습니다. - 값 변환은 Django 필드를 따릅니다. 컬럼과 비교하는 값은 ORM 조회(
filter())처럼, 쓰는 값은 ORM 저장처럼(get_db_prep_save), 읽을 때는 Django ORM이 쓰는 변환기를 거칩니다. 그래서 JSON·UUID·시간대가 있는 datetime·Decimal·Enum이 ORM과 똑같이 왕복합니다. (SQLAlchemy 타입 변환을 그대로 쓰면 SQLite에서 시간이 9시간 밀리거나 Enum이 값 대신 이름으로 저장되는 문제가 있어 피합니다.) - 경계를 드러냅니다. 브리지로 쓴 내용은 Django signal을 발생시키지 않습니다. API 이름과 문서에 이 점을 분명히 적습니다.
모델에서 테이블 만들기
import sqlalchemy as sa
from django_sqlalchemy_bridge import assert_table_matches, table_for
from shop.models import Order
orders = table_for(Order) # 모델마다 한 번 만들고 캐시, 공용 MetaData 하나
stmt = sa.select(orders.c.id).where(orders.c.status == "paid")
# 테스트에서: 만든 테이블이 현재 모델·실제 DB 와 어긋나면 차이를 모두 나열하며 실패
assert_table_matches(Order, check_db=True)
- 테이블명은
db_table, 컬럼명은db_column(FK 는<이름>_id)을 따르고, PK·nullable·FK 대상 컬럼을 반영합니다. - 각
Column.info["django_field"]에 원래 Django 필드가,Table.info["django_model"]에 모델이 들어 있습니다. 컬럼 타입은 아래 표의 SQLAlchemy 타입을 감싼FieldType(TypeDecorator)이고column.type.impl이 표의 타입,column.type.field가 Django 필드입니다. SQLAlchemy 타입은 SQL 컴파일에만 쓰고, 값 변환은 Django 필드가 맡습니다(아래 "실행하기"). compare_table(model, table=None, check_db=False)는 차이를Difference(source, kind, column, expected, actual)리스트로 돌려줍니다. 모델과는 테이블명·컬럼·타입(FieldType이면 감싼 타입)·nullable·PK·FK 를, 실제 DB 와는 컬럼 유무·nullable·컬럼 타입을 비교합니다. 타입은 모델 필드의db_type()(FK 는 대상 컬럼 타입)과 DB 컬럼 타입을 같은 표기로 맞춘 뒤 비교하고, 다르면Difference("db", "type", 컬럼, DB 타입, 모델이 바라는 타입)을 냅니다(예:"character varying(50)"대"character varying(100)").- PostgreSQL:
format_type()이 주는 이름으로 맞춥니다(varchar→character varying,serial·int4→integer,timestamptz→timestamp with time zone,decimal→numeric등). varchar 길이와numeric(p,s)정밀도까지 비교합니다. - SQLite: 테이블에 선언된 타입 텍스트를 대소문자·공백만 맞춰 비교합니다. Django 가 만든 테이블은 선언 타입이 곧
db_type()입니다. Django 가DecimalField를 정밀도 없이decimal로 선언하므로 SQLite 에서는 decimal 정밀도 차이를 잡지 못하고, 손으로 만든 테이블이 다른 동의어(INT등)를 썼다면 타입 차이로 보고합니다. - MySQL:
information_schema.columns의COLUMN_TYPE과 맞춥니다(integer→int,bool→tinyint(1),numeric→decimal,double precision·real→double,AUTO_INCREMENT와 정수 표시 폭int(11)은 뗌). varchar 길이,decimal(p,s)정밀도,datetime(6)의 소수 자릿수,unsigned까지 비교합니다. - 그 밖의 백엔드(MariaDB: JSON 이
longtext, UUID 가 고유 타입. Oracle: 데이터 사전이db_type()과 다르게 씀, 예를 들어DOUBLE PRECISION을FLOAT(126)으로)에서는 타입을 비교하지 않습니다. - Oracle 에서는 컬럼 이름을 Django 가 실제로 만든 이름(대문자, 30자를 넘으면 해시로 줄임)으로 맞춰 보고, nullable 은 Django 스키마 편집기의 규칙대로 봅니다. Oracle 은 빈 문자열을
NULL로 저장하므로 Django 가 빈 문자열을 받는 필드(CharField·TextField등, PK 제외)를null=False여도 NULL 허용 컬럼으로 만들고,compare_table도 그 컬럼을 NULL 허용으로 기대합니다.
- PostgreSQL:
- 테이블은 모델에서 만들고 어느 DB 에도 묶이지 않습니다. 어느 DB 에서 실행할지는 호출의
using이 정합니다(아래 "다중 DB"). forget_table(model)은 캐시와 공용MetaData에서 테이블을 지웁니다. 테스트(isolate_apps등)에서 동적 모델을 정리하는 용도입니다.
지원 필드
Django 필드 (get_internal_type() 기준) |
SQLAlchemy 타입 |
|---|---|
AutoField, IntegerField, PositiveIntegerField |
Integer |
BigAutoField, BigIntegerField, PositiveBigIntegerField |
BigInteger |
SmallAutoField, SmallIntegerField, PositiveSmallIntegerField |
SmallInteger |
CharField(EmailField·URLField 포함), SlugField, FileField(ImageField 포함), FilePathField |
String(max_length) |
GenericIPAddressField |
String(39) |
TextField |
Text |
BooleanField |
Boolean |
DecimalField |
Numeric(max_digits, decimal_places) |
FloatField |
Float |
DateField / TimeField |
Date / Time |
DateTimeField |
DateTime(timezone=USE_TZ) |
DurationField |
Interval |
UUIDField |
Uuid |
JSONField |
postgresql.JSONB (SQLite·MySQL·Oracle 에서는 JSON 으로 컴파일) |
BinaryField |
LargeBinary |
ForeignKey, OneToOneField |
대상 컬럼의 타입 + ForeignKey |
choices가 있는 필드는 바탕 필드의 타입을 그대로 씁니다.JSONField는postgresql.JSONB().with_variant(sa.JSON(), "sqlite", "oracle")에 MySQL·MariaDB 용JSON변형을 붙인 타입입니다(SQLAlchemy 2.0 의 Oracle dialect 에는 JSON 이 없어 2.0 에서는 Oracle 변형을 붙이지 않습니다). 연산자(contains()·has_key()등)는 dialect 를 고르기 전, 식을 만들 때의 타입에서 나오므로 기본 타입이JSONB여야 PostgreSQL 연산자가 열립니다(sa.JSON기본에 PostgreSQL 변형만 붙이면contains()가 조용히LIKE가 됩니다). 그래서compare_table은 직접 만든 테이블의sa.JSON()컬럼을 타입 차이로 보고합니다.ManyToManyField와 역관계는 컬럼이 아니므로 건너뜁니다(중간 테이블 모델은 따로table_for할 수 있습니다). 다중 테이블 상속의 자식 테이블에는 자기 컬럼과<부모>_ptr_id만 들어갑니다. 복합 PK(CompositePrimaryKey)를 반영합니다.- 위 표에 없는 필드가 DB 컬럼을 가지면(예: PostgreSQL
ArrayField, 직접 만든 필드) 조용히 넘기지 않고UnsupportedFieldError를 냅니다.
실행하기
import sqlalchemy as sa
from django.db import transaction
from django_sqlalchemy_bridge import execute, execute_result, table_for
from shop.models import Order
orders = table_for(Order)
with transaction.atomic(): # 브리지 쿼리도 이 트랜잭션 안에서 돈다
rows = execute(sa.select(orders.c.id, orders.c.paid_at).where(orders.c.status == "paid"))
# [(1, datetime.datetime(2026, 10, 25, 0, 30, tzinfo=datetime.timezone.utc)), ...]
n = execute(sa.update(orders).where(orders.c.id.in_([1, 2])).values(status="shipped")) # rowcount
stmt = sa.update(orders).where(orders.c.id == sa.bindparam("pk")).values(status=sa.bindparam("s"))
execute(stmt, [{"pk": 1, "s": "paid"}, {"pk": 2, "s": "void"}]) # cursor.executemany
result = execute_result(sa.select(orders.c.id, orders.c.status)) # SQLAlchemy Result (옵트인)
for row in result.mappings():
...
-
execute(stmt, params=None, *, using="default")는connections[using]의 vendor에 맞는 SQLAlchemy dialect(SQLite, PostgreSQL+psycopg, MySQL·MariaDB+mysqlclient, Oracle+oracledb)로 컴파일하고 Django 커서로 실행합니다. 그래서atomic()·savepoint·on_commit·execute_wrapper·CaptureQueriesContext·assertNumQueries가 ORM 쿼리와 똑같이 적용됩니다. -
반환 형태: 행을 돌려주는 문장(
SELECT,RETURNING)은 튜플 리스트, 그 밖의 문장은 커서의 rowcount(정수)입니다.params에 매핑을 넘기면bindparam()값(그리고insert(table)처럼 값이 없는 INSERT의 컬럼)을 채우고, 매핑의 시퀀스를 넘기면cursor.executemany()로 실행합니다(이때RETURNING은 받지 않습니다). -
execute_result(stmt, params=None, *, using="default")는 같은 행을 SQLAlchemyResult로 줍니다(row.name,row._mapping,.mappings(),.scalars()). 행을 모두 가져와 변환한 뒤의Result입니다. 외부 행으로Result를 만드는 공개 API가 없어 이 부분만_sa_result.py한 곳에서 비공개 API를 씁니다. 키는 DB 가 알려 주는 컬럼 이름입니다. Oracle 은 이름을 대문자(브리지가 Django 식으로 쓴 이름)로 돌려주므로, 문장의 컬럼·라벨이면 문장을 만들 때의 이름(MixedCase, 30자 넘는 이름,label("Who"))으로 되돌리고, 그 밖의 이름(sa.text()의 컬럼,count_1같은 SQLAlchemy 익명 라벨)은 SQLAlchemy 의 Oracle dialect 처럼 전부 대문자면 소문자로, 아니면 받은 그대로 둡니다. 그래서text('SELECT name AS Plain, name AS "MixedCase" ...')의 키는plain·MixedCase입니다. 다른 DB 의 키는 바꾸지 않습니다(테스트로 확인). -
값 변환은 Django 필드 기준입니다. 컬럼과 비교(
==,!=,<,IN,BETWEEN등)하는 값은 ORM 조회filter(field=v)와 같은 경로(field.get_prep_value()뒤get_db_prep_value(prepared=True), FK 는 대상 필드)를, INSERT/UPDATE로 넣는 값은 ORM 저장과 같은field.get_db_prep_save()를, 컬럼을 고른 결과(라벨·max()처럼 컬럼 타입을 그대로 잇는 식 포함)는 ORM과 같은 변환기(connection.ops.get_db_converters()+ 필드 변환기)를 거칩니다. JSON·UUID·시간대 있는 datetime(SQLite에서도 UTC로 저장, 9시간 밀리지 않음)·Decimal·선택지(이름이 아니라 값)가 ORM과 똑같이 왕복합니다.None은 ORMsave()처럼 SQLNULL입니다. 비교와 쓰기를 가르는 기준은 자리입니다. 비교 연산자의 피연산자(IN목록·BETWEEN경계·튜플 항목 포함)로 바로 들어간 값이 조회 값이고, 나머지(VALUES·SET, 산술·함수 인자 안의 값)는 쓰기 경로입니다. 두 경로는 백엔드가 쓰는 값만 검사할 때 갈립니다. 예를 들어 MySQL은AutoField에 0을 쓰지 못하므로id == 0비교는 ORM처럼 실행되고id=0INSERT는 ORM처럼ValueError입니다. -
SQLite 의
DecimalField식은 ORM 처럼NUMERIC으로 캐스트합니다. Django 는 SQLite 에서DecimalField값을 텍스트로 묶는데, 컬럼은 NUMERIC 친화성이 있어 텍스트를 숫자로 비교하지만SUM()·산술·CASE의 결과는 친화성이 없어 숫자가 늘 텍스트보다 작습니다(SUM(price) >= '51'이 모든 행에서 거짓). ORM 은 출력 필드가DecimalField인 함수·산술·CASE·윈도를(CAST(... AS NUMERIC))으로 감싸고(SQLiteNumericMixin), 브리지 SQLite dialect 도 타입이DecimalField컬럼의 타입인 식(sum()·max()·min()·coalesce()·price + price·-price·case()·over()·filter())을 같은 자리에서 감쌉니다(윈도·FILTER는 그 바깥). 컬럼 자체는 감싸지 않습니다. 다른 DB 의 SQL 은 그대로입니다. SQLAlchemy 의func.avg()는 타입이 없으므로sa.func.avg(books.c.price, type_=books.c.price.type)처럼 타입을 주어야 감싸지고Decimal로 읽힙니다. -
컬럼으로 추적되지 않는 값(
LIKE패턴, 산술식,count()같은 식,sa.literal(),sa.text())은 변환 없이 그대로 오갑니다.INSERT … SELECT의 SELECT 목록에 넣는 값도 여기에 듭니다. 브리지는 그 값이 들어갈 대상 컬럼을 알지 못하므로(SQLAlchemy 가from_select()의 컬럼 이름을 공개 API 로 내주지 않음) 값마다 대상 컬럼 타입을 주세요:sa.literal(value, daily_stock.c.counted_at.type),sa.bindparam("at", type_=daily_stock.c.counted_at.type). 타입이 없으면 UUID(SQLite)·JSON 컬럼에 넣는 dict(PostgreSQL)는 드라이버에서 에러가 나고, 시간대 있는 datetime 은 SQLite 에서 에러 없이 UTC 가 아닌 오프셋 문자열로 저장돼 ORM 필터가 그 행을 찾지 못합니다. MySQL·Oracle 에서는 드라이버(mysqlclient·oracledb)가 오프셋을 버리고 벽시계 시각을 저장해, Django 가 UTC 로 읽으면 다른 시각(서울 시각이면 9시간 뒤)이 됩니다. 예외는 JSON 키·경로(meta["k"],meta[0],meta[("a", "b")])로, 값이 아니라 문법이라 dialect 표기(SQLite'$."k"', PostgreSQL'{a, b}')로 바꿔 넘깁니다. -
JSON 컬럼.
meta["k"] == 1(ORMmeta__k=1),meta[("a", "b")] == 1,meta == {...},meta["k"].in_([...]),meta["k"].as_string()은 세 백엔드에서 동작하고 결과가 ORM 조회와 같습니다(SQLite 의 구조 값 비교는 아래 예외). PostgreSQL에서는 jsonb 연산자도 쓸 수 있고 결과가 ORM 조회와 같습니다(테스트로 확인).브리지 (PostgreSQL) ORM meta.contains({"k": 1})(@>)meta__contains={"k": 1}meta.contained_by({...})(<@)meta__contained_by={...}meta.has_key("k")/has_all([...])/has_any([...])meta__has_key/meta__has_keys/meta__has_any_keysmeta["k"].astext == "1"(->>)annotate(v=KT("meta__k")).filter(v="1")contains·contained_by의 우변은 컬럼 값과 같게JSONField.get_db_prep_value()로 jsonb 바인딩합니다. SQLite에는 이 연산자들이 없습니다.contains·has_key는 실행 시OperationalError,astext(->>)는 SQLite 3.38+의->>로 실행되지만 텍스트가 아니라 SQL 값을 돌려줘{"k": 1}이'1'과 같지 않습니다. SQLite에서meta["k"] == [1, 2]처럼 구조 값과 비교하면 JSON 텍스트끼리 비교라 공백이 다르면 맞지 않습니다(ORM 은JSON()으로 정규화). 스칼라 비교는 ORM 과 같습니다.MySQL 은 JSON 값과 문자열을 비교하면 문자열을 JSON 문자열로 보므로(
'1'이{"k": "1"}에 맞음), 브리지는 ORM 처럼 JSON 컬럼에 묶는 값을JSON_EXTRACT(%s, '$')로 감싸 JSON 문서로 읽힙니다(INSERT·UPDATE 로 넣는 값도 같은 문서로 저장됩니다).contains·has_key는 MySQL 에 없는 연산자라 실행 시ProgrammingError이고,astext는 MySQL 의->>(JSON_UNQUOTE(JSON_EXTRACT(...)))라{"k": 1}과{"k": "1"}모두 텍스트'1'입니다(ORMKT()필터는 MySQL 에서 우변을 JSON 으로 감싸 텍스트와 맞지 않으니 결과를 대조하지 마세요).Oracle 에서 Django 는
JSONField를NCLOB(IS JSON)으로 저장하는데, Oracle 은NCLOB을=로 비교하지 못하고(ORA-22848) 키는JSON_QUERY()텍스트라[1,2]가 Django 가 쓴[1, 2]와 맞지 않습니다. 그래서 브리지는 JSON 끼리의==·!=를JSON_EQUAL()로 컴파일합니다. 문서 전체 비교(meta == {...})는 ORM 과 같습니다. 키 비교는 JSON 값으로 비교해meta["k"] == 1이{"k": "1"}에 맞지 않습니다(PostgreSQL·MySQL 과 같음). Oracle 의 ORM 은 키를JSON_VALUE()텍스트로 비교해1과"1"이 서로 맞으니 결과를 대조하지 마세요.meta["k"].in_([...])는 JSON 텍스트 비교라 구조 값이 맞지 않습니다(SQLite 와 같음).as_string()·as_integer()등은 SQLAlchemy 가JSON_VALUE(... ERROR ON ERROR)로 컴파일해 키가 없는 행 하나에 문장 전체가 실패하므로, 브리지는ERROR ON ERROR를 떼어 다른 DB 처럼NULL을 받게 합니다.contains·has_key는 Oracle 에 없는 연산자입니다. SQLAlchemy 2.0 의 Oracle dialect 는 JSON 키·경로를 컴파일하지 못해 실행 전sqlalchemy.exc.UnsupportedCompilationError입니다(문서 전체 비교는 됩니다). JSON 키·경로를 Oracle 에서 쓰려면 SQLAlchemy 2.1 을 쓰세요. -
컴파일 캐시:
bindparam()으로 만든 문장을 재사용하면 컴파일을 건너뜁니다. 브리지는 넘겨받은 문장 객체마다 컴파일 결과를 기억해, 같은 객체를 같은 DB 종류(vendor)에서 같은 이름의params로 다시 실행하면 컴파일 없이 값 변환과 실행만 합니다(execute·execute_result·stream공통). 그러니 값은sa.bindparam("pk")로 비워 둔 문장을 한 번 만들어 두고(모듈 수준 등) 돌려 쓰세요.where(orders.c.id == pk)처럼 값을 넣어 매번 새로 만든 문장은 매번 컴파일합니다(아래 "성능과 메모리" 4번).params이름이 달라지면(예: UPDATE 의SET컬럼) SQL 이 달라지므로 따로 컴파일합니다.RETURNING지원 검사는 연결(alias)마다 다를 수 있어 매 호출 그 연결로 다시 정하고, 결과 변환기는 연결 객체(connections[alias], 스레드마다 하나)에 컬럼 타입별로 한 번 찾아 둡니다. 기억한 결과는 문장 객체가 사라지면 함께 사라지고, 여러 스레드가 같은 문장을 써도 됩니다. 끄는 스위치는 없습니다(결과가 캐시 여부와 무관하므로). -
리터럴
%는 그대로 써도 됩니다(LIKE 'a%',text("SELECT '100%'")). 브리지가%s자리표시로 컴파일하고%를%%로 바꾼 뒤, 파라미터가 없어도 빈 튜플을 넘겨 백엔드가 되돌리게 합니다(MySQL 의 mysqlclient 도 같은 format paramstyle 입니다).sa.text()는 그 DB 의 SQL 그대로라, MySQL 기본sql_mode에서는 문자열 리터럴의 백슬래시가 이스케이프입니다(ESCAPE '\\'로 써야 백슬래시 하나). -
async 코드에서 직접 부르면 ORM처럼
SynchronousOnlyOperation이 납니다. 작업 단위를 동기 함수로 묶어arun으로 부르세요(아래 "비동기"). -
모델 인스턴스가 필요하면
raw(Model, stmt)가 DjangoRawQuerySet을 줍니다(아래 "모델 인스턴스로 읽기"). -
DRF·클래스 기반 뷰(
ViewSet·APIView·페이지네이션·ModelSerializer·TemplateView)에서 쓰는 레시피와 되지 않는 것(ModelViewSet·DetailView·필터 백엔드·CursorPagination등)은 docs/drf.md에 있습니다.
쪼개 읽기: stream
from django_sqlalchemy_bridge import stream
for order_id, paid_at in stream(sa.select(orders.c.id, orders.c.paid_at), chunk_size=2000):
...
stream(stmt, params=None, *, chunk_size=2000, using="default")는 행을chunk_size개씩 가져와 튜플로 하나씩 내주는 제너레이터입니다. 값 변환은execute와 같습니다. 기본chunk_size는 DjangoQuerySet.iterator()의 기본값(2000)과 같습니다.- 커서는
QuerySet.iterator()와 같은 경로로 엽니다.connection.chunked_cursor()(PostgreSQL에서는 서버 측 named cursor, SQLite·MySQL·Oracle에서는 일반 커서)에fetchmany(chunk_size)를 반복합니다. MySQL 의 일반 커서는 mysqlclient 가execute()때 결과 전체를 클라이언트로 받으므로QuerySet.iterator()처럼 메모리 이득이 없습니다(atomic()안팎 모두, 테스트로 확인). 변환한 튜플만 청크 단위로 만듭니다. 데이터베이스 설정에DISABLE_SERVER_SIDE_CURSORS: True가 있으면 일반 커서를 씁니다.CaptureQueriesContext·assertNumQueries에는iterator()처럼 1건으로 잡힙니다(FETCH는 잡히지 않습니다). - 첫 행을 요청할 때 실행됩니다. 행이 끝나거나, 제너레이터를
close()하거나(for문을break로 빠져나가 제너레이터가 버려질 때 포함), 예외로 끝나면 커서를 닫습니다. 제너레이터를 변수에 쥔 채 소비를 멈추면 닫히지 않으니close()를 부르거나contextlib.closing()으로 감싸세요. - 행을 돌려주지 않는 문장(
RETURNING없는 DML)은 실행 전에ValueError, 매핑의 시퀀스(executemany 형태)는TypeError입니다. 행이 없는text()문장은 첫next()에서ValueError입니다. - PostgreSQL의 서버 측 커서(
DECLARE)는SELECT·VALUES만 받습니다. 그래서RETURNING이 있는 DML은 일반 커서로 실행하고(행은 드라이버가 한꺼번에 받으므로 메모리 이득은 없습니다),text()문장도SELECT·VALUES여야 합니다. 데이터를 바꾸는 CTE(WITH u AS (UPDATE ... RETURNING ...) SELECT ...)는 PostgreSQL이NotSupportedError로 거부하니execute를 쓰세요.
PostgreSQL에서 트랜잭션 밖(autocommit)일 때. Django는 autocommit 상태에서 named cursor를 WITH HOLD로 엽니다(atomic() 안에서는 일반 커서). 저장소에서 확인한 동작은 이렇습니다(PostgreSQL 18, psycopg 3).
WITH HOLD커서는DECLARE가 커밋되는 시점에 결과 전체를 서버에서 계산해 서버 쪽에 저장합니다. 그래서 첫 실행이 쿼리 전체만큼 걸리고(이후fetchmany는 저장된 결과를 읽습니다), 결과가 크면 서버의 임시 저장 공간을 그만큼 씁니다. 클라이언트 메모리는 여전히 청크 단위입니다.atomic()안에서는 결과를 미리 만들지 않고fetchmany마다 계산합니다.- 커서는 그 뒤 다른 트랜잭션이 커밋돼도 살아 있고, 만들 때의 결과를 그대로 줍니다. 닫지 않으면 연결이 닫힐 때까지 서버에 남습니다.
- 반대로
atomic()안에서 연 스트림은 그 트랜잭션이 끝나면 서버 커서가 사라집니다. 블록을 나온 뒤 계속 소비하면ProgrammingError: cursor ... does not exist가 납니다. 블록 안에서 다 읽으세요. - PgBouncer를 transaction pooling 모드로 쓰면 트랜잭션이 끝난 뒤의
FETCH가 커서를 연 것과 다른 서버 연결로 갈 수 있으니, Django 문서대로DISABLE_SERVER_SIDE_CURSORS: True를 설정해야 합니다. 그러면stream도 일반 커서를 씁니다(드라이버가 결과를 한꺼번에 받습니다).
모델 인스턴스로 읽기: raw
from django_sqlalchemy_bridge import raw
paid = sa.select(orders).where(orders.c.status == sa.bindparam("status"))
for order in raw(Order, paid, {"status": "paid"}): # Order 인스턴스. 쿼리는 여기서 나간다
order.customer # 평소의 모델 인스턴스: 관계·메서드·ModelSerializer 가 그대로
raw(model, stmt, params=None, *, using="default")는 DjangoRawQuerySet을 돌려줍니다. 브리지는 문장을using연결의 dialect 로 컴파일하고params를execute와 같이 Django 필드 기준으로 변환(컬럼과 비교하는 값은 ORM 조회처럼)한 뒤model._default_manager.db_manager(using).raw(sql, params)를 부릅니다. 컴파일 캐시도execute와 같이 탑니다.- 게으릅니다. 컴파일·변환·검사는
raw()를 부를 때 하지만 SQL 은RawQuerySet을 반복할 때 Django 커서로 나갑니다(connection.queries·execute_wrapper·assertNumQueries에 1건). 한 번 반복한RawQuerySet은 결과를 기억하고,prefetch_related()·using()·async for도 Django 의 것 그대로입니다. - 결과 변환은 Django 가 합니다. Django
raw()의 계약 그대로, 결과 컬럼 이름이 필드의 컬럼 이름(db_column)과 같으면 그 필드에 ORM 이 읽을 때의 변환기를 거쳐 들어갑니다(Decimal·UUID·JSON·시간대 있는 datetime·choices 가Model.objects.get()과 같은 값). 문장에서 뺀 필드는 deferred 로, 처음 읽을 때 쿼리가 한 번 더 나갑니다. 필드가 아닌 컬럼(label("n_sales"))은 인스턴스 속성이 되며 변환하지 않은 드라이버 값입니다. 예를 들어sa.func.max(sales.c.sold_at).label("last_sold")는 SQLite 에서 저장된 텍스트(str), 다른 DB 에서datetime입니다(execute는 이런 라벨도 컬럼 타입으로 변환하지만raw()는 Django 에 맡깁니다). 그런 값이 필요하면execute_result로 읽으세요. - PK 가 있어야 합니다.
select()처럼 컬럼 이름을 컴파일 때 아는 문장은 모델 PK 의 컬럼이 없으면 실행 전에ValueError입니다.sa.text()는 이름을 알 수 없어 Django 에 맡기고, Django 가 반복할 때FieldDoesNotExist를 냅니다. - 행을 고르는 문장(
select()·union_all()같은 복합 SELECT·sa.text())만 받습니다.insert·update·delete는RETURNING이 있어도ValueError,params에 매핑의 시퀀스를 넘기면ValueError입니다(executemany 는 뜻이 없음). 파라미터가 없어도 빈 튜플을 넘기므로 리터럴%는execute처럼 그대로 씁니다. - Oracle 에서 Django
raw()는 커서가 알려 주는 컬럼 이름을 소문자로 바꿔 필드 컬럼과 맞춥니다. 브리지는 Django 식 철자(대문자)로 쓰므로db_column="MixedCase"는 맞지만, 30자를 넘는 컬럼은 Oracle 에서 해시로 줄인 이름이라 어느 필드와도 맞지 않아 deferred 가 되고 줄인 이름의 속성이 붙습니다(DjangoModel.objects.raw()도 같음, 테스트로 확인). - 비동기.
async for obj in qs는 DjangoRawQuerySet의 비동기 반복 그대로입니다. 다만raw()는 부를 때 컴파일하는데, MySQL 은 dialect 를 고르려고 연결의 첫 호출에서 서버 정보(MariaDB 여부,sql_mode)를 읽으므로 async 코드에서 바로 부르면SynchronousOnlyOperation입니다.qs = await sync_to_async(raw)(Model, stmt)로 만드세요(다른 DB 는 바로 불러도 됩니다). - 복합 PK(Django 5.2
CompositePrimaryKey)는 검사가 모든 PK 컬럼을 보지만 테스트하지 않았습니다.
여러 문장 한 번에: execute_pipeline
from django_sqlalchemy_bridge import execute_pipeline
by_pk = sa.select(orders.c.id, orders.c.status).where(orders.c.id == sa.bindparam("pk"))
mark = sa.update(orders).where(orders.c.id == sa.bindparam("pk")).values(status="seen")
results = execute_pipeline(
[
*[(by_pk, {"pk": pk}) for pk in (1, 2, 3)],
sa.select(sa.func.count()).select_from(orders), # params 가 없으면 문장만
(mark, [{"pk": 1}, {"pk": 2}]), # executemany
]
)
# [[(1, "paid")], [(2, "void")], [(3, "paid")], [(42,)], 2]
execute_pipeline(items, *, using="default")의 항목은 문장 또는(문장, params)쌍입니다. 항목마다 의미와 결과는execute와 같고(행 튜플 리스트 또는 rowcount, 값 변환,text(), 매핑의 시퀀스는 executemany), 결과는 입력 순서의 리스트입니다. 빈 입력은[]이고 아무것도 실행하지 않습니다.- PostgreSQL + psycopg 3 + 파이프라인을 지원하는 libpq(14 이상) 에서는 psycopg 의 파이프라인 모드(
connection.connection.pipeline()) 안에서 문장마다 Django 커서로 실행해, 모든 문장을 보낸 뒤 결과를 읽습니다. 왕복이 문장 수만큼이 아니라 한 번이라 독립 조회가 많을수록, 서버가 멀수록 빨라집니다(아래 "성능과 메모리" 8). 그 밖(SQLite·MySQL·Oracle·psycopg2)에서는 같은 순서로 하나씩 실행해 같은 결과를 줍니다. 속도만 다릅니다. - 항목 사이의 의존(앞 결과를 뒤
params로)은 받지 않습니다. 모든 문장이 호출할 때 준비돼 있어야 합니다. - 실행 전 검사는 모든 항목에 대해 먼저 합니다.
RETURNING을 지원하지 않는 DB, SQLAlchemy Python 측 default, executemany 와RETURNING처럼execute가 실행 전에 거부하는 항목이 하나라도 있으면 아무것도 실행하지 않습니다. - Django 커서를 지나므로
connection.queries·CaptureQueriesContext·assertNumQueries·execute_wrapper에 문장마다 하나씩(executemany 항목은 하나) 잡힙니다. 컴파일 캐시도 항목마다 그대로 탑니다. - 문장을 둘 이상 실행하는 호출은
atomic(using, savepoint=False)안에서 돕니다(bulk_*와 같음). 그래서atomic()밖에서도, 모든 백엔드에서 한 호출의 쓰기는 모두 되거나 모두 안 됩니다. 트랜잭션 밖에서 부르면 Django 가BEGIN·COMMIT을 쿼리 기록에 남기고, PostgreSQL 에서는COMMIT왕복이 하나 늘어납니다. 바깥atomic()안에서 이 호출의 에러를 잡고 계속하려면 호출을atomic()으로 한 번 더 감싸세요(savepoint).- PostgreSQL 파이프라인은 그 자체로도 Sync 까지의 문장을 암묵적 트랜잭션으로 묶습니다. 저장소에서 감싸지 않고 확인했을 때 autocommit 에서 뒤 문장이 실패하면 앞 쓰기도 남지 않았습니다(PostgreSQL 18, psycopg 3.3). 다만 executemany 항목은 결과를 남기지 않아 어느 항목이 실패했는지 알려면 그 뒤에 Sync 를 하나 더 보내야 하고(항목마다 왕복 하나), 트랜잭션 밖의 Sync 는 커밋이라 브리지가 트랜잭션을 엽니다.
- 한 항목이 실패하면 그 항목의 DB 에러(Django 의
IntegrityError등)가 그대로 나고, 에러의 note(e.__notes__, 트레이스백 끝에 보임)에execute_pipeline(): item 2 failed처럼 몇 번째 항목인지 적힙니다. psycopg 가 실패 뒤 문장에 내는PipelineAborted는 드러나지 않습니다. 뒤 항목은 효과가 없습니다. PostgreSQL 은 이미 보낸 문장을 서버가 건너뛰고(그래서execute_wrapper에는 보인 문장으로 잡힙니다), 하나씩 실행하는 백엔드는 보내지 않습니다.atomic()안이면 블록이 롤백됩니다. - 결과 하나짜리
Result(execute_result)판,stream의 파이프라인화, 결과 지연 읽기는 없습니다. async 코드에서는 다른 API 처럼SynchronousOnlyOperation이니arun으로 감싸세요.
CSV 로 내보내기: copy_to (PostgreSQL)
from django.http import StreamingHttpResponse
from django_sqlalchemy_bridge import copy_to
paid = sa.select(orders.c.id, orders.c.status, orders.c.paid_at).where(orders.c.status == sa.bindparam("s"))
response = StreamingHttpResponse(copy_to(paid, {"s": "paid"}), content_type="text/csv")
with open("orders.csv", "wb") as f:
f.writelines(copy_to(paid, {"s": "paid"}))
copy_to(stmt, params=None, *, format="csv", header=True, using="default")는COPY (<컴파일한 문장>) TO STDOUT WITH (FORMAT csv, HEADER …)를 Django 커서 아래 psycopg 커서(cursor.cursor.copy())로 실행하고 서버가 쓴 바이트를 그대로 내주는 제너레이터입니다. 행을 파이썬 객체로 만들지 않습니다. psycopg 는 COPY 데이터를 행 하나씩 주므로 브리지가 64 KiB 이상씩 모아 내줍니다(마지막 덩어리만 더 작을 수 있음).StreamingHttpResponse는 덩어리마다 한 번 쓰기 때문입니다.- 값은 서버의 텍스트 표현입니다(Django 필드 변환 없음).
timestamptz는 Django 가 연결에 설정한 세션 시간대(USE_TZ면 UTC,+00접미), boolean 은t/f, numeric 은 그대로(12.500), jsonb 는 JSON 텍스트, bytea 는\x…입니다. NULL 은 csv 에서 빈 칸, 빈 문자열은"", text 포맷에서는\N입니다. 쉼표·따옴표·개행·탭의 따옴표 처리와 이스케이프는 서버가 합니다(테스트로 고정). format은"csv"(헤더 줄은header=True가 기본, 컬럼 이름이나label())와"text"(탭 구분, PostgreSQL 기본 COPY 포맷)입니다. text 포맷은 헤더를 받지 않아header=False를 함께 줘야 하고,header=True면ValueError입니다.stmt·params는execute처럼 컴파일·변환합니다(컬럼과 비교하는 값은 ORM 조회처럼, 컴파일 캐시도 탐). PostgreSQL 의 COPY 는 프로토콜 파라미터를 받지 않으므로 브리지는 psycopgClientCursor.mogrify()로 값을 SQL 리터럴로 쓴 뒤 파라미터 없이 COPY 합니다. psycopg 의 어댑터로 쓰므로 bytea·jsonb·UUID 도 그대로이고, DjangoOPTIONS["server_side_binding"](psycopgServerBindingCursor)에서도 같습니다. 파라미터가 없어도 거치므로 리터럴%는execute처럼 그대로 씁니다.- 행을 고르는 문장(
select()·복합 SELECT·sa.text())만 받습니다.insert·update·delete는RETURNING이 있어도 실행 전ValueError, 매핑의 시퀀스는TypeError입니다. PostgreSQL 이 아니거나 psycopg2 면 실행 전NotSupportedError입니다. stream과 같은 계약. 첫 덩어리를 요청할 때 실행되고, 바이트가 끝나거나close()하거나 예외로 끝나면 커서를 닫습니다.atomic()안에서 열었으면 블록 안에서 끝까지 읽으세요. 일찍close()하면 트랜잭션 밖(autocommit)에서는 psycopg 가 COPY 를 취소하고, 트랜잭션 안에서는 남은 데이터를 읽어 버립니다. 취소하면 그 트랜잭션이 깨지기 때문입니다(결과가 클 때current transaction is aborted, 테스트로 고정). 그래서 큰 내보내기를 트랜잭션 안에서 중간에 멈추면 나머지를 받는 시간만큼 걸립니다.- 쿼리 기록은
bulk_insert(method="copy")와 같습니다. 디버그 기록이 켜져 있으면 값을 넣은COPY (…) TO STDOUT …문장 한 건이connection.queries에 남고(시간은 바이트를 다 내준 뒤까지),execute_wrapper()에는 보이지 않습니다. 에러는 Django 예외(ProgrammingError등)로 올라오고, 깨진 트랜잭션에서는execute처럼TransactionManagementError입니다. - 언제 쓰나: 많은 행을 그대로 파일·HTTP 로 내보낼 때. 200,000행(컬럼 7개)을 CSV 로 쓰는 데
stream()+csv.writer766 ms 대 237 ms, tracemalloc 피크 40.0 MiB 대 12.3 MiB 였습니다(아래 "성능과 메모리" 9). 파이썬 값이 필요하거나 Django 식 표현(aware datetime 의+09:00,True)이 필요하면stream으로 읽어csv.writer로 쓰세요(아래 "성능과 메모리" 9).
대량 쓰기: bulk_update, bulk_insert
from django_sqlalchemy_bridge import bulk_insert, bulk_update
# PK(기본) 또는 지정한 키로 행마다 다른 값을 넣는 UPDATE. 반환은 rowcount
bulk_update(orders, [{"id": 1, "status": "paid"}, {"id": 2, "status": "void"}])
bulk_update(orders, rows, key="uid", columns=["status"]) # 키·설정 컬럼 지정, 복합 키는 key=("a", "b")
# INSERT. returning 을 주면 행마다 튜플(필드 변환을 거친 값), rows 순서대로
ids = bulk_insert(orders, rows, returning=["id"])
# 수십만 행 이상: batch_size 행씩 문장을 나눠 메모리를 줄인다(전부 쓰이거나 하나도 안 쓰임)
bulk_insert(orders, rows, batch_size=10_000)
# PostgreSQL 에서 RETURNING 이 필요 없는 수십만 행: COPY FROM STDIN
bulk_insert(orders, rows, method="copy")
bulk_update(table, rows, *, key=None, columns=None, batch_size=None, using="default"),bulk_insert(table, rows, *, returning=None, batch_size=None, using="default", method="insert").table은table_for()테이블이나 모델입니다.rows는 컬럼 이름(db_column, FK 는<이름>_id)을 키로 한 매핑의 시퀀스입니다.- PostgreSQL에서는 문장 하나입니다. 컬럼마다 배열 파라미터 하나를 Django 컬럼 타입으로 캐스트하고(
(%s)::jsonb[],(%s)::numeric[]…)unnest()로 행을 만듭니다. UPDATE 는UPDATE t SET c = v.c FROM unnest(...) AS v(...) WHERE t.k = v.k, INSERT 는INSERT INTO t (...) SELECT * FROM unnest(...)꼴로, Djangobulk_create가 PostgreSQL에서 쓰는 방식과 같습니다. 캐스트에서는 길이·자릿수를 떼므로(varchar(50)[]가 아니라varchar[]) 값이 잘리지 않고, 너무 긴 값은 ORM 쓰기처럼 컬럼에 넣을 때 오류가 납니다.CaptureQueriesContext에는 1건으로 잡힙니다. - 그 밖의 백엔드(SQLite·MySQL·Oracle)에서는 같은 호출이
cursor.executemany()입니다(atomic()안에서, 아래 "원자성").returning이 있는 INSERT 는 executemany 로 행을 받을 수 없어서 다중VALUES문장을connection.ops.bulk_batch_size()(SQLite 변수 한도) 단위로 나눠 실행합니다. 결과는 PostgreSQL과 같습니다.- MySQL: mysqlclient 는 INSERT 의 executemany 를 다중 행
INSERT … VALUES (…), (…)로 바꿔 보내고, UPDATE 의 executemany 는 행마다 문장 하나를 보냅니다(CaptureQueriesContext에는 1건). rowcount 는 Django 가 켠CLIENT.FOUND_ROWS덕에 바뀐 행이 아니라 맞은 행을 셉니다.bulk_insert(returning=...)는 MySQL 에RETURNING이 없어 실행 전NotSupportedError이고, MariaDB 에서는 다중VALUES … RETURNING으로 돕니다.UPDATE … JOIN (VALUES ROW(…))로 한 문장을 만드는 방식은 MariaDB 에VALUES ROW가 없고 행 값의 타입을 정할 방법이 없어 쓰지 않았습니다.INSERT … ON DUPLICATE KEY UPDATE는 없는 키를 새 행으로 넣어 의미가 다릅니다. - Oracle:
bulk_insert(returning=...)는 실행 전NotSupportedError입니다(아래 "제약"의RETURNING). 너무 긴 값은 ORM 쓰기와 같이DataError가 아니라DatabaseError(ORA-12899)입니다.
- MySQL: mysqlclient 는 INSERT 의 executemany 를 다중 행
- 값 변환은
execute와 같습니다. 쓰는 행 값마다field.get_db_prep_save(),bulk_update의key값은 ORM 조회처럼(None은 SQLNULL),returning컬럼은 ORM 변환기를 거칩니다. 파라미터는 행마다 SQLAlchemy로 만들지 않고 컬럼마다 리스트 하나로 바로 만듭니다. - 빠진 값은 오류입니다. 실행 전에
ValueError를 냅니다.bulk_update: 키나 설정할 컬럼이 없는 행, 키가 같은 두 행(PostgreSQL은 그중 아무 행 하나로, executemany 는 둘 다 차례로 갱신해 결과가 달라지므로 거부).columns를 생략하면 첫 행의 키 외 컬럼을 설정하고 모든 행이 같은 키를 가져야 합니다.columns를 주면 행의 다른 키는 무시합니다. 없는 키 값은 아무 행도 바꾸지 않고, rowcount 는 맞은 행만 셉니다.bulk_insert: 행끼리 키가 다르거나, 테이블 컬럼을 빠뜨린 경우. 자동 증가 PK 와db_default가 있는 컬럼만 빠뜨릴 수 있습니다. Django 필드default·auto_now를 채우지 않으므로 nullable 컬럼도None을 직접 넣어야 합니다(잊은 컬럼이 조용히NULL이 되지 않게).
batch_size: 양의 정수면 그 행 수마다 문장 하나(SQLite 는executemany()호출 하나)로 나눕니다.None(기본값)이면 위와 같습니다. 0 이하나 정수가 아니면 실행 전에ValueError입니다. SQLite 의returning배치는bulk_batch_size()를 넘지 않습니다. 키 중복·누락 검사는 나누기 전에 전체 행으로 하고, rowcount 는 배치의 합,returning결과는 배치와 상관없이rows순서입니다.- 원자성: 문장을 둘 이상 실행하는 호출(배치가 여럿이거나 SQLite
executemany())은 Djangobulk_create·bulk_update처럼transaction.atomic(using=..., savepoint=False)안에서 돕니다. 한 배치가 실패하면 그 호출이 쓴 행은 모두 롤백됩니다. 바깥atomic()안에서는 savepoint 를 만들지 않으므로, 실패를 잡아 트랜잭션을 이어가려면 호출을atomic()으로 한 번 더 감싸세요(ORM 쓰기와 같습니다). - 언제
batch_size를 주나. PostgreSQL 의 한 문장은 행 수에 비례해 클라이언트(파라미터 배열)와 서버 백엔드(배열과unnest결과) 메모리를 씁니다. 1,000,000행(컬럼 6개)에서bulk_insert는 클라이언트 tracemalloc 피크 849 MiB, 서버 백엔드 233 MiB 였고,batch_size=10_000이면 226 MiB·6 MiB 로 줄면서 시간은 3.5% 빨랐습니다.bulk_update는 나누면 느려집니다(1,000,000행에서10_000은 21% 느림,200_000은 3% 느림). 한 문장은 대상 테이블과 해시 조인 한 번으로, 작은 배치는 행마다 PK 인덱스 조회로 갱신하기 때문입니다(로컬 PostgreSQL 18 의EXPLAIN ANALYZE로 확인). 그래서 기본값은None이고, 수십만 행 이상에서 메모리가 문제일 때bulk_insert는10_000~50_000,bulk_update는200_000안팎을 권합니다. SQLite 는 차이가 작습니다(아래 "성능과 메모리" 7). method="copy"(PostgreSQL + psycopg 3):INSERT대신COPY t (컬럼…) FROM STDIN(text 포맷)으로 넣습니다. Django 커서 아래의 psycopg 커서(cursor.cursor.copy())로 실행하므로 Django 연결·트랜잭션 안에서 돕니다. 행 검사와 값 변환(get_db_prep_save())은"insert"와 같고, 탭·개행·백슬래시·\N문자열의 이스케이프는 psycopg 가 맡습니다(테스트로 고정).batch_size를 주면 배치마다COPY하나, 둘 이상이면 같은atomic(savepoint=False)입니다. 트리거·제약·FK 검사는 INSERT 와 같고, 제약 위반은 Django 예외(IntegrityError·DataError)로 올라옵니다. 반환값은 psycopg 가 COPY 뒤cursor.rowcount로 주는 행 수입니다. 언제 쓰나:RETURNING이 필요 없는 수십만 행 이상의 INSERT. 200,000행(컬럼 6개)에서"insert"(unnest) 3,571 ms 대 1,925 ms 였고, 1,000,000행에서는 시간이 47% 줄고 클라이언트 tracemalloc 피크가 849 MiB → 193 MiB, 서버 백엔드 메모리 증가가 233 MiB → 0.5 MiB 였습니다(아래 "성능과 메모리" 2·7). COPY 는 행을 흘려보내므로 서버 메모리가 행 수를 따라 늘지 않습니다.batch_size는 클라이언트 메모리만 조금 줄입니다(1,000,000행에서10_000이면 148 MiB, 시간은 4% 늘어남).returning과 함께 쓰면 실행 전ValueError입니다(COPY 에는RETURNING·ON CONFLICT가 없음). PostgreSQL 이 아닌 연결이나 psycopg2 에서는 실행 전NotSupportedError입니다. 조용히"insert"로 바꾸지 않습니다. binary 포맷은 쓰지 않습니다(psycopg 의 binary COPY 는 컬럼마다set_types()로 서버 타입을 정해야 하고, text 포맷은 서버가 INSERT 파라미터처럼 텍스트로 받아 컬럼 타입으로 읽습니다).- 쿼리 기록:
COPY는 DjangoCursorWrapper.execute()를 지나지 않습니다. 브리지가 디버그 기록이 켜져 있을 때(connection.queries_logged)COPY … FROM STDIN문장을 배치마다connection.queries에 한 건씩 남기므로CaptureQueriesContext·assertNumQueries에 잡히지만,connection.execute_wrapper()에는 보이지 않습니다.
- 빈
rows는 쿼리를 실행하지 않고0(또는returning이면[])을 돌려줍니다. RETURNING순서: 결과는rows순서입니다(테스트로 고정). 다만 PostgreSQL·SQLite 모두RETURNING순서를 문서로 보장하지는 않으며, Djangobulk_create가 PK 를 객체에 채울 때도 같은 동작에 기댑니다. 아래 "제약"을 보세요.- signal·
save()를 거치지 않는 것은 다른 브리지 쓰기와 같습니다(아래).
⚠️ 브리지로 쓴 내용은 모델 계층을 거치지 않습니다.
save()·delete()가 불리지 않고,pre_save/post_save/pre_delete/post_delete등 signal이 발생하지 않으며, Django 필드의default·auto_now도 채워지지 않습니다. 값은 모두 직접 넣어야 합니다.
다중 DB
table_for()의 테이블은 모델에서 오므로 어느 DB 에도 묶이지 않습니다. 어느 DB 에서 실행할지는 호출마다 using(Django DB 별칭)이 정하고, 같은 테이블·같은 문장을 default와 다른 DB 에 번갈아 실행해도 됩니다. dialect 는 실행할 때 connections[using]의 vendor 로 고르고, 컴파일 캐시는 vendor 별, 결과 컨버터 캐시는 연결 객체별이라 서로 섞이지 않습니다. execute·execute_result·stream·raw·execute_pipeline·copy_to·bulk_* 모두 using을 받습니다.
price_changes = table_for(PriceChange) # 모델에서 만든 테이블은 어느 DB 에도 묶이지 않는다
stmt = sa.select(price_changes.c.sku, price_changes.c.price)
here = execute(stmt) # default: [("SHIRT", Decimal("27.50"))]
there = execute(stmt, using="other") # 같은 문장을 other 에서: [("TEA", Decimal("8.50"))]
서로 다른 DB 의 테이블은 한 문장에서 JOIN 할 수 없습니다. JOIN 은 한 연결 위에서 DB 서버가 실행하기 때문이고, Django ORM 도 SQLAlchemy 도 같습니다. 길은 둘입니다.
- 서버 링크. PostgreSQL
postgres_fdw·dblink, SQLiteATTACH, MySQLFEDERATED, Oracle DB link 처럼 한 DB 가 다른 DB 의 테이블을 자기 이름으로 보여 주면, 그 테이블은 한 연결 안의 이름입니다. 모델이 없으니sa.table()로 손수 만들어 평범한 JOIN 을 그 연결(using)로 보냅니다. 손수 만든 테이블의 컬럼에는 Django 필드가 없으므로 그 값은 변환 없이 드라이버 값 그대로 오갑니다(위 "실행하기"의 컬럼으로 추적되지 않는 값과 같음). 아래는 SQLite 에서 실제로 도는 예입니다(linked는 다른 SQLite 파일).
# 다른 SQLite 파일을 이 연결의 linked 스키마로 붙인다(연결 상태라 연결마다 한 번)
with connection.cursor() as cursor:
cursor.execute("ATTACH DATABASE %s AS linked", [path])
products = table_for(Product)
remote_sales = sa.table("remote_sale", sa.column("product_id"), sa.column("quantity"), schema="linked")
stmt = (
sa.select(products.c.sku, sa.func.sum(remote_sales.c.quantity))
.join(remote_sales, remote_sales.c.product_id == products.c.id)
.group_by(products.c.sku)
.order_by(products.c.sku)
)
rows = execute(stmt) # 한 연결 안의 평범한 JOIN: [("SHIRT", 3), ("TEA", 5)]
- 애플리케이션에서 합치기. 서버 링크가 없으면 Django 의 교차 DB
prefetch_related처럼 한쪽에서 키를 뽑아 다른 쪽을in_()으로 조회하고 파이썬에서 합칩니다. 문장이 둘이고 트랜잭션도 DB 마다 따로입니다.
products = table_for(Product) # default DB 의 상품
price_changes = table_for(PriceChange) # other DB 의 가격표
skus = [sku for (sku,) in execute(sa.select(products.c.sku).order_by(products.c.sku))]
new_prices = dict(
execute(
sa.select(price_changes.c.sku, price_changes.c.price).where(price_changes.c.sku.in_(skus)),
using="other",
)
)
rows = [(sku, new_prices.get(sku)) for sku in skus]
# [("JEANS", None), ("SHIRT", Decimal("27.50")), ("TEA", Decimal("8.50"))]
arun에는 using이 없습니다. fn 안의 호출이 저마다 using을 받습니다(아래 "비동기").
제약
브리지가 실행 전에 막는 것과, 막지 않거나 막을 수 없는 것들입니다.
- RETURNING 은 그 DB 가 지원할 때만. dialect 는 DB 에 연결하지 않고 컴파일하므로 어떤 DB 에도
RETURNING을 씁니다. 그래서RETURNING이 있는 SQLAlchemy DML(execute·execute_result·stream,bulk_insert(returning=...))은 문장 종류별로 실행 연결을 보고 실행 전에django.db.NotSupportedError를 냅니다.- SQLite: 3.35 부터 INSERT·UPDATE·DELETE 모두 지원합니다(Django 5.2 는 3.31 부터 받음). Django feature
can_return_columns_from_insert가 거짓이면 셋 다 거부합니다. - MySQL:
RETURNING이 없어 모두 거부합니다. - MariaDB(Django vendor 는
"mysql"):INSERT … RETURNING·DELETE … RETURNING은 실행하고UPDATE … RETURNING만 거부합니다. - Oracle: 모두 거부합니다. Oracle 은
RETURNING … INTO :출력변수로 행을 출력 바인드에 넣는데 Django 커서로는 그 값을 받을 수 없습니다. 거부하지 않으면 에러 없이 행 대신 rowcount 가 돌아옵니다(2026-10-26, Oracle 23ai Free 에서 확인). Django 는 Oracle 에서can_return_columns_from_insert를 참으로 알리지만 브리지는 vendor 로 거부합니다. sa.text("... RETURNING ...")는 안을 볼 수 없어 검사하지 않고 DB 가 판단합니다.
- SQLite: 3.35 부터 INSERT·UPDATE·DELETE 모두 지원합니다(Django 5.2 는 3.31 부터 받음). Django feature
- SQLAlchemy Python 측 컬럼
default/onupdate는 적용할 수 없어 실행 전에 막습니다. 직접 만든sa.Table의Column(default=..., onupdate=...)에 준 Python 값·callable 은 SQLAlchemy 실행 컨텍스트(Engine·Connection)가 채우는데 브리지는 Django 커서로 실행합니다. 컴파일러는 그 컬럼을 SQL 에 넣어 두므로(INSERT ... (name, ...) VALUES (%s, ...),UPDATE ... SET name=%s, ...) 그대로 두면NULL이 바인딩되어, nullable 컬럼에는 조용히NULL이 저장되고onupdate컬럼은 UPDATE 마다 기존 값이NULL로 덮입니다(SQLite·PostgreSQL 에서 확인). 그래서 그런 컬럼을 비워 둔 INSERT·UPDATE 는execute·execute_result·stream·executemany 모두 실행 전에ValueError(... Python-side default or onupdate of 테이블.컬럼 cannot be applied ...)를 냅니다. 그 컬럼 값을.values()나 params 로 직접 주면 그대로 실행합니다.default=sa.func.now()처럼 SQL 식인 default/onupdate 는 SQL 에 들어가므로 막지 않고 DB 가 계산합니다. DB 쪽server_default·Djangodb_default도 DB 가 채우므로 영향이 없습니다.table_for()테이블에는 이런 default 가 없고(Django 필드default·auto_now도 채우지 않습니다),bulk_*는table_for()테이블만 받습니다. - PostgreSQL
standard_conforming_strings=off서버는 지원하지 않습니다. 브리지는 연결하지 않고 컴파일하므로 리터럴 백슬래시를 "on"(PostgreSQL 기본값, Django 가 지원하는 모든 버전의 기본)으로 렌더합니다. "off" 서버에서는 컴파일러가 직접 쓴 리터럴(sa.literal(..., literal_execute=True)등)의 백슬래시가 이스케이프로 읽혀'a\tb'가 탭 문자가 됩니다(세션에서 "off"로 바꿔 PostgreSQL 18 에서 확인). 바인딩 값에는 영향이 없습니다. - MySQL 의 리터럴 백슬래시는 연결의
sql_mode를 따릅니다. 컴파일러가 직접 쓴 리터럴(sa.literal(..., literal_execute=True)등)의 백슬래시를 기본sql_mode에서는 두 번 쓰고,NO_BACKSLASH_ESCAPES면 한 번 씁니다. Django 가 연결마다 한 번 읽는connection.sql_mode를 보므로, 연결을 연 뒤 세션에서SET sql_mode로 바꾸면 따라가지 않습니다. - Oracle 의 식별자는 Django 식으로 씁니다. Django 의 Oracle
quote_name()은 모든 이름을 대문자로 바꾸고 30자를 넘으면 해시로 줄입니다(a_column_name_longer_than_thirty_characters→A_COLUMN_NAME_LONGER_THAN_9E63). SQLAlchemy 의 Oracle dialect 는 소문자 이름을 따옴표 없이 쓰지만(Oracle 이 대문자로 읽어 같음) 대소문자가 섞인 이름(db_column="MixedCase")·긴 이름·예약어(uid,level)는 그대로 따옴표로 감싸 Django 가 만든 적 없는 컬럼을 가리킵니다(ORA-00904). 그래서 브리지의 Oracle dialect 는 테이블·컬럼·별칭을 모두 Django 처럼 대문자로 줄여 따옴표로 씁니다.sa.sql.quoted_name("Legacy", quote=True)처럼 대소문자를 지키라고 한 이름도 대문자로 씁니다. Django 의quote_name()이 따옴표로 감싼 이름까지 대문자로 바꾸므로 Django 가 관리하는 스키마에는 대소문자를 구분하는 이름이 없고, 브리지는 Django 와 같은 이름을 쓰는 쪽을 택했습니다. Django 밖에서 대소문자를 구분해 만든 테이블은sa.text()로 쓰세요. - Oracle 의 그 밖의 차이. 브리지는 SQL 의미를 그대로 쓰므로 ORM 이 Oracle 에서 바꿔 주는 것을 바꾸지 않습니다.
- 빈 문자열은
NULL입니다.col == ""은 아무 행에도 맞지 않습니다(ORM 은filter(col="")을IS NULL로 바꿈).col.is_(None)을 쓰세요. 읽을 때는 ORM 과 브리지 모두""를 줍니다. TextField는NCLOB이라==로 비교하면ORA-22848입니다(ORM 은DBMS_LOB.SUBSTR()로 감쌈).- 다중 행
VALUES(insert(t).values([{...}, {...}]))는 SQLAlchemy 가 연결하지 않은 Oracle dialect 에서 컴파일하지 않아 실행 전CompileError입니다. params 리스트(executemany)나bulk_insert를 쓰세요. - 컬럼이 없는 식이나
sa.text()로 고른NCLOB·BLOB값은 oracledb 의 LOB 객체로 옵니다(.read()). 컬럼을 고르면 ORM 변환기가str·bytes로 바꿉니다. sum()·avg()처럼 정밀도가 없는 숫자를 Django 의 Oracle 커서는 텍스트에 소수점이 있는지로int나Decimal로 줍니다. 브리지는 ORM 처럼(BaseExpression.convert_value) 컬럼 필드의 타입으로 맞춥니다(DecimalField의 합은Decimal).SELECT목록의 불리언 식((price > 2).label("gt"),sa.exists())은 Oracle 23ai 부터 됩니다. 19c 는 확인하지 않았습니다(아래 "지원 대상").
- 빈 문자열은
bulk_insert(method="copy")는execute_wrapper()에 보이지 않습니다. psycopg 의Cursor.copy()는 Django 커서의execute()를 거치지 않기 때문입니다.connection.queries에는 배치마다 한 건씩 남깁니다(위 "대량 쓰기"). PostgreSQL + psycopg 3 전용이고, 다른 연결에서는 실행 전NotSupportedError입니다.copy_to는 PostgreSQL + psycopg 3 전용이고execute_wrapper()에 보이지 않습니다. 값은 Django 변환이 아닌 서버의 텍스트 표현이고, 트랜잭션 안에서 일찍close()하면 남은 데이터를 다 받습니다(위 "CSV 로 내보내기").bulk_insert(returning=...)의 행 순서는 DB 가 문서로 보장하지 않습니다. PostgreSQL·SQLite 모두 지금은 입력 순서로 돌려주고 Djangobulk_create도 같은 가정에 기대지만, 순서가 중요하면 행을 식별할 키(자연 키,uid등)를 함께RETURNING해서 그 값으로 짝지으세요. 예:bulk_insert(books, rows, returning=["uid", "id"]).
비동기
Django의 async ORM(aget() 등)은 내부적으로 쿼리마다 sync_to_async로 스레드에 넘기는 구조이고, Django 문서도 "async 모드에서는 아직 트랜잭션이 동작하지 않는다"고 적고 있습니다. 브리지는 작업 단위 전체를 스레드에 한 번 넘기는 arun 하나만 제공합니다. 얻는 것은 스레드 위임 횟수가 줄고 async 코드에서도 트랜잭션을 쓸 수 있는 것이지, 진짜 비동기 I/O는 아닙니다.
arun
import sqlalchemy as sa
from django.db import transaction
from django_sqlalchemy_bridge import arun, execute, table_for
from shop.models import Order
orders = table_for(Order)
def ship(order_ids): # 동기 함수: 쿼리 여러 개와 atomic()을 담은 작업 단위
with transaction.atomic():
n = execute(sa.update(orders).where(orders.c.id.in_(order_ids)).values(status="shipped"))
transaction.on_commit(notify_shipping)
return n
async def view(request):
n = await arun(ship, [1, 2, 3])
arun(fn, /, *args, **kwargs)는fn(*args, **kwargs)를sync_to_async(thread_sensitive=True)로 한 번에 실행하고 반환값을 돌려줍니다.fn이 낸 예외도 그대로 올라옵니다.fn안에서는execute·stream·bulk_*·atomic()·on_commit·ORM을 동기 코드처럼 씁니다.fn은 위치 전용 인자라fn이나using이라는 키워드 인자도 그대로fn에 넘어갑니다.arun에는using이 없습니다. 어느 DB를 쓸지는fn안의execute(..., using=...)·atomic(using=...)이 정합니다(위 "다중 DB").- 코루틴 함수를 넘기면
TypeError입니다(await fn()을 쓰세요). 동기 함수가 awaitable을 돌려줘도TypeError입니다. arun여러 건을asyncio.gather로 동시에 돌려도 서로 섞이지 않습니다. thread-sensitive 호출은 한 스레드에서 차례로 돌고, 각fn의 트랜잭션은 그fn안에서 시작해 끝나므로 한쪽의 롤백이 다른 쪽의 커밋에 영향을 주지 않습니다(테스트로 확인).- 연결 수명.
fn앞뒤로 Djangoclose_old_connections()와 같은 정리를 합니다. 그 스레드의 연결 중 오류 뒤 쓸 수 없게 된 것,CONN_MAX_AGE가 지난 것을 닫습니다(Channelsdatabase_sync_to_async와 같은 동작). 요청 밖에서 오래 도는 코루틴(워커, consumer)은 Django의 요청 시작·끝 정리를 받지 못해, 서버가 끊은 연결이 그 스레드에서 계속connection is closed로 실패하기 때문입니다. 이 정리가 있으면 끊긴 뒤 첫 호출만 실패하고 다음 호출은 새 연결을 씁니다.CONN_HEALTH_CHECKS: True면 첫 호출부터 새 연결을 씁니다(PostgreSQL에서 테스트로 확인).- 그래서
CONN_MAX_AGE: 0(기본값)이면arun호출마다 연결을 새로 엽니다. 요청 하나에서 여러 번 부른다면CONN_MAX_AGE를 주거나 PostgreSQL 연결 풀(OPTIONS: {"pool": True})을 쓰세요. 측정은 아래 "성능과 메모리"의 5 를 보세요. atomic()블록 안에 있는 연결(예: 바깥 동기 코드가 연 트랜잭션, DjangoTestCase)은 닫지 않습니다.
- 그래서
- async 코드에서
execute·stream·bulk_*를arun없이 바로 부르면 ORM처럼SynchronousOnlyOperation이 납니다. 이 안전장치는 우회하지 않습니다.
Django Channels. thread-sensitive 호출은 Django ASGI 핸들러 안에서는 요청마다 스레드 하나를 쓰지만, Channels consumer에는 그런 구분이 없어 모든 consumer의 arun(그리고 database_sync_to_async)이 프로세스 전체에서 스레드 하나로 줄을 섭니다. DB 작업이 긴 consumer가 많으면 서로를 기다립니다. 브리지는 Channels에 의존하지 않습니다.
넣지 않는 것
async with atomic()형태는 넣지 않습니다.atomic()의 진입·종료를 따로sync_to_async로 넘기면, 같은 스레드를 쓰는 코루틴들이 연결 하나와 그 트랜잭션 상태를 함께 씁니다. 먼저 연 코루틴의 트랜잭션 안에서 다른 코루틴의atomic()은 savepoint가 되고, 트랜잭션이 없는 쓰기는 그 트랜잭션에 그대로 섞입니다. 그래서 정상 종료한 코루틴의 쓰기가 다른 코루틴의 실패와 함께 예외 없이 롤백됩니다. 이렇게 흉내 낸 구현을gather로 두 건 돌려 SQLite·PostgreSQL 모두에서 재현했습니다(먼저 연 쪽이 실패하든, 정상 쪽이 먼저 블록을 나오든 정상 쪽의 행이 사라짐).- SQLAlchemy 비동기 엔진(
AsyncEngine)과 psycopg 3 비동기 연결 직접 사용은 채택하지 않습니다. 둘 다 Django 밖에서 따로 연결을 열기 때문에 Django 트랜잭션·잠금·쿼리 집계(execute_wrapper,assertNumQueries) 밖에서 돕니다. "연결과 트랜잭션은 Django가 관리한다"는 원칙과 맞지 않습니다.
성능과 메모리
아래 표의 수치는 모두 저장소의 bench/ 스크립트가 쓴 결과 파일(bench/results/*.json)에서 bench/readme.py가 만든 것입니다. 표마다 출처 파일을 적었고, 결과 파일에는 회차별 원값과 버전·DB 서버·머신 정보가 함께 들어 있습니다. 표가 결과 파일과 어긋나면 테스트(tests/test_bench_readme.py)가 실패합니다.
GitHub Actions 의 ubuntu-latest 러너 한 대에서 잰 수치입니다(.github/workflows/bench.yml, 실행 기록은 결과 파일의 ci_run). 러너는 다른 작업과 하드웨어를 나눠 쓰는 공유 VM 이라 같은 측정의 회차 사이에도 수십 % 차이가 나기도 하고(결과 파일의 times_s), 차이가 10% 안팎인 비교는 순서가 뒤바뀔 수 있습니다. PostgreSQL 은 같은 VM 의 서비스 컨테이너라 네트워크를 건너는 실제 서버 배치보다 왕복이 쌉니다. 절대값보다 같은 표 안의 상대 비교로 읽으세요.
PostgreSQL 18.6 (Debian 18.6-1.pgdg13+2) · Python 3.12.3 · Django 6.1.2 · SQLAlchemy 2.1.6 · psycopg 3.3.6 · django-pgbulk 3.3.0 · django-cte 4.0.0 · AMD EPYC 9V45 96-Core Processor (4코어, 메모리 16 GiB) · Linux-6.17.0-1022-azure-x86_64-with-glibc2.39 · 반복 5회(+예열 1회) 중 최솟값
SQLite 3.45.1 · Python 3.12.3 · Django 6.1.2 · SQLAlchemy 2.1.6 · psycopg 3.3.6 · django-pgbulk 3.3.0 · django-cte 4.0.0 · AMD EPYC 9V45 96-Core Processor (4코어, 메모리 16 GiB) · Linux-6.17.0-1022-azure-x86_64-with-glibc2.39 · 반복 5회(+예열 1회) 중 최솟값
다시 재기:
uv sync --group bench
DSB_PG_HOST=127.0.0.1 DSB_PG_PORT=55432 DSB_PG_USER=dsb DSB_PG_PASSWORD=dsb DSB_PG_NAME=dsb \
uv run --group bench python -m bench --db postgres # 시나리오 지정: python -m bench update read ...
uv run --group bench python -m bench --db sqlite
uv run python -m bench.readme --write # 시나리오·DB 마다 날짜가 가장 늦은 결과 파일로
측정 방법.
- 시간은 측정 대상 호출 하나를
perf_counter로 잰 값이고, 예열 1회 뒤 5회 중 최솟값입니다(원값 5개는 결과 파일에). 메모리는 따로 한 번 더 돌려tracemalloc피크(그 호출이 새로 할당한 양)를 잽니다. 대량 읽기는 새 프로세스에서 결과를 쥔 채 RSS 증가분도 잽니다(3회 중앙값). - 매 회차 같은 데이터·같은 상태에서 시작합니다. 쓰기는 트랜잭션 안에서 재고 롤백하며, PostgreSQL 은 회차마다
VACUUM ANALYZE를 합니다. - 입력 만들기는 시간에 넣지 않습니다. Django·django-pgbulk 는 모델 인스턴스, 브리지·SQLAlchemy 는 딕셔너리를 미리 만들어 두고 쓰기 호출만 잽니다. 실제로는 인스턴스를 만드는 비용이 Django 쪽에 더 붙습니다.
- 비교 대상은 그 도구다운 방법으로 씁니다. Django
bulk_update·bulk_create는batch_size기본값과1000둘 다, django-pgbulk 는update()·copy()(text·binary)입니다. - "별도 엔진"이라 적은 SQLAlchemy 수치는 브리지가 아닙니다. SQLAlchemy 를 단독으로 쓸 때의 기준선으로, 자체
Engine이 Django 밖에서 따로 연결을 엽니다(Django 트랜잭션·쿼리 집계 밖). 브리지는 이 방식을 쓰지 않습니다(위 "설계 원칙").
1. PK 기준 대량 UPDATE (컬럼 3개)
| 5,000행 시간 (ms) | 50,000행 시간 (ms) | |
|---|---|---|
Django bulk_update() (batch_size 기본값) |
4,156 | 측정 안 함 ¹ |
Django bulk_update(batch_size=1000) |
1,484 | 15,569 |
django-pgbulk update() |
59.8 | 1,130 |
| SQLAlchemy ORM bulk UPDATE (별도 엔진) | 67.1 | 934 |
브리지 execute(stmt, [params...]) (executemany) |
110 | 1,184 |
브리지 bulk_update() |
32.2 | 333 |
결과 파일: bench/results/2026-10-25-postgres-update.json
¹ PostgreSQL 에서 batch_size가 없으면 Django 는 모든 행을 컬럼마다 CASE WHEN id = … THEN … 하나에 담은 UPDATE 한 문장을 보냅니다. 5,000행에서도 위처럼 느리고, 50,000행에서는 (이전 로컬 측정 때) 서버 백엔드가 CPU 100%·메모리 3.6 GB 로 30분 넘게 끝나지 않고 취소에도 응답하지 않아 프로세스를 강제로 끝냈습니다. 그래서 재지 않았습니다.
² SQLite 의 batch_size 기본값 실패는 Django 6.1.2 에서 재현됩니다. 기본 배치 크기를 SQLITE_LIMIT_VARIABLE_NUMBER를 행당 파라미터 2 + 컬럼 수로 나눠 정하는데, 실제 문장은 행당 2 × 컬럼 수 + 1개를 써서 두 컬럼 이상을 갱신하면 한도를 넘습니다(같은 5,000행·3컬럼이 Django 5.2.18 에서는 성공). 언제 넘는지는 SQLite 빌드의 한도에 달렸습니다. 이 측정의 Ubuntu SQLite 는 한도가 250,000 이라 기본 배치가 50,000행이 되고, 5,000행은 한 문장(파라미터 35,001개)으로 성공하지만 50,000행(350,001개)은 실패합니다. 한도가 SQLite 기본값 32,766 인 빌드(예: uv 가 설치하는 Python)에서는 5,000행부터 실패합니다.
| 5,000행 시간 (ms) | 50,000행 시간 (ms) | |
|---|---|---|
Django bulk_update() (batch_size 기본값) |
1,385 | 실패: OperationalError ² |
Django bulk_update(batch_size=1000) |
1,060 | 14,651 |
| SQLAlchemy ORM bulk UPDATE (별도 엔진) | 21.1 | 292 |
브리지 execute(stmt, [params...]) (executemany) |
28.9 | 321 |
브리지 bulk_update() |
11.7 | 137 |
결과 파일: bench/results/2026-10-25-sqlite-update.json
2. 대량 INSERT
PostgreSQL 표는 위 환경과 다른 실행(다른 러너 CPU)에서 쟀습니다.
PostgreSQL 18.6 (Debian 18.6-1.pgdg13+2) · Python 3.12.3 · Django 6.1.2 · SQLAlchemy 2.1.6 · psycopg 3.3.6 · django-pgbulk 3.3.0 · django-cte 4.0.0 · AMD EPYC 7763 64-Core Processor (4코어, 메모리 16 GiB) · Linux-6.17.0-1022-azure-x86_64-with-glibc2.39 · 반복 5회(+예열 1회) 중 최솟값
| 20,000행 시간 (ms) | 200,000행 시간 (ms) | |
|---|---|---|
Django bulk_create() (batch_size 기본값) |
440 | 4,813 |
Django bulk_create(batch_size=1000) |
460 | 4,829 |
django-pgbulk copy() |
231 | 2,297 |
django-pgbulk copy(binary=True) |
210 | 2,069 |
SQLAlchemy Core insert() (별도 엔진) |
449 | 5,045 |
SQLAlchemy Core insert().returning(id) (별도 엔진) |
702 | 7,627 |
브리지 execute(insert(t), [rows...]) (executemany) |
1,367 | 12,171 |
브리지 bulk_insert() |
327 | 3,571 |
브리지 bulk_insert(returning=['id']) |
342 | 3,732 |
브리지 bulk_insert(method="copy") |
174 | 1,925 |
결과 파일: bench/results/2026-10-26-postgres-insert.json
| 20,000행 시간 (ms) | 200,000행 시간 (ms) | |
|---|---|---|
Django bulk_create() (batch_size 기본값) |
316 | 10,066 |
Django bulk_create(batch_size=1000) |
231 | 7,392 |
SQLAlchemy Core insert() (별도 엔진) |
83.1 | 883 |
SQLAlchemy Core insert().returning(id) (별도 엔진) |
93.6 | 1,261 |
브리지 execute(insert(t), [rows...]) (executemany) |
205 | 2,152 |
브리지 bulk_insert() |
124 | 1,474 |
브리지 bulk_insert(returning=['id']) |
149 | 1,520 |
결과 파일: bench/results/2026-10-25-sqlite-insert.json
3. 20,000행 읽기 (컬럼 7개): 시간과 메모리
| 시간 (ms) | tracemalloc 피크 (MiB) | RSS 증가 (MiB) | |
|---|---|---|---|
Django 모델 객체 list(qs) |
71.7 | 14.2 | 15.8 |
Django values() |
39.7 | 12.4 | 16.4 |
Django values_list() |
33.0 | 7.2 | 11.2 |
| SQLAlchemy ORM 객체 (별도 엔진) | 100 | 25.2 | 29.7 |
SQLAlchemy Core Row (별도 엔진) |
25.3 | 8.4 | 12.6 |
브리지 execute_result().all() (Row) |
36.3 | 8.4 | 9.0 |
브리지 execute() (튜플) |
32.1 | 7.2 | 11.3 |
결과 파일: bench/results/2026-10-25-postgres-read.json
| 시간 (ms) | tracemalloc 피크 (MiB) | RSS 증가 (MiB) | |
|---|---|---|---|
Django 모델 객체 list(qs) |
120 | 15.6 | 15.3 |
Django values() |
82.9 | 13.8 | 15.9 |
Django values_list() |
76.9 | 10.5 | 12.6 |
| SQLAlchemy ORM 객체 (별도 엔진) | 84.6 | 25.4 | 28.1 |
SQLAlchemy Core Row (별도 엔진) |
34.4 | 11.9 | 14.0 |
브리지 execute_result().all() (Row) |
73.3 | 10.4 | 12.7 |
브리지 execute() (튜플) |
73.9 | 10.4 | 12.4 |
결과 파일: bench/results/2026-10-25-sqlite-read.json
결과를 쥐지 않고 쪼개 읽기만 할 때(PostgreSQL, 서버 측 커서):
| 시간 (ms) | tracemalloc 피크 (MiB) | |
|---|---|---|
Django values_list().iterator(chunk_size=2000) |
34.6 | 1.4 |
브리지 stream(chunk_size=2000) |
32.4 | 1.4 |
결과 파일: bench/results/2026-10-25-postgres-read.json
메모리 지침. 행을 많이 읽을 때는 모델 객체(Django 든 SQLAlchemy ORM 이든)가 아니라 튜플·행으로 받으세요. 브리지 execute()의 튜플은 Django values_list()와 같은 수준이고, 다 쥘 필요가 없으면 stream()이 메모리를 청크 크기로 묶습니다(Django iterator()와 같은 수준).
4. 쿼리 생성 오버헤드: PK 조회 5,000번
| 시간 (ms) | 호출당 (µs) | |
|---|---|---|
| Django 커서에 SQL 직접 | 877 | 175 |
Django objects.get(pk=...) |
1,844 | 369 |
Django values_list(...).get(pk=...) |
2,045 | 409 |
SQLAlchemy Core, 문장 1회 생성 + bindparam (별도 엔진) |
902 | 180 |
| SQLAlchemy Core, 매번 문장 생성 (별도 엔진) | 1,300 | 260 |
브리지 execute(), 문장 1회 생성 + bindparam |
1,188 | 238 |
브리지 execute(), 매번 문장 생성 |
2,253 | 451 |
(참고) 브리지 내부 prepare()만 (캐시 적중 + 파라미터 변환), DB 없음 |
33.2 | 6.65 |
(참고) 내부 prepare() 1회 후 커서 하나로 실행·변환만 |
878 | 176 |
결과 파일: bench/results/2026-10-26-postgres-lookup.json
| 시간 (ms) | 호출당 (µs) | |
|---|---|---|
| Django 커서에 SQL 직접 | 41.9 | 8.37 |
Django objects.get(pk=...) |
672 | 134 |
Django values_list(...).get(pk=...) |
837 | 167 |
SQLAlchemy Core, 문장 1회 생성 + bindparam (별도 엔진) |
119 | 23.8 |
| SQLAlchemy Core, 매번 문장 생성 (별도 엔진) | 322 | 64.4 |
브리지 execute(), 문장 1회 생성 + bindparam |
127 | 25.3 |
브리지 execute(), 매번 문장 생성 |
895 | 179 |
(참고) 브리지 내부 prepare()만 (캐시 적중 + 파라미터 변환), DB 없음 |
33.0 | 6.60 |
(참고) 내부 prepare() 1회 후 커서 하나로 실행·변환만 |
67.2 | 13.4 |
결과 파일: bench/results/2026-10-26-sqlite-lookup.json
- 이 표는 위 환경 줄과 다른 실행(결과 파일의
ci_run, 러너 CPU AMD EPYC 9V74)에서 다시 잰 값입니다(#28 컴파일 캐시, #60 결과 변환기 캐시 반영). 러너 CPU 가 달라 절대값을 위 표들과 견주지 마세요. - 브리지는 같은 문장 객체를 다시 실행하면 컴파일을 건너뜁니다(위 "실행하기"의 컴파일 캐시).
bindparam으로 한 번 만든 문장은 첫 호출에만 컴파일하고, 매번 새로 만든 문장은 매번 컴파일합니다. 두 행의 차이(PostgreSQL 약 210µs, SQLite 약 150µs)가 호출당 컴파일 비용입니다. 문장을 한 번 만들어bindparam으로 재사용하세요. - "(참고)
prepare()만" 행은 캐시 적중 뒤 남는 브리지 쪽 일(파라미터 변환, 연결 객체에 둔 결과 변환기 꺼내기)이고 호출당 약 6.6µs 입니다. "(참고)prepare()1회" 행은 그것마저 한 번만 하고 커서 하나로 실행·변환만 한 값으로, 공개 API 가 아닙니다. 브리지execute()는 호출마다 Django 커서를 새로 엽니다(Djangoobjects.get()도 마찬가지). PostgreSQL 에서execute()가 두 참고 행의 합보다 느린 몫은 그 때문으로 보이지만 따로 재지는 않았습니다. - PostgreSQL 에서
bindparam재사용 브리지(호출당 238µs)는 Djangoobjects.get()(369µs)보다 빠르고, SQLAlchemy 단독 엔진(180µs)과의 차이는 58µs 입니다. SQLite 에서는 25.3µs 로 SQLAlchemy 단독(23.8µs)과 같은 자릿수이고 Django ORM 조회(134µs 이상)보다 5배 남짓 빠릅니다.
5. 비동기 (PostgreSQL, PK 조회)
| 시간 (ms) | 쿼리당 (µs) | |
|---|---|---|
(기준) 동기 코드에서 execute() 1,000번 |
266 | 266 |
aget() 1,000번 순차 |
403 | 403 |
arun() 1,000번 순차 (호출마다 쿼리 1개) |
402 | 402 |
같은 것, CONN_MAX_AGE=0 (호출마다 재연결) |
5,305 | 5,305 |
gather 100건 × aget() |
32.4 | 324 |
gather 100건 × arun() |
36.6 | 366 |
gather 1,000건 × aget() |
377 | 377 |
gather 1,000건 × arun() |
343 | 343 |
작업 단위(쿼리 5개) 200개 순차, 쿼리마다 aget() |
375 | 375 |
작업 단위(쿼리 5개) 200개 순차, 단위마다 arun() |
306 | 306 |
작업 단위 200개 gather, 쿼리마다 aget() |
311 | 311 |
작업 단위 200개 gather, 단위마다 arun() |
283 | 283 |
결과 파일: bench/results/2026-10-25-postgres-async.json
- 쿼리 하나짜리 호출에서는
arun과aget()이 같은 수준입니다. 둘 다 thread-sensitive 스레드 하나에서 차례로 돌기 때문에gather로 동시에 불러도 처리량이 크게 늘지 않습니다(순차 대비 쿼리당 시간이 5~20% 줄어드는 정도). arun의 이점은 속도보다 트랜잭션을 async 코드에서 쓸 수 있다는 것입니다. 쿼리 여러 개를 한 번에 넘기면 스레드 위임이 줄어 순차 실행에서 빨라집니다(작업 단위 200개 순차에서 약 20%). 작업 단위를gather로 동시에 돌린 경우는 차이가 10% 안팎이라 이 측정만으로 어느 쪽이 빠르다고 하기 어렵습니다.CONN_MAX_AGE=0(기본값)이면arun은 호출마다 다시 연결합니다(위 "연결 수명"). 표에서 보듯 가장 큰 비용이므로arun을 자주 부른다면CONN_MAX_AGE나 연결 풀을 쓰세요.- SQLAlchemy
AsyncEngine·psycopg 비동기 연결은 재지 않았습니다. #1 에서 Django 트랜잭션·잠금·쿼리 집계 밖에서 돈다는 이유로 탈락했고 브리지 API 가 아닙니다.
6. CTE·윈도 함수 리포트 쿼리 (PostgreSQL, 20,000행)
CTE + RANK() (500행) 시간 (ms) |
|
|---|---|
| Django 커서에 SQL 직접 | 3.38 |
Django ORM (CTE 없이 집계 + Window) |
3.68 |
| Django + django-cte | 4.02 |
브리지 (select().cte() + rank().over()) |
3.71 |
결과 파일: bench/results/2026-10-25-postgres-report.json
누적 합 SUM() OVER (20,000행) 시간 (ms) |
|
|---|---|
Django ORM Window(Sum(...), partition_by=...) |
25.0 |
브리지 func.sum().over(partition_by=...) |
20.3 |
결과 파일: bench/results/2026-10-25-postgres-report.json
모든 변형이 같은 행을 돌려주는지 측정 중에 확인합니다. 결과가 작은 집계(위 표)는 DB 실행이 시간의 대부분이라 도구 차이가 거의 없고, 행이 많은 결과(아래 표)는 행을 만들고 변환하는 비용에서 차이가 납니다.
7. 대량 쓰기의 batch_size (1,000,000행)
batch_size에 따른 시간, 클라이언트 tracemalloc 피크, (PostgreSQL) 서버 백엔드 메모리입니다. PostgreSQL 에서 batch_size=None은 한 문장이고, method="copy"는 배치마다 COPY 하나입니다. 서버 백엔드 메모리는 따로 한 번 더, 새 연결에서 그 연결의 PostgreSQL 백엔드 프로세스 /proc/<pid>/status를 2 ms 마다 읽어 호출 중 RssAnon(공유 버퍼를 뺀 개인 메모리) 최댓값에서 호출 전 값을 뺀 것입니다. 200,000행 결과와 VmHWM은 결과 파일에 있습니다. 이 절의 표는 위 표들과 다른 실행(다른 러너 CPU)에서 쟀습니다.
PostgreSQL 18.6 (Debian 18.6-1.pgdg13+2) · Python 3.12.3 · Django 6.1.2 · SQLAlchemy 2.1.6 · psycopg 3.3.6 · django-pgbulk 3.3.0 · django-cte 4.0.0 · AMD EPYC 7763 64-Core Processor (4코어, 메모리 16 GiB) · Linux-6.17.0-1022-azure-x86_64-with-glibc2.39 · 반복 5회(+예열 1회) 중 최솟값
| 시간 (ms) | tracemalloc 피크 (MiB) | 서버 백엔드 메모리 증가 (MiB) | |
|---|---|---|---|
bulk_insert() (batch_size=None) |
17,958 | 848.9 | 233.3 |
bulk_insert(batch_size=10_000) |
17,333 | 226.0 | 6.1 |
bulk_insert(batch_size=50_000) |
17,368 | 388.9 | 26.9 |
bulk_insert(batch_size=200_000) |
17,582 | 643.5 | 68.2 |
bulk_insert(returning=['id']) (batch_size=None) |
18,551 | 848.9 | 235.8 |
bulk_insert(returning=['id'], batch_size=50_000) |
17,417 | 259.4 | 28.9 |
bulk_insert(method="copy") (batch_size=None) |
9,549 | 193.3 | 0.5 |
bulk_insert(method="copy", batch_size=10_000) |
9,929 | 148.0 | 0.5 |
결과 파일: bench/results/2026-10-26-postgres-batch.json
| 시간 (ms) | tracemalloc 피크 (MiB) | 서버 백엔드 메모리 증가 (MiB) | |
|---|---|---|---|
bulk_update() (batch_size=None) |
16,173 | 609.6 | 196.5 |
bulk_update(batch_size=10_000) |
19,544 | 163.1 | 12.8 |
bulk_update(batch_size=50_000) |
20,546 | 299.0 | 26.8 |
bulk_update(batch_size=200_000) |
16,713 | 435.9 | 51.5 |
결과 파일: bench/results/2026-10-26-postgres-batch.json
SQLite 에서는 차이가 작습니다. 시간은 3% 안, tracemalloc 피크는 많아야 7% 줄었습니다. 어차피 executemany()가 행마다 실행하기 때문입니다(returning은 bulk_batch_size() 단위 배치).
| 시간 (ms) | tracemalloc 피크 (MiB) | |
|---|---|---|
bulk_insert() (batch_size=None) |
12,687 | 221.4 |
bulk_insert(batch_size=10_000) |
12,536 | 205.4 |
bulk_insert(batch_size=50_000) |
12,599 | 206.0 |
bulk_insert(batch_size=200_000) |
12,625 | 208.4 |
bulk_insert(returning=['id']) (batch_size=None) |
12,702 | 304.6 |
bulk_insert(returning=['id'], batch_size=50_000) |
12,849 | 304.6 |
결과 파일: bench/results/2026-10-26-sqlite-batch.json
| 시간 (ms) | tracemalloc 피크 (MiB) | |
|---|---|---|
bulk_update() (batch_size=None) |
4,876 | 148.2 |
bulk_update(batch_size=10_000) |
4,760 | 148.2 |
bulk_update(batch_size=50_000) |
4,841 | 148.2 |
bulk_update(batch_size=200_000) |
4,863 | 148.2 |
결과 파일: bench/results/2026-10-26-sqlite-batch.json
8. 여러 독립 문장: execute() 순차 대 execute_pipeline() (PostgreSQL)
같은 문장(bindparam 으로 1회 생성)으로 PK 조회를 하나씩 execute() 하는 것과 (문장, params) 항목으로 execute_pipeline() 한 번에 넘기는 것, 그리고 서로 독립인 집계 쿼리 5개(대시보드 한 화면)를 비교합니다. 모든 변형이 같은 행을 돌려주는지 확인합니다.
| PK 조회 1,000번 시간 (ms) | 5,000번 시간 (ms) | |
|---|---|---|
execute()를 문장마다 (트랜잭션 안) |
144 | 726 |
execute_pipeline() (트랜잭션 안) |
46.7 | 446 |
execute()를 문장마다 (트랜잭션 밖) |
141 | 752 |
execute_pipeline() (트랜잭션 밖, 자체 atomic()) |
47.7 | 447 |
결과 파일: bench/results/2026-10-26-postgres-pipeline.json
| 집계 쿼리 5개 1회 시간 (ms) | |
|---|---|
execute()를 문장마다 (트랜잭션 안) |
7.16 |
execute_pipeline() (트랜잭션 안) |
6.62 |
결과 파일: bench/results/2026-10-26-postgres-pipeline.json
- 이 표는 위 환경 줄과 다른 실행(결과 파일의
ci_run)에서 같은 종류의 러너로 잰 값입니다. - 파이프라인은 왕복 수를 줄이는 것이라, 이득은 문장 하나의 실행 시간에 비해 왕복이 클수록 커집니다. 이 러너의 PostgreSQL 은 같은 VM 의 서비스 컨테이너라 왕복이 짧은데도 PK 조회 1,000번에서 약 3배였습니다. 네트워크를 건너는 서버에서는 재지 않았습니다.
- 5,000번에서는 1.6배로 줄었습니다. CI 러너에서는 5,000번이 1,000번의 약 9.5배였으나 로컬(PG 컨테이너)에서는 문장 수에 비례했습니다. 러너의 특성으로 보이며 원인은 재지 않았습니다.
- 대시보드처럼 문장마다 서버 실행(20,000행 집계)이 시간 대부분이면 차이가 작습니다(약 8%). 파이프라인은 서버에서 문장을 동시에 실행하지 않습니다.
- 트랜잭션 밖에서는
execute_pipeline()이 자체atomic()을 열어COMMIT왕복이 하나 늘지만, 표에서 차이가 보이지 않을 만큼 작습니다.
9. CSV 내보내기: copy_to() 대 행 읽기 + csv.writer (PostgreSQL, 컬럼 7개)
표 전체(헤더 포함)를 메모리 버퍼에 CSV 바이트로 씁니다. copy_to()는 서버가 쓴 바이트를 모으고, 나머지는 행을 읽어 csv.writer로 씁니다. 출력 텍스트는 세부가 다릅니다(서버는 t/f·+00, csv.writer는 파이썬 str()). tracemalloc 에는 출력 버퍼(20,000행에 약 1.3 MB)도 들어갑니다. 위 환경과 다른 실행(다른 러너 CPU)에서 쟀습니다.
PostgreSQL 18.6 (Debian 18.6-1.pgdg13+2) · Python 3.12.3 · Django 6.1.2 · SQLAlchemy 2.1.6 · psycopg 3.3.6 · django-pgbulk 3.3.0 · django-cte 4.0.0 · INTEL(R) XEON(R) PLATINUM 8573C (4코어, 메모리 16 GiB) · Linux-6.17.0-1022-azure-x86_64-with-glibc2.39 · 반복 5회(+예열 1회) 중 최솟값
| 20,000행 시간 (ms) | 20,000행 tracemalloc 피크 (MiB) | 200,000행 시간 (ms) | 200,000행 tracemalloc 피크 (MiB) | |
|---|---|---|---|---|
Django values_list() + csv.writer |
70.6 | 11.0 | 755 | 110.4 |
Django values_list().iterator(chunk_size=2000) + csv.writer |
79.3 | 4.1 | 777 | 40.0 |
브리지 execute() + csv.writer |
70.4 | 11.0 | 751 | 110.3 |
브리지 stream(chunk_size=2000) + csv.writer |
74.0 | 4.1 | 766 | 40.0 |
브리지 copy_to() (COPY TO STDOUT) |
22.1 | 1.6 | 237 | 12.3 |
결과 파일: bench/results/2026-10-26-postgres-export.json
copy_to()는 200,000행에서 237 ms 로 execute()·stream() + csv.writer(751·766 ms)의 3분의 1 이하였습니다. 파이썬 행을 만들지 않아 tracemalloc 피크는 출력 버퍼 수준(12.3 MiB, stream() + csv.writer는 40.0 MiB)입니다. 행을 쥐는 execute()·values_list()는 110 MiB 입니다.
브리지가 도움이 안 되는 경우
- 일반 CRUD. 한 행을 읽고 쓰는 일은
bindparam문장을 재사용하면 Django ORM 보다 빠르지만 매번 문장을 만들면 조금 느립니다(시나리오 4). 속도 차이 말고는 얻는 것이 없으니 signal·save()·검증이 따라오는 ORM 을 쓰세요. - 대량 INSERT 만 필요하고 생성된 id 가 필요 없을 때, django-pgbulk 를 이미 쓴다면. PostgreSQL 에서는 COPY 가 가장 빠르고, 브리지
bulk_insert(method="copy")와 django-pgbulkcopy()는 같은 부류입니다(200,000행에서 1,925 ms 대 2,297 ms, binary 2,069 ms, 시나리오 2. 입력 만들기는 빼고 잼). 브리지bulk_insert()(unnest)는 그 두 배 가까이 걸리고 Djangobulk_create()보다는 25% 안팎 빠릅니다. 바꿀 이유는 속도보다 SQLAlchemy 식이 필요한지에 있습니다. - django-pgbulk 를 이미 쓴다면. PK 기준 대량 UPDATE 에서 브리지가 더 빠르긴 하지만 둘 다 Django
bulk_update보다 한 자릿수 이상 빠른 같은 부류입니다(시나리오 1). 바꿀 이유는 속도보다 SQLAlchemy 식이 필요한지에 있습니다. - ORM 으로 쓸 수 있는 리포트 쿼리. CTE·윈도 함수 쿼리는 실행 시간이 DB 에서 정해져 도구 차이가 거의 없고, 이 예처럼 Django ORM(CTE 없이
Window로)이나 django-cte 로 표현되면 그대로 두면 됩니다(시나리오 6). 브리지는 ORM 으로 쓰기 어려운 식(여러 CTE,LATERAL, 복잡한 조인)에서 의미가 있습니다. - SQLite 에서 Django 트랜잭션이 필요 없을 때. SQLite 에서는 SQLAlchemy 를 단독으로(별도 엔진) 쓰는 편이 대량 INSERT·읽기에서 브리지보다 빠릅니다(시나리오 2·3). 브리지는 값을 Django 필드 변환기로 바꾸는 비용을 내는 대신 ORM 과 같은 값·같은 트랜잭션을 줍니다.
- 여러 행 업서트를 ORM
bulk_create(update_conflicts=True)로 쓸 수 있을 때. 입력마다 달라지는 여러 행VALUES문장은 호출마다 컴파일되어, 있는 행을 잠가 읽고bulk_create(update_conflicts=True)하는 ORM 이 1.4~2.3배 빨랐습니다(위 "같은 요청, 두 구현"). 브리지는 기존 값에 더하는 갱신을 한 문장으로 해야 할 때의 선택지입니다. - SQLite executemany 형태의
execute(stmt, [params…]). 행마다 SQLAlchemy 로 파라미터를 만들기 때문에bulk_update()·bulk_insert()보다 느립니다. 대량 쓰기는bulk_*를 쓰세요(시나리오 1·2).
지원 대상
SQLite, PostgreSQL(psycopg 3), MySQL 8.4 LTS(mysqlclient; Django 5.2·6.1 모두 지원하는 버전), Oracle(oracledb thin 모드) · Django 5.2 이상 · SQLAlchemy 2.0 이상 2.2 미만(Oracle 의 JSON 키·경로는 2.1 이상) · Python 3.12 이상
PostgreSQL 은 Django 기본(클라이언트측 바인딩)뿐 아니라 OPTIONS={"server_side_binding": True, "prepare_threshold": 5}(서버측 바인딩, prepared statement)에서도 동작합니다(CI 가 두 설정 모두 돌립니다).
Oracle 은 Django 5.2·6.1 이 19c 이상을 받지만, 검증한 버전은 CI 의 Oracle 23ai Free(gvenzl/oracle-free:23-slim-faststart)뿐입니다. 무료 19c 이미지가 없어 19c 에서는 돌려 보지 않았고, SELECT 목록의 불리언 식은 19c 에 없습니다.
MariaDB 는 컴파일과 RETURNING 판정(INSERT·DELETE 는 되고 UPDATE 는 안 됨)만 맞춰 두었고 CI 에서 돌리지 않습니다. 로컬에서 MariaDB 11.4 로 테스트를 한 번 돌렸을 때 JSON 키·문서 비교가 ORM 과 다르게 나오고(MariaDB 의 JSON 은 텍스트이고 ORM 은 양쪽에 JSON_UNQUOTE를 씌움) LATERAL이 없었습니다. JSON 컬럼을 비교하는 쿼리는 MariaDB 에서 ORM 결과와 대조해 쓰세요.
라이선스
MIT
Metadata
Release files for django-sqlalchemy-bridge 0.2.0rc1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| django_sqlalchemy_bridge-0.2.0rc1.tar.gz | 335.8 kB | With provenance | Details for django_sqlalchemy_bridge-0.2.0rc1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| django_sqlalchemy_bridge-0.2.0rc1-py3-none-any.whl | Python 3 | none | any | Details for django_sqlalchemy_bridge-0.2.0rc1-py3-none-any.whl |
Total release size: 413.4 kB
Release files / django_sqlalchemy_bridge-0.2.0rc1.tar.gz
| Download URL | django_sqlalchemy_bridge-0.2.0rc1.tar.gz |
|---|---|
| Size | 335.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a31d8d5da62e4f0be23dd8c23927b4d80151bed2d29b5d91c2f1510e2ea68ba4
|
|
BLAKE2b-256 checksum How to use checksums |
3b5111fb828a6ec91ed8a62b3d6ffe0677e2ae2ea128e2d91d04072afb852091
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logRelease files / django_sqlalchemy_bridge-0.2.0rc1-py3-none-any.whl
| Download URL | django_sqlalchemy_bridge-0.2.0rc1-py3-none-any.whl |
|---|---|
| Size | 77.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
764799c88f8ac7af7c9eb0a3a60c0f2c88c89065434329b9f4cc495772a16310
|
|
BLAKE2b-256 checksum How to use checksums |
b7ae8fc59c9df22b14ddcd5f9fc7f74947425f513cc62d8957011caa6b558c9b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logSecurity for django-sqlalchemy-bridge 0.2.0rc1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for django_sqlalchemy_bridge-0.2.0rc1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.