Guide to Charset and Collation for CB‐Spider RDBMS(KR)

Guide to Charset and Collation for CB-Spider RDBMS

Language: English | 한국어

Overview

• CB-Spider는 RDBMS 인스턴스 내부에 Database를 생성할 때 Charset/Collation을 선택적으로 지정할 수 있는 API를 제공합니다 (mysql/mariadb 엔진 전용).
• CSP마다 이를 실제로 적용하는 방식(네이티브 API, SQL 직접 실행, 저장 프로시저)과 전제조건이 크게 다르며, 일부 CSP는 요청이 "created"로 성공 응답해도 실제로는 요청한 값을 조용히 무시하는 경우가 있었습니다. 본 가이드는 이런 함정을 피해 안전하게 Charset/Collation을 지정하는 방법을 설명합니다.
• 9개 CSP(MySQL) / 4개 CSP(MariaDB) 전체를 대상으로 한 실측 검증 결과와 상세 원리는 rdbms-mysql-test/charset-test README, collation-test README를 참고하세요 — 본 가이드는 그 결과를 바탕으로 한 실전 활용 가이드입니다.

왜 필요한가

• Charset(문자셋): 데이터베이스에 저장되는 문자를 어떤 바이트 인코딩으로 표현할지 정의합니다. 잘못 설정하면 한글/이모지 등 일부 문자가 저장 시 깨지거나(?로 치환) INSERT 자체가 거부될 수 있습니다.
• Collation(콜레이션): 같은 문자셋 내에서 문자열을 정렬(ORDER BY)하고 비교(=, LIKE)할 때의 규칙입니다. 예를 들어 _ci(case-insensitive) 콜레이션은 'ABC'와 'abc'를 같은 값으로 취급하지만, _bin(binary) 콜레이션은 다른 값으로 취급합니다.
• 온프레미스에서 마이그레이션하거나 기존 시스템과 정렬 규칙을 맞춰야 하는 경우, CSP의 기본값이 아닌 특정 Charset/Collation으로 Database를 생성해야 할 때가 많습니다.

CB-Spider의 접근 방식: 값 자체는 검증하지 않습니다

• CB-Spider는 Charset/Collation 값을 고정된 목록(enum)으로 검증하지 않습니다. MySQL/MariaDB는 버전마다 새로운 charset/collation을 추가하며(예: MySQL 8.0의 utf8mb4_0900_ai_ci, MariaDB 11.4.2+의 utf8mb4_uca1400_ai_ci), 이를 CB-Spider가 미리 다 알고 있을 수 없기 때문입니다.
• 대신 CB-Spider는 SQL 식별자로 안전하게 쓸 수 있는 형식인지만 확인합니다(영문자/숫자/언더스코어만 허용). 형식만 통과하면 그 값을 그대로 CSP API 또는 SQL 엔진에 전달하며, 엔진이 그 값을 인식하지 못하면 엔진 자체의 에러 메시지가 그대로 반환됩니다.
• 즉 Charset=invalidvalue처럼 실제로 존재하지 않는 값을 보내면, CB-Spider가 아니라 MySQL/MariaDB 엔진이나 CSP API가 "그런 charset 없음" 에러를 반환합니다.

---

Database 생성 API

POST /spider/rdbms/{Name}/databases

요청 필드

필드	필수	설명
ConnectionName	✅	Connection 이름
DatabaseName	✅	생성할 Database 이름
MasterUserName	조건부	아래 CSP별 지원 방식 참고 — CSP에 따라 필수
MasterUserPassword	조건부	위와 동일
Charset	선택	예: utf8mb4, latin1 — mysql/mariadb에서만 유효
Collation	선택	예: utf8mb4_unicode_ci, utf8mb4_bin — mysql/mariadb에서만 유효

Charset/Collation을 postgres 엔진 인스턴스에 지정하면 에러로 거부됩니다.

호출 예시

curl -u admin:your-secure-password -sX POST \
  http://localhost:1024/spider/rdbms/cb-spider-mysql-test/databases \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "DatabaseName": "mydb",
    "MasterUserName": "myadmin",
    "MasterUserPassword": "Password123!",
    "Charset": "utf8mb4",
    "Collation": "utf8mb4_unicode_ci"
  }' | jq

성공 응답

{ "message": "created" }

⚠️ 이 응답이 "created"라고 해서 Charset/Collation이 반드시 요청한 값대로 적용됐다는 뜻은 아닙니다 — 아래 CSP별 지원 방식에서 설명하는 CSP별 제약을 반드시 확인하세요. (실제로 Azure는 과거 Charset만 단독으로 요청하면 조용히 무시하고 서버 기본값으로 생성한 사례가 있었습니다 — 지금은 CB-Spider가 자동으로 보정합니다. 자세한 내용은 CSP별 참고사항 참고.)

---

CSP별 지원 방식

CB-Spider는 CSP마다 서로 다른 메커니즘으로 Charset/Collation을 적용합니다. MasterUserName/MasterUserPassword가 필요한지 여부도 메커니즘에 따라 다릅니다.

CSP	메커니즘	MasterUserName/Password 필요 여부
Azure, GCP, OpenStack, Alibaba	CSP 네이티브 API — Create Database API 자체가 Charset/Collation 필드를 지원	기본적으로 불필요(단, Azure에서 Charset만 지정하고 Collation을 생략하면 CB-Spider가 실제 기본 Collation을 조회하기 위해 필요 — CSP별 참고사항 참고)
Tencent	네이티브 API(Charset) + SQL(Collation) — Tencent API에는 Collation 필드가 아예 없음	Collation을 지정할 때만 필요 (생성 직후 ALTER DATABASE ... COLLATE ...를 SQL로 추가 실행)
NCP	SQL 저장 프로시저 — NCP 공식 sys.ncp_create_db('name','charset','collation') 호출	Charset 또는 Collation을 하나라도 지정하면 필요
NHN	SQL (CREATE DATABASE ... CHARACTER SET ... COLLATE ...)	Charset 또는 Collation을 하나라도 지정하면 필요 — 추가로 콘솔에서 "Direct Control" 사전 활성화 필요(CSP별 참고사항 참고)
AWS, IBM	SQL (CREATE DATABASE ... CHARACTER SET ... COLLATE ...) — CSP 네이티브 Database 관리 API 자체가 없음	항상 필요 (Charset/Collation 지정 여부와 무관)

MasterUserName/MasterUserPassword는 인스턴스 생성 시 설정한 값을 그대로 다시 전달해야 합니다. CB-Spider는 생성 이후 이 값을 조회 API로 돌려주지 않습니다 — 여러 CSP에서 실제 마스터 계정을 신뢰성 있게 재확인할 방법이 없기 때문입니다.

흐름도 (Charset만 지정했을 때의 CSP별 분기)

flowchart TD
    A["POST .../databases<br/>Charset=X, Collation=(empty)"] --> B{CSP 메커니즘}
    B -->|Azure| C1["Collation 자동 조회 후<br/>네이티브 API 1회 호출"]
    B -->|GCP/OpenStack/Alibaba| C2["네이티브 API 1회 호출<br/>(Collation 생략 가능)"]
    B -->|Tencent| C3["네이티브 API로 Charset만 적용<br/>(Collation 미지정이므로 SQL 불필요)"]
    B -->|NCP| C4["SQL: CALL sys.ncp_create_db<br/>(name, X, '')"]
    B -->|NHN| C5["SQL: CREATE DATABASE ...<br/>CHARACTER SET X<br/>(Direct Control 필요)"]
    B -->|AWS/IBM| C6["SQL: CREATE DATABASE ...<br/>CHARACTER SET X"]

Loading

---

Private Mode에서의 제약

• 위 표에서 **SQL(또는 SQL 기반 저장 프로시저)**을 쓰는 CSP(Tencent의 Collation 적용, NCP, NHN, AWS/IBM)는 CB-Spider 서버가 대상 인스턴스에 직접 TCP로 접속해야 동작합니다.

• 인스턴스가 Private Mode(PublicAccess=false, 공인 IP 없이 사설망에만 존재)이고 CB-Spider 서버에서 그 네트워크로 라우팅 경로가 없다면:

  CSP	영향
  AWS, IBM	Database 생성 자체가 안 됨(Charset/Collation 지정 여부와 무관 — 이 두 CSP는 애초에 전체 생성 경로가 SQL뿐)
  Tencent	Charset만 지정하면 정상 동작, Collation까지 지정하면 그 부분만 실패
  NCP, NHN	Charset/Collation 중 하나라도 지정하면 실패 — 지정하지 않고 기본값으로 생성하는 것은 정상 동작
  Azure	Charset만 지정하고 Collation은 생략한 요청에서만 실패(기본 Collation 자동조회에 SQL 필요) — 둘 다 명시하거나 둘 다 생략하면 영향 없음
  GCP, OpenStack, Alibaba	영향 없음 — Charset/Collation 모두 CSP 네이티브 API로 처리

• CSP 네이티브 API로의 대체는 불가능합니다 — Tencent는 API 자체에 Collation 필드가 없고, NCP의 공식 우회 수단 자체가 SQL 저장 프로시저이며, NHN의 네이티브 API는 애초에 charset/collation 파라미터를 지원하지 않습니다.

• 이런 경우에도 Database를 기본값(엔진 기본 Charset/Collation)으로 생성하는 것은 가능합니다 — 명시적으로 원하는 Charset/Collation을 지정하는 옵션만 쓸 수 없습니다.

• 다른 Private Mode 제약사항 전체 목록(TLS 상태 조회, OpenStack 마스터 권한 등)은 RDBMS Management Guide의 "Private Mode에서 지원되지 않는 기능"을 참고하세요.

---

예시

Charset만 지정 (Collation은 엔진 기본값 사용)

curl -u admin:your-secure-password -sX POST \
  http://localhost:1024/spider/rdbms/cb-spider-mysql-test/databases \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "DatabaseName": "mydb",
    "MasterUserName": "myadmin",
    "MasterUserPassword": "Password123!",
    "Charset": "utf8mb4"
  }' | jq

Collation까지 명시 (정렬/비교 규칙을 정밀하게 제어)

curl -u admin:your-secure-password -sX POST \
  http://localhost:1024/spider/rdbms/cb-spider-mysql-test/databases \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "DatabaseName": "mydb",
    "MasterUserName": "myadmin",
    "MasterUserPassword": "Password123!",
    "Charset": "utf8mb4",
    "Collation": "utf8mb4_bin"
  }' | jq

utf8mb4_general_ci/utf8mb4_0900_ai_ci/utf8mb4_uca1400_ai_ci 같은 "기본값 계열" collation은 MySQL/MariaDB 버전마다 이름이 다릅니다. 반면 utf8mb4_bin(대소문자 구분, 바이트 단위 비교)은 모든 MySQL/MariaDB 버전에서 동일한 이름으로 존재하는 안정적인 값입니다.

실패 사례: Alibaba MariaDB에서 Collation 지정

curl -u admin:your-secure-password -sX POST \
  http://localhost:1024/spider/rdbms/cb-spider-mariadb-test/databases \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "alibaba-beijing-config",
    "DatabaseName": "mydb",
    "MasterUserName": "myadmin",
    "MasterUserPassword": "Password123!",
    "Charset": "utf8mb4",
    "Collation": "utf8mb4_bin"
  }' | jq

응답 (명확한 에러 — 조용히 무시되지 않음)

{ "message": "Alibaba CreateDatabase: Collation is not supported on MariaDB instances (Alibaba's API documents CollationName as MySQL-only, and a MariaDB instance silently ignores it rather than erroring) -- omit Collation and specify only Charset" }

---

Quick Start

export SPIDER_URL=http://localhost:1024
export SPIDER_AUTH=admin:change-your-password

curl -u $SPIDER_AUTH -sX POST \
  "$SPIDER_URL/spider/rdbms/cb-spider-mysql-test/databases" \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "DatabaseName": "mydb",
    "MasterUserName": "myadmin",
    "MasterUserPassword": "Password123!",
    "Charset": "utf8mb4",
    "Collation": "utf8mb4_unicode_ci"
  }' | jq

# 적용 결과 확인 (SQL 클라이언트로 직접 접속)
mysql -h <Endpoint 호스트> -P 3306 -u myadmin -p -e \
  "SELECT DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME='mydb';"

---

AdminWeb에서 확인하기

• RDBMS 인스턴스 상세 패널에서 + Database 버튼을 클릭하면 나타나는 "Create Database" 창에 Database Name 아래 Charset/Collation 입력 필드(둘 다 선택 입력)가 있습니다.
• 두 필드 모두 mysql/mariadb에서만 유효하며, 모든 CSP가 지원하는 것은 아니라는 안내 문구가 함께 표시됩니다. Charset만 입력하고 Collation을 비워두면 일부 CSP(Azure 등)에서는 위에서 설정한 User/Password가 추가로 필요할 수 있습니다 — 이미 Connect 시 입력했다면 별도 조치가 필요 없습니다.

---

CSP별 참고사항

Azure

• Azure MySQL Flexible Server의 Database 리소스는 Charset/Collation을 모두 지원하지만, Charset만 지정하고 Collation을 생략하면 Azure가 이를 조용히 무시하고 서버 기본 charset(보통 utf8mb4)으로 생성하는 현상이 실측 확인됐습니다.
• CB-Spider는 이를 감지해, Azure에 한해 Charset만 들어오면 대상 인스턴스에 실제 SQL 조회(information_schema.CHARACTER_SETS)를 수행해 그 charset의 진짜 기본 collation을 알아낸 뒤 두 값을 함께 Azure API에 전달합니다. 이 조회 때문에 Azure에서 Charset만 지정해도 MasterUserName/MasterUserPassword가 필요합니다.
• Charset과 Collation을 모두 직접 지정하면 이 조회 자체가 생략됩니다.

Tencent

• Tencent CDB의 CreateDatabase API는 CharacterSetName 필드만 있고 Collation 필드가 아예 없습니다.
• Collation을 지정하면 CB-Spider가 Database 생성 직후 ALTER DATABASE ... COLLATE ...를 SQL로 추가 실행합니다. 이 ALTER가 실패하면 방금 생성한 Database를 자동으로 롤백(삭제)합니다 — 잘못된 Collation 상태로 Database가 남지 않도록 하기 위함입니다.

NCP

• NCP Cloud DB for MySQL은 네이티브 API에 Charset/Collation 필드가 없고, 보안 정책상 마스터 계정에 일반 CREATE DATABASE SQL 권한도 부여되지 않습니다.
• 대신 NCP가 공식 제공하는 저장 프로시저 CALL sys.ncp_create_db('dbname', 'charset', 'collation')를 CB-Spider가 SQL로 직접 호출합니다 — Charset/Collation 중 하나라도 지정하면 이 경로를 사용합니다.
• 이 SQL 호출이 동작하려면 CB-Spider 서버가 인스턴스에 직접 TCP로 접속 가능해야 합니다(아래 Private Mode에서의 제약 참고). NCP는 Public Domain 할당 API가 없어 PublicAccess=true 생성 요청 자체가 거부되므로, CB-Spider 서버가 같은 VPC 등으로 라우팅 가능하지 않다면 NCPAutoOpenACG=true로 생성해 ACG를 연 뒤 NCP 콘솔에서 Public Domain을 수동 설정해야 합니다 — 세부 내용은 RDBMS Management Guide를 참고하세요.

NHN

• NHN Cloud RDS는 기본적으로 마스터 계정의 SQL CREATE DATABASE 권한을 차단합니다. Charset/Collation을 지정하려면 콘솔에서 "DB 스키마 & 사용자 직접 제어"(Direct Control)를 미리 활성화해야 합니다.
  • 설정 경로: NHN 콘솔 로그인 → Database → RDS for MySQL(또는 MariaDB) → DB 인스턴스 목록을 "그룹" 화면으로 전환 → 대상 그룹 선택 → 기본 정보 탭 → 수정 → "DB 스키마 & 사용자 직접 제어" 활성화
  • ⚠️ 활성화 즉시 현재 생성된 모든 사용자에게 CREATE, DROP, ALTER, CREATE USER 등 광범위한 권한이 *.*에 부여됩니다. 또한 비가역적입니다 — 다시 비활성화해도 이미 부여된 권한은 자동 회수되지 않습니다. 운영 환경에서는 신중히 적용하세요.
  • 비활성화 상태에서 Charset/Collation을 지정하면 CB-Spider의 "미지원" 메시지가 아니라 MySQL/MariaDB 엔진 자체의 권한 거부 에러(Error 1044: Access denied ...)가 그대로 노출됩니다.
  • MySQL용 인스턴스와 MariaDB용 인스턴스는 별도의 DB 인스턴스 그룹이므로, 각각 따로 Direct Control을 활성화해야 합니다.

Alibaba

• Alibaba RDS의 CreateDatabase API는 CharacterSetName을 MySQL/MariaDB 모두에서 지원하지만, CollationName은 공식 문서에 **"MySQL instances only"**로 명시되어 있습니다.
• 실측 결과, MariaDB 인스턴스에 Collation을 지정해도 에러 없이 조용히 무시되고 기본 Collation(utf8mb4_general_ci)으로 생성되는 것이 확인됐습니다.
• CB-Spider는 이를 조용히 넘어가는 대신, Alibaba MariaDB 인스턴스에 Collation을 지정하면 생성 요청 자체를 명확한 에러로 거부합니다. Alibaba MariaDB에서는 Charset만 지정하세요.
• Alibaba MySQL 인스턴스에서는 Charset/Collation 모두 정상 지원됩니다.

GCP, OpenStack

• 둘 다 Charset/Collation을 네이티브 API가 그대로 지원하며, Charset만 지정해도 올바른 기본 Collation이 적용됩니다(Azure와 달리 별도 보정 로직 불필요).
• OpenStack Trove의 Database/User API는 공식적으로 mysql datastore에 대해서만 지원이 명시되어 있습니다 — mariadb datastore에서의 동작은 배포본에 따라 다를 수 있으며, CB-Spider의 실측 테스트(이 wiki의 RDBMS Management Guide)는 테스트 당시의 특정 배포본 기준 결과입니다.

전체 9개 CSP(MySQL)/4개 CSP(MariaDB)에 대한 실측 검증 결과와 근거는 charset-test README, collation-test README의 Test Results 섹션을 참고하세요.

---

Security Notes

• MasterUserName/MasterUserPassword는 URL 쿼리 파라미터가 아니라 요청 Body로 전달됩니다 (List 조회는 X-Master-User-Name/X-Master-User-Password 헤더 사용 — RDBMS Management Guide 8번 절차 참고). 이 API는 CB-Spider 서버와의 신뢰된 네트워크 경로에서만 호출하세요.
• NHN의 "Direct Control" 활성화는 비가역적으로 광범위한 권한을 모든 기존 사용자에게 부여합니다 — 운영 환경 인스턴스에 적용하기 전에 반드시 보안 영향을 검토하세요.
• Tencent/NCP/NHN 경로는 CB-Spider가 대상 인스턴스에 직접 SQL로 접속해 DDL(CREATE DATABASE, ALTER DATABASE, 저장 프로시저 호출)을 실행합니다 — MasterUserName/MasterUserPassword가 유출되면 이 권한이 그대로 악용될 수 있으니 일반 애플리케이션 접속 계정과 동일한 수준으로 보호하세요.

---