> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 컬럼 저장

> vsql::preview::column_store 및 vsql::preview::storage 기능을 사용하면 확장 프로그램이 자신의 사용자 정의 타입에 대해 사용자 정의 바이너리 디스크 레이아웃을 InnoDB에 등록할 수 있습니다.

이 페이지의 기능은 미리보기 단계입니다. API는 안정적이지 않으며, 이 기능을 선언하는 확장 프로그램은 설치 시 `vsql_allow_preview_extensions = ON`이 필요합니다. 미리보기 계층을 활성화하고 기능을 등록하는 방법은 [미리보기 기능](https://villagesql.com/docs/ko/extensions/build/preview-capabilities)을 참조하세요.

컬럼 저장은 확장 프로그램이 InnoDB에 직접 커스텀 유형의 이진 디스크 레이아웃을 등록할 수 있게 해줍니다. 이는 VARBINARY 페이로드를 통해 유형 바이트를 라우팅하는 대신, 커스텀 유형의 디스크 모양을 VARBINARY가 표현할 수 없는 경우(예: 전용 페이지에 저장되어야 하는 밀집된 부동 소수점 배열)에 사용됩니다. 이는 새로운 기능을 제공하는 특성입니다: 기존 레이아웃에 대한 튜닝 장치가 아니라 새로운 저장 레이아웃을 활성화합니다.

> [!WARNING]
>
> 컬럼 저장은 미리보기 ABI입니다 — 개발 중이며 릴리스 간에 변경될 수 있습니다. 현재는 행 수준 지속성만 지원합니다. 커스텀 저장 컬럼은 [사용자 정의 인덱스](https://villagesql.com/docs/ko/extensions/build/custom-indexes.md)만 허용하며, 일반 인덱스는 `ERROR 3219 (HY000): InnoDB: Indexing for types with column storage is supported only with custom index.`로 거부됩니다.

## 기능 선언

두 개의 미리보기 기능이 함께 작동합니다:

* `vsql::preview::storage` — InnoDB 저장소 인프라구조(미니 트랜잭션, 세그먼트, 페이지)에 접근합니다. 파일 범위에서 `StorageCapability`을 선언합니다.
* `vsql::preview::column_store` — 확장 프로그램의 커스텀 유형 중 하나에 대한 저장 구현을 바인딩합니다. `make_column_store<Ctx>(TYPE).…build()`를 사용하여 파일 범위에서 `ColumnStoreCapability`을 선언합니다.

둘 다 `make_extension()`의 `.with()`에 전달되어야 합니다:

```cpp theme={null}
#include <villagesql/preview/storage_builder.h>
#include <villagesql/preview/storage_api.h>
#include <villagesql/vsql.h>

namespace storage = vsql::preview_storage;
using vsql::preview_storage_builder::ColumnStoreCapability;
using vsql::preview_storage_builder::make_column_store;
using vsql::preview_storage_builder::StorageCapability;

struct MyCtx {
  storage::Space::Ref space = 0;
  storage::Segment::PageRef root_page = storage::Page::INVALID_REF;
};

static auto STORAGE = StorageCapability{};

static constexpr auto kMyStorage =
    make_column_store<MyCtx>(MY_TYPE)
        .create<&MyStorage::create>()
        .drop<&MyStorage::drop>()
        .load<&MyStorage::load>()
        .insert<&MyStorage::insert>()
        .select<&MyStorage::select>()
        .mark_delete<&MyStorage::mark_delete>()
        .purge<&MyStorage::purge>()
        .build();

static auto COLUMN_STORE = ColumnStoreCapability().column_store(kMyStorage);

using namespace vsql;

VEF_GENERATE_ENTRY_POINTS(
    make_extension()
        .with(STORAGE)
        .with(COLUMN_STORE)
        .type(MY_TYPE))
```

`make_column_store<MyCtx>(MY_TYPE)`은 구현을 동일한 확장 프로그램에서 등록된 하나의 커스텀 유형과 연결합니다. 모든 7개의 슬롯은 `build()` 시점에 필수적입니다. 각 슬롯은 InnoDB가 정상 운영 중에 도달하는 고유한 컬럼 라이프사이클 단계를 나타내기 때문입니다.

## 일곱 개의 저장 함수

모든 함수는 `storage::Column::StorageCtx<MyCtx>*`를 받습니다. 이 `user()` 접근자는 확장 프로그램의 컬럼별 상태를 반환하고, `arena()`는 보조 개체에 대한 서버 관리 할당을 제공합니다. 모든 함수는 성공 시 `false`를 반환하고, 오류 시 `true`를 반환하며, `error_msg`(용량 `error_msg_len`)에 메시지를 작성합니다. 서버는 그 메시지를 오류 로그에 기록합니다. 실패한 `create` 또는 `insert`는 `ERROR 3219 (HY000): InnoDB: Custom type operation failed. See server error log for details.`로 문을 실패시킵니다.

```cpp theme={null}
// CREATE TABLE / ALTER TABLE ADD COLUMN.
// col_len is the type's persisted length. Reserve segments here and store
// space + root_page in ctx->user() so DML functions can reach them.
bool create(storage::Column::StorageCtx<MyCtx>*, storage::Space::Ref,
            storage::Segment::TrxRef, uint32_t col_len,
            char* error_msg, uint32_t error_msg_len);

// DROP TABLE / ALTER TABLE DROP COLUMN.
// Release any segments reserved in create(). Arena memory is freed by the
// server after this call returns.
bool drop(storage::Column::StorageCtx<MyCtx>*, storage::Segment::TrxRef,
          char* error_msg, uint32_t error_msg_len);

// Called when the server reattaches to existing storage (e.g. after restart).
// Recover space and root_page from the StorageRef set in create().
bool load(storage::Column::StorageCtx<MyCtx>*, storage::Column::StorageRef,
          char* error_msg, uint32_t error_msg_len);

// INSERT. col_data is the encoded value; rowid_prefix identifies the owning
// row. Write into your storage layout and return a Column::Ref the server
// stores in the row payload in place of the value bytes.
bool insert(storage::Column::StorageCtx<MyCtx>*, storage::MtrCtx::Ref,
            storage::Segment::TrxRef, storage::Column::Data col_data,
            storage::Column::Data rowid_prefix, storage::Column::Ref* col_ref,
            char* error_msg, uint32_t error_msg_len);

// SELECT. Given the Column::Ref produced by insert, populate col_data and
// rowid_prefix, and report the writing transaction and delete-mark status.
bool select(storage::Column::StorageCtx<MyCtx>*, storage::MtrCtx::Ref,
            storage::Column::Ref, storage::Column::Data* col_data,
            storage::Column::Data* rowid_prefix, storage::Segment::TrxRef*,
            bool* delete_marked, char* error_msg, uint32_t error_msg_len);

// DELETE (in-transaction). Set or clear the delete-mark flag. The actual
// bytes must remain readable until purge() runs.
bool mark_delete(storage::Column::StorageCtx<MyCtx>*, storage::MtrCtx::Ref,
                 storage::Segment::TrxRef, storage::Column::Ref,
                 bool delete_mark, char* error_msg, uint32_t error_msg_len);

// InnoDB purge. Reclaim storage for entries whose deleting transaction is
// no longer visible to any active snapshot.
bool purge(storage::Column::StorageCtx<MyCtx>*, storage::MtrCtx::Ref,
           storage::Segment::TrxRef, storage::Column::Ref,
           char* error_msg, uint32_t error_msg_len);
```

`mark_delete` 및 `purge`는 InnoDB MVCC가 퍼지가 실행될 때까지 삭제된 행을 오래된 스냅샷에서 읽을 수 있도록 유지해야 하기 때문에 구분됩니다.

## 컬럼별 컨텍스트 및 아레나

C++ SDK는 `create` 또는 `load`를 호출하기 전에 `MyCtx`를 기본 생성합니다 — `ctx->user()`는 함수가 실행될 때 이미 채워져 있습니다. `MyCtx`는 기본 생성 가능해야 하며, C++ SDK는 인수 없이 `T()`를 호출합니다.

`ctx->user()`를 직접 사용하여 상태를 초기화하세요. `ctx->arena().construct<MyCtx>()`를 호출하지 마세요 — 이는 두 번째 사용되지 않는 인스턴스를 할당하고 `ctx->user()`가 이 인스턴스를 가리키지 않습니다.

```cpp theme={null}
bool MyStorage::create(storage::Column::StorageCtx<MyCtx>* ctx,
                       storage::Space::Ref space, storage::Segment::TrxRef trx,
                       uint32_t col_len,
                       char* error_msg, uint32_t error_msg_len) {
  storage::Segment::PageRef root;
  if (storage::Segment::create(space, 1, trx, root) != storage::Error::SUCCESS) {
    snprintf(error_msg, error_msg_len, "%s", storage::last_error().data());
    return true;
  }

  ctx->user()->space = space;
  ctx->user()->root_page = root;
  // Encode space and root into StorageRef so load() can recover both.
  ctx->set_ref((static_cast<storage::Column::StorageRef>(space) << 32) |
               static_cast<storage::Column::StorageRef>(root));
  return false;
}
```

`load`는 동일한 패턴을 따릅니다 — `ctx->user()`는 미리 채워져 있고, `storage_ref`는 `create`에서 `ctx->set_ref()`로 저장된 패킹된 값을 담고 있습니다:

```cpp theme={null}
bool MyStorage::load(storage::Column::StorageCtx<MyCtx>* ctx,
                     storage::Column::StorageRef storage_ref,
                     char* error_msg, uint32_t error_msg_len) {
  ctx->user()->space =
      static_cast<storage::Space::Ref>(storage_ref >> 32);
  ctx->user()->root_page =
      static_cast<storage::Segment::PageRef>(storage_ref & 0xFFFFFFFF);
  ctx->set_ref(storage_ref);
  return false;
}
```

`ctx->arena()`는 `MyCtx`에 직접 포함할 수 없는 크기나 동적 객체를 할당하는 데만 사용하세요. C++ SDK는 `drop`이 반환된 후 자동으로 아레나를 파괴하고 `~MyCtx()`를 호출합니다(성공 여부와 무관).

## InnoDB 접근 유틸리티

InnoDB 원시 기능을 위해 `<villagesql/preview/storage_api.h>`를 포함합니다. 모든 페이지 읽기 및 쓰기는 미니 트랜잭션 내에서 발생해야 합니다:

```cpp theme={null}
storage::MtrCtx mtr;
storage::MtrCtx::Ref mtr_ref = mtr.start();
if (mtr_ref == nullptr) { /* OOM — handle error */ return true; }
// ... page operations ...
mtr.commit();
```

미니 트랜잭션 커밋은 페이지 래치를 해제하고 변경 사항을 영구화하는 redo 로그 기록을 작성합니다.

**세그먼트**는 `create` 시 예약됩니다 — 완전한 설정 패턴은 위 컬럼별 컨텍스트의 `create` 및 `load` 예제를 참조하세요. DML 작업 중에는 루트 페이지에서 세그먼트 참조를 얻어 새 페이지를 할당합니다:

```cpp theme={null}
storage::Page root;
root.load(ctx->user()->space, ctx->user()->root_page,
          storage::Page::Latch::EXCLUSIVE, mtr_ref);
storage::Segment::Ref seg = storage::Segment::get_header(root, 0);
storage::Page data_page;
data_page.load_new(seg, mtr_ref);  // allocates a fresh page
```

**페이지**는 공유 래치로 읽고 배타 래치로 씁니다. InnoDB가 변경 사항을 로깅하도록 `mtr_ref`를 쓰기 호출에 전달합니다:

```cpp theme={null}
// Read: a shared latch
storage::Page page;
page.load(ctx->user()->space, page_num, storage::Page::Latch::SHARED, mtr_ref);
uint32_t v = page.read_integer_4(storage::Page::HEADER_SIZE + offset);
```

```cpp theme={null}
// Write: an exclusive latch. Do not load a page for writing
// when the same mini-transaction already holds it with a shared latch.
storage::Page page;
page.load(ctx->user()->space, page_num, storage::Page::Latch::EXCLUSIVE, mtr_ref);
page.write_integer_4(storage::Page::HEADER_SIZE + offset, v, mtr_ref);
```

페이지 레이아웃 상수:

| 상수 | 값 | 참고 |
| - | - | - |
| `storage::Page::HEADER_SIZE` | `38` | 확장 데이터는 이 오프셋에서 시작됩니다. |
| `storage::Page::TRAILER_SIZE` | `8` | `page_size - TRAILER_SIZE`를 초과하여 쓰지 마세요. |
| `storage::Page::get_size(space)` | runtime | 16384을 하드코딩하는 대신 사용하세요. |

페이지 접근자는 헤더 또는 트레일러 영역 내부의 오프셋을 거부합니다: 릴리스 빌드는 읽기 또는 쓰기를 건너뛰고, `NDEBUG`가 없는 빌드는 `assert`에 실패합니다. InnoDB는 해당 바이트 범위를 자체적인 관리 및 체크섬에 사용합니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.