> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ClickHouse SQLAlchemy 지원

# SQLAlchemy 지원

ClickHouse Connect에는 핵심 드라이버를 기반으로 한 SQLAlchemy 방언(`clickhousedb`)이 포함되어 있습니다. 이 방언은 SQLAlchemy Core API를 대상으로 하며 SQLAlchemy 1.4.40+ 및 2.0.x를 지원합니다.

<div id="sqlalchemy-connect">
  ## SQLAlchemy로 연결하기
</div>

`clickhousedb://` 또는 `clickhousedb+connect://` URL을 사용해 엔진을 생성합니다. 쿼리 매개변수는 ClickHouse 설정, 클라이언트 옵션, HTTP/TLS 전송 옵션에 대응됩니다.

```python theme={null}
from sqlalchemy import create_engine, text

engine = create_engine(
    "clickhousedb://user:password@host:8123/mydb?compression=zstd"
)

with engine.begin() as conn:
    rows = conn.execute(text("SELECT version()"))
    print(rows.scalar())
```

URL/쿼리 매개변수 관련 참고 사항:

* ClickHouse 설정: 쿼리 매개변수로 전달합니다(예: `use_skip_indexes=0`).
* 클라이언트 옵션: `compression`(`compress`의 별칭), `query_limit`, 시간 초과 설정 등입니다.
* HTTP/TLS 옵션: HTTP 풀과 TLS용 옵션입니다(예: `ch_http_max_field_name_size=99999`, `ca_cert=certifi`).

지원되는 옵션의 전체 목록은 아래 섹션의 [Connection arguments and Settings](/ko/integrations/language-clients/python/driver-api#connection-arguments)를 참조하십시오. 이러한 옵션은 SQLAlchemy DSN을 통해서도 지정할 수 있습니다.

<div id="sqlalchemy-core-queries">
  ## 핵심 쿼리
</div>

이 방언은 조인, 필터, 정렬, LIMIT/OFFSET, `DISTINCT`를 포함한 SQLAlchemy Core `SELECT` 쿼리를 지원합니다.

```python theme={null}
from sqlalchemy import MetaData, Table, select

metadata = MetaData(schema="mydb")
users = Table("users", metadata, autoload_with=engine)
orders = Table("orders", metadata, autoload_with=engine)

# 기본 SELECT
with engine.begin() as conn:
    rows = conn.execute(select(users.c.id, users.c.name).order_by(users.c.id).limit(10)).fetchall()

# 조인 (INNER/LEFT OUTER/FULL OUTER/CROSS)
with engine.begin() as conn:
    stmt = (
        select(users.c.name, orders.c.product)
        .select_from(users.join(orders, users.c.id == orders.c.user_id))
    )
    rows = conn.execute(stmt).fetchall()
```

필수 `WHERE` 절이 포함된 경량 `DELETE`를 지원합니다:

```python theme={null}
from sqlalchemy import delete

with engine.begin() as conn:
    conn.execute(delete(users).where(users.c.name.like("%temp%")))
```

<div id="sqlalchemy-ddl-reflection">
  ## DDL 및 리플렉션
</div>

제공된 DDL 헬퍼와 타입/엔진 구문을 사용하여 데이터베이스와 테이블을 생성할 수 있습니다. 테이블 리플렉션(컬럼 타입과 엔진 포함)이 지원됩니다.

```python theme={null}
import sqlalchemy as db
from sqlalchemy import MetaData
from clickhouse_connect.cc_sqlalchemy.ddl.custom import CreateDatabase, DropDatabase
from clickhouse_connect.cc_sqlalchemy.ddl.tableengine import MergeTree
from clickhouse_connect.cc_sqlalchemy.datatypes.sqltypes import UInt32, String, DateTime64

with engine.begin() as conn:
    # 데이터베이스
    conn.execute(CreateDatabase("example_db", exists_ok=True))

    # 테이블
    metadata = MetaData(schema="example_db")
    table = db.Table(
        "events",
        metadata,
        db.Column("id", UInt32, primary_key=True),
        db.Column("user", String),
        db.Column("created_at", DateTime64(3)),
        MergeTree(order_by="id"),
    )
    table.create(conn)

    # 리플렉션
    reflected = db.Table("events", metadata, autoload_with=engine)
    assert reflected.engine is not None
```

리플렉션된 컬럼에는 서버에 존재하는 경우 `clickhousedb_default_type`, `clickhousedb_codec_expression`, `clickhousedb_ttl_expression`와 같은 방언별 속성도 포함됩니다.

<div id="sqlalchemy-inserts">
  ## 삽입 (Core 및 기본 ORM)
</div>

편의를 위해 SQLAlchemy Core뿐 아니라 간단한 ORM 모델을 사용해서도 삽입할 수 있습니다.

```python theme={null}
# Core 삽입
with engine.begin() as conn:
    conn.execute(table.insert().values(id=1, user="joe"))

# 기본 ORM 삽입
from sqlalchemy.orm import declarative_base, Session

Base = declarative_base(metadata=MetaData(schema="example_db"))

class User(Base):
    __tablename__ = "users"
    __table_args__ = (MergeTree(order_by=["id"]),)
    id = db.Column(UInt32, primary_key=True)
    name = db.Column(String)

Base.metadata.create_all(engine)

with Session(engine) as session:
    session.add(User(id=1, name="Alice"))
    session.bulk_save_objects([User(id=2, name="Bob")])
    session.commit()
```

<div id="scope-and-limitations">
  ## 범위 및 제한 사항
</div>

* 핵심 범위: `JOIN`(`INNER`, `LEFT OUTER`, `FULL OUTER`, `CROSS`)이 포함된 `SELECT`, `WHERE`, `ORDER BY`, `LIMIT`/`OFFSET`, `DISTINCT` 같은 SQLAlchemy Core 기능을 지원합니다.
* `WHERE`가 있는 `DELETE`만 지원: 이 방언은 경량 `DELETE`를 지원하지만, 실수로 테이블 전체가 삭제되는 것을 방지하려면 명시적인 `WHERE` 절이 필요합니다. 테이블을 비우려면 `TRUNCATE TABLE`을 사용하십시오.
* `UPDATE` 미지원: ClickHouse는 append에 최적화되어 있습니다. 이 방언은 `UPDATE`를 구현하지 않습니다. 데이터를 변경해야 하는 경우 업스트림에서 변환을 적용한 후 다시 삽입하거나, 사용자 책임하에 명시적인 텍스트 SQL(예: `ALTER TABLE ... UPDATE`)을 사용하십시오.
* DDL 및 리플렉션: 데이터베이스와 테이블 생성이 지원되며, 리플렉션은 컬럼 타입과 테이블 엔진 메타데이터를 반환합니다. ClickHouse는 이러한 제약 조건을 강제하지 않으므로 일반적인 PK/FK/인덱스 메타데이터는 제공되지 않습니다.
* ORM 범위: 편의를 위해 Declarative 모델과 `Session.add(...)`/`bulk_save_objects(...)`를 통한 삽입을 사용할 수 있습니다. 고급 ORM 기능(관계 관리, unit-of-work 업데이트, cascading, eager/lazy loading 시맨틱)은 지원되지 않습니다.
* 프라이머리 키 의미: `Column(..., primary_key=True)`는 SQLAlchemy에서 객체 아이덴티티 용도로만 사용됩니다. 이는 ClickHouse에 서버 측 제약 조건을 생성하지 않습니다. `ORDER BY`(및 선택적 `PRIMARY KEY`)는 테이블 엔진(예: `MergeTree(order_by=...)`)을 통해 정의하십시오.
* 트랜잭션 및 서버 기능: 2단계 트랜잭션, 시퀀스, `RETURNING`, 고급 격리 수준은 지원되지 않습니다. `engine.begin()`은 SQL 문을 묶는 Python 컨텍스트 매니저를 제공하지만, 실제 트랜잭션 제어는 수행하지 않습니다(`commit`/`rollback`은 no-op입니다).