읽기 복제본 색인 만들기 및 관리

MySQL   |  PostgreSQL   |  SQL Server

이 문서에서는 Cloud SQL 읽기 복제본에서 보조 색인을 만들고 유지보수하고 모니터링하는 방법을 설명합니다.

관리형 복제본 색인의 작동 방식에 대한 개념 정보는 읽기 복제본 색인 개요를 참조하세요.

관리형 복제본 색인

다음 표에는 관리형 복제본 색인을 만들고 구성하고 모니터링하는 워크플로가 요약되어 있습니다.

단계	저장 프로시저 또는 데이터베이스 플래그	단계를 수행할 위치
색인 정의 만들기	CALL mysql.cloudsql_replica_idx_defn_create('INDEX_DEFINITION_NAME', 'CREATE_INDEX_STATEMENT'); 이 저장 프로시져는 색인 정의 INDEX_DEFINITION_ID의 고유한 정수 식별자를 반환합니다.	기본 인스턴스
그룹에 정의 매핑	CALL mysql.cloudsql_replica_idx_group_add(INDEX_DEFINITION_ID, 'GROUP_NAME'); GROUP_NAME은 선택할 수 있는 커스텀 이름입니다. 해당 그룹이 없으면 Cloud SQL에서 새 그룹을 만듭니다.	기본 인스턴스
복제본에 그룹 할당	데이터베이스 플래그: cloudsql_index_recreate_replica_group = GROUP_NAME	읽기 복제본 인스턴스
상태 확인	CALL mysql.cloudsql_replica_idx_show_status();	읽기 복제본 인스턴스
감사 오류	CALL mysql.cloudsql_replica_idx_show_errors();	읽기 복제본 인스턴스

각 저장 프로시져 호출은 현재 세션의 변경사항을 완료하는 COMMIT 문을 실행합니다. 따라서 이러한 저장 프로시져를 사용하여 실행되는 데이터 조작 언어 (DML) 문은 트랜잭션 내에서 롤백할 수 없습니다.

Cloud SQL은 기존 색인 메타데이터 업데이트 또는 변경을 지원하지 않습니다. 관리형 복제본 색인을 수정하려면 기존 색인 정의를 삭제 (또는 복제본 그룹에서 삭제)하고 새 색인 정의를 만들어야 합니다. 자세한 내용은 관리형 복제본 색인 수정을 참조하세요.

필수 역할 및 권한

관리형 복제본 색인의 저장 프로시져를 실행하려면 cloudsqlsuperuser 역할이 할당된 데이터베이스 사용자 계정을 사용해야 합니다.

관리형 복제본 색인 만들기

읽기 복제본에서 관리형 복제본 색인을 만들고 유지보수하려면 다음 단계를 따르세요.

1. 기본 인스턴스에서 색인 정의를 만듭니다.

   데이터베이스 기본 인스턴스에서 mysql.cloudsql_replica_idx_defn_create 저장 프로시져를 호출합니다.

   CALL mysql.cloudsql_replica_idx_defn_create
   ('INDEX_DEFINITION_NAME', 'CREATE_INDEX_STATEMENT');

   다음을 바꿉니다.

   • INDEX_DEFINITION_NAME: 색인 정의의 이름입니다.
   • CREATE_INDEX_STATEMENT: 보조 색인을 만드는 SQL 문입니다 (예: CREATE INDEX idx_age ON university.students (age)). 이 문에는 스키마 프리픽스가 있어야 합니다.

   프로시저 출력에서 반환된 idx_id (정의의 고유 정수 식별자)를 기록해 둡니다. Cloud SQL은 이 데이터를 mysql.cloudsql_replica_idx_defn에 저장하며, 나중에 이 테이블을 쿼리하여 idx_id를 검색할 수 있습니다.

2. 복제본 그룹에 색인 정의를 추가합니다.

   기본 인스턴스에서 mysql.cloudsql_replica_idx_group_add를 호출하여 색인 정의를 지정된 복제본 그룹 이름에 매핑합니다.

   CALL mysql.cloudsql_replica_idx_group_add
   (INDEX_DEFINITION_ID, 'GROUP_NAME');

   다음을 바꿉니다.

   • INDEX_DEFINITION_ID: mysql.cloudsql_replica_idx_defn_create 저장 프로시져를 실행하여 보조 색인을 만들 때 반환되는 고유한 정수 ID입니다.
   • GROUP_NAME: 복제본 그룹 매핑의 이름입니다 (예: reporting_group). GROUP_NAME은 선택할 수 있는 커스텀 이름입니다. 그룹이 없으면 Cloud SQL에서 새 그룹을 만듭니다.

   Cloud SQL은 이 데이터를 mysql.cloudsql_replica_idx_group_map에 저장하며, 나중에 이 테이블을 쿼리하여 그룹 매핑을 검색할 수 있습니다.

   참고: 동일한 색인 정의를 여러 복제본 그룹에 추가할 수 있습니다.

3. 복제본 인스턴스에 그룹을 할당합니다.

   데이터베이스 플래그 cloudsql_index_recreate_replica_group를 그룹 이름 (예: reporting_group)으로 설정하여 읽기 복제본에서 지정된 그룹을 사용 설정합니다.

4. 복원 진행 상황을 확인합니다.

   읽기 복제본 인스턴스에 연결하고 색인의 생성 진행 상황과 상태를 확인합니다.

   • 진행 중인 색인 생성 진행 상황을 확인합니다.

     CALL mysql.cloudsql_replica_idx_show_status();
     

   • 실패한 시도 및 오류 메시지를 확인합니다.

     CALL mysql.cloudsql_replica_idx_show_errors();
     

   • 모든 관리형 색인의 상태, 재시도 세부정보, 기간을 나열합니다.

     CALL mysql.cloudsql_replica_idx_show_all();
     

관리형 복제본 색인 상태 확인

색인 작업 상태를 확인하려면 읽기 복제본 인스턴스에 연결하고 mysql.cloudsql_replica_idx_status 테이블을 쿼리합니다.

SELECT * FROM mysql.cloudsql_replica_idx_status;

출력은 다음과 비슷합니다.

+--------+----------------------------------------------------+--------+-----------+---------------------+---------------------+-------------+---------+--------------------+---------+
| idx_id | create_stmt                                        | action | thread_id | start_time          | end_time            | retry_count | err_msg | comment_tag        | status  |
+--------+----------------------------------------------------+--------+-----------+---------------------+---------------------+-------------+---------+--------------------+---------+
|      2 | CREATE INDEX t1_fname ON sampletest.t1(first_name) | CREATE |      8140 | 2026-08-26 10:52:13 | NULL                |           0 | NULL    | [SIC_4_1787741231] | RUNNING |
|      4 | CREATE INDEX t2_lname ON sampletest.t2(last_name)  | DROP   |      NULL | 2026-08-26 10:52:13 | 2026-08-26 10:53:15 |           0 | NULL    | [SIC_4_1787741533] | DONE    |
|      5 | CREATE INDEX t1_lname ON sampletest.t1(last_name)  | CREATE |      8142 | 2026-08-26 10:53:14 | NULL                |           0 | NULL    | [SIC_5_1787741594] | RUNNING |
+--------+----------------------------------------------------+--------+-----------+---------------------+---------------------+-------------+---------+--------------------+---------+

Cloud SQL은 관리형 복제본 색인 유지보수를 일괄적으로 수행합니다. Cloud SQL이 CREATE 또는 DROP 작업 그룹을 선택하면 각 색인에 대해 PENDING 상태 항목을 만든 다음 각 데이터 정의 언어 (DDL) 문을 순차적으로 실행합니다. 한 색인에서 실패해도 큐에 있는 후속 색인의 실행이 차단되지 않습니다. 그러면 Cloud SQL은 약 5분 후에 다음 배치를 선택합니다.

색인 생성이 실패하면 Cloud SQL은 상태를 FAILED로 표시하고 1시간 후에 작업을 자동으로 다시 시도합니다.

mysql.cloudsql_replica_idx_status 테이블에는 모든 색인 작업 상태 항목이 포함되며 다음 열이 포함됩니다.

• idx_id: 색인 정의의 고유 정수 식별자입니다.
• create_stmt: CREATE INDEX SQL 문입니다.
• action: 수행 중인 작업 (CREATE 또는 DROP)
• thread_id: 작업을 실행하는 MySQL 스레드 ID입니다.
• 작업이 시작된 시점의 타임스탬프입니다.start_time
• end_time: 작업이 완료된 시점의 타임스탬프입니다.
• retry_count: 작업의 재시도 횟수입니다. Cloud SQL은 1시간 후에 실패한 색인 생성을 다시 시도합니다.
• err_msg: 마지막으로 실패한 작업의 오류 메시지입니다.
• comment_tag: 색인 주석 앞에 추가된 [SIC_X_Y] 태그입니다. 이 태그는 내부 관리용으로만 사용되며 기능이 없습니다.
• status: 작업의 현재 상태입니다.
  • PENDING: 색인 작업이 큐에 추가되었습니다.
  • RUNNING: 색인 작업 실행이 시작되었습니다.
  • DONE: 색인 작업이 성공적으로 완료되었습니다.
  • FAILED: 색인 작업이 실패했습니다. Cloud SQL은 1시간 후에 실패한 색인 생성을 다시 시도합니다.

관리형 복제본 색인 삭제

복제본 그룹에서 색인을 삭제하거나 색인 정의를 완전히 삭제하려면 기본 인스턴스에서 해당 저장 프로시져를 호출합니다.

• 복제본 그룹에서 색인 정의를 삭제합니다.

  기본 인스턴스에서 mysql.cloudsql_replica_idx_group_drop를 호출합니다.

  CALL mysql.cloudsql_replica_idx_group_drop
  (INDEX_DEFINITION_ID, 'GROUP_NAME');

  다음을 바꿉니다.

  • INDEX_DEFINITION_ID: 보조 색인 정의를 만들 때 반환된 고유 정수 ID입니다.
  • GROUP_NAME: 복제본 그룹 매핑의 이름입니다(예: reporting_group).

• 색인 정의 삭제:

  기본 인스턴스에서 mysql.cloudsql_replica_idx_defn_drop를 호출합니다.

  CALL mysql.cloudsql_replica_idx_defn_drop
  (INDEX_DEFINITION_ID);

  다음을 바꿉니다.

  • INDEX_DEFINITION_ID: 삭제할 색인 정의의 고유 정수 ID입니다.
  참고: 색인 정의가 복제본 그룹의 일부인 경우 삭제할 수 없습니다. 색인을 삭제하기 전에 mysql.cloudsql_replica_idx_group_drop를 사용하여 모든 복제본 그룹에서 색인 정의를 삭제합니다.

저장 프로시져에 대한 자세한 내용은 관리형 복제본 색인 저장 프로시져를 참조하세요.

관리형 복제본 색인 수정

Cloud SQL은 기존 색인 메타데이터 업데이트 또는 변경을 지원하지 않습니다. 기존 색인 정의 또는 SQL 문을 직접 수정할 수 없습니다.

관리형 복제본 색인을 수정하려면 (예: 색인이 생성된 열 또는 색인 옵션 변경) 기존 색인 정의를 삭제한 후 새 색인 정의를 만들어야 합니다.

관리형 복제본 색인을 수정하려면 다음 단계를 따르세요.

1. 기본 인스턴스에서 기존 색인 정의를 삭제합니다.

   • 복제본 그룹에서 색인 정의를 삭제하려면 mysql.cloudsql_replica_idx_group_drop를 호출합니다.

     CALL mysql.cloudsql_replica_idx_group_drop
     (INDEX_DEFINITION_ID, 'GROUP_NAME');

   • 색인 정의를 완전히 삭제하려면 mysql.cloudsql_replica_idx_defn_drop를 호출합니다.

     CALL mysql.cloudsql_replica_idx_defn_drop
     (INDEX_DEFINITION_ID);

   다음을 바꿉니다.

   • INDEX_DEFINITION_ID: 삭제할 색인 정의의 고유 정수 ID입니다.
   • GROUP_NAME: 복제본 그룹 매핑의 이름입니다(예: reporting_group).

2. 기본 인스턴스에서 새 색인 정의를 만듭니다.

   업데이트된 색인 문으로 mysql.cloudsql_replica_idx_defn_create를 호출합니다.

   CALL mysql.cloudsql_replica_idx_defn_create
   ('INDEX_DEFINITION_NAME', 'CREATE_INDEX_STATEMENT');

   다음을 바꿉니다.

   • INDEX_DEFINITION_NAME: 새 색인 정의의 이름입니다.
   • CREATE_INDEX_STATEMENT: 보조 색인을 만드는 업데이트된 SQL 문입니다 (예: CREATE INDEX idx_age ON university.students (age, name)).

   저장 프러시저 출력에 반환된 새 idx_id을 기록해 둡니다.

3. 새 색인 정의를 복제본 그룹에 매핑합니다.

   기본 인스턴스에서 mysql.cloudsql_replica_idx_group_add를 호출합니다.

   CALL mysql.cloudsql_replica_idx_group_add
   (INDEX_DEFINITION_ID, 'GROUP_NAME');

   다음을 바꿉니다.

   • INDEX_DEFINITION_ID: 2단계에서 반환된 새로운 고유 정수 ID입니다.
   • GROUP_NAME: 복제본 그룹 매핑의 이름입니다(예: reporting_group).

새 색인 정의를 복제본 그룹에 매핑하면 백그라운드 유지보수 프로세스가 읽기 복제본에서 기존 색인을 삭제한 다음 업데이트된 정의를 사용하여 복제본에 새 색인을 만듭니다.

관리형 복제본 색인의 데이터베이스 구성 플래그

다음 전역 데이터베이스 플래그를 사용하여 관리형 복제본 색인 동작을 동적으로 맞춤설정할 수 있습니다.

• cloudsql_index_recreate_enable: 다시 만들기 프로세스를 사용 설정 또는 중지합니다. 기본적으로 플래그는 on으로 설정됩니다. 플래그를 off로 설정하면 진행 중인 색인 유지보수 작업이 즉시 종료됩니다.

  주의: 색인이 활발하게 생성되는 동안 이 플래그를 사용 중지하면 작업이 즉시 종료됩니다. 대규모 테이블에서 진행 중인 색인 생성을 롤백하면 성능 문제가 발생하고 전반적인 데이터베이스 응답성이 저하될 수 있습니다.

• cloudsql_index_recreate_replica_group: 복제본의 지정된 복제본 그룹 이름입니다 (기본값은 NULL). 복제본은 한 번에 하나의 복제본 그룹에만 할당할 수 있습니다. 복제본은 이 복제본 그룹 이름에 매핑된 모든 색인을 빌드합니다.

자체 관리형 복제본 색인

Cloud SQL은 MySQL 읽기 복제본에 보조 색인을 추가하고 삭제하는 데 사용할 수 있는 두 가지 저장 프로시져를 mysql 스키마에 포함합니다. 이러한 저장 프로시져는 기본 소스 인스턴스에서 실행될 수 있지만 읽기 복제본용으로 설계되었습니다.

복제본이 다시 생성되면 이러한 색인은 유지되지 않습니다.

mysql.addSecondaryIdxOnReplica

데이터베이스에 보조 색인을 추가합니다. 이 저장 프로시져는 CREATE INDEX DDL 문의 래퍼입니다.

파라미터:

• idxType: 만들 색인의 유형입니다. 예를 들어 UNIQUE를 전달하여 고유 색인을 만듭니다.
• idxName: 색인 이름입니다.
• tableName: schema.name 형식의 테이블 이름입니다.
• idxDefinition: 색인 정의입니다. 외부 괄호는 포함하지 않습니다.
• idxOption: 색인 생성 시 전달할 추가 옵션입니다. 예를 들어 MySQL 8.0에서는 보이지 않는 색인에 INVISIBLE 옵션을 전달할 수 있습니다.

구문:

mysql.addSecondaryIdxOnReplica(idxType, idxName, tableName, idxDefinition, idxOption)
     

mysql.dropSecondaryIdxOnReplica

데이터베이스에 보조 색인을 삭제합니다. 이 저장 프로시져는 DROP INDEX DDL 문의 래퍼입니다.

파라미터:

• idxName: 색인 이름입니다.
• tableName: schema.name 형식의 테이블 이름입니다.
• idxOption: 색인을 삭제할 때 전달할 추가 옵션입니다. 예를 들어 INPLACE과 같은 알고리즘 옵션입니다.

구문:

mysql.dropSecondaryIdxOnReplica(idxName, tableName, idxOption)
      

idxType 및 idxOption 매개변수는 Cloud SQL 인스턴스에서 실행되는 MySQL의 주 버전에 대한 문서를 참조하세요.

예시

이 섹션에서는 자체 관리형 복제본 색인을 올바르게 또는 잘못 추가하거나 삭제하는 방법의 예시를 제공합니다.

올바른 사용

다음은 프로시져 호출의 예시입니다. 다음 정의가 있는 테이블이 있다고 가정해 보겠습니다.

CREATE TABLE sampletest.t1(
   id int(10) unsigned NOT NULL AUTO_INCREMENT,
   first_name varchar(64) NOT NULL,
   last_name varchar(64) NOT NULL,
   license_id int NOT NULL,
   PRIMARY KEY (id),
   KEY idx_fname (first_name)
) ENGINE=InnoDB DEFAULT CHARSET=utf8

first_name 및 last_name 열에 t1_fname_lname이라는 일반 색인을 만들려면 다음 문을 실행합니다.

CALL mysql.addSecondaryIdxOnReplica('', 't1_fname_lname', 'sampletest.t1', 'first_name, last_name', '')

'고유 라이선스 ID'라는 주석이 있는 license_id 열에 t1_license_id라는 고유 색인을 만들려면 다음 문을 실행합니다.

CALL mysql.addSecondaryIdxOnReplica('unique', 't1_license_id', 'sampletest.t1', 'license_id', 'comment "unique license ID"')

t1_fname_lname 색인을 삭제하려면 다음 문을 실행합니다.

CALL mysql.dropSecondaryIdxOnReplica('t1_fname_lname', 'sampletest.t1', '')

잘못된 사용

first_name 및 last_name 열에 색인을 만들려는 다음 시도는 idxDefinition 매개변수의 외부 괄호로 인해 실패합니다.

CALL mysql.addSecondaryIdxOnReplica('', 't1_extra_parenthesis', 'sampletest.t1', '(first_name, last_name)', '')

고객이 만든 테이블에만 색인을 추가할 수 있습니다. mysql.servers 테이블의 host 열에 색인을 만들려는 다음 시도는 실패합니다.

CALL mysql.addSecondaryIdxOnReplica('', 'idx_invalid', 'mysql.servers', 'host', '')

dropSecondaryIdxOnReplica 프로시져만 사용하여 이전에 addSecondaryIdxOnReplica 프로시져를 사용하여 만든 색인을 삭제할 수 있습니다. 예를 들어 기존 idx_fname 색인을 삭제하는 다음 호출은 실패합니다.

CALL mysql.dropSecondaryIdxOnReplica('idx_fname', 'sampletest.t1', '')

이러한 프로시져 호출의 SQL 삽입은 실패합니다. 예를 들어 주석 시퀀스가 있는 다음 SQL 삽입은 실패합니다.

CALL mysql.addSecondaryIdxOnReplica("user 'a'@'%' --", 'idx_fname', 'sampletest.t1', 'first_name', '')

마찬가지로 구분 기호를 사용한 이 SQL 삽입 시도는 실패합니다.

CALL mysql.addSecondaryIdxOnReplica('', 'idx_fname', 'sampletest.t1', 'first_name', ';flush status')

자체 관리형에서 관리형 복제본 색인으로 마이그레이션

관리형 복제본 색인과 자체 관리형 복제본 색인이 모두 동일한 인스턴스에 공존할 수 있지만 관리형 복제본 색인으로 마이그레이션할 수 있습니다.

자체 관리형에서 관리형 복제본 색인으로 마이그레이션하려면 다음 단계를 따르세요.

1. 기본 인스턴스에 색인 정의를 등록합니다.

   각 보조 색인의 기본 인스턴스에서 mysql.cloudsql_replica_idx_defn_create를 호출합니다.

   CALL mysql.cloudsql_replica_idx_defn_create
   ('INDEX_DEFINITION_NAME',
   'CREATE INDEX INDEX_NAME ON DATABASE.TABLE (COLUMNS)');

   프로시저 출력에서 반환된 idx_id (정의의 고유 정수 식별자)를 기록해 둡니다.

2. 복제본 그룹에 색인 정의를 추가합니다.

   기본 인스턴스에서 mysql.cloudsql_replica_idx_group_add를 호출하여 색인 정의를 지정된 복제본 그룹 이름에 매핑합니다.

   CALL mysql.cloudsql_replica_idx_group_add
   (INDEX_DEFINITION_ID, 'REPLICA_GROUP');

3. 읽기 복제본에서 복제본 그룹 플래그를 구성합니다.

   읽기 복제본 인스턴스에서 cloudsql_index_recreate_replica_group 데이터베이스 플래그를 그룹 이름을 타겟팅하도록 설정합니다.

   gcloud sql instances patch REPLICA_INSTANCE_NAME \
   --database-flags=EXISTING_FLAGS,cloudsql_index_recreate_replica_group=REPLICA_GROUP

   cloudsql_index_recreate_replica_group 데이터베이스 플래그에 제공된 그룹 이름이 mysql.cloudsql_replica_idx_group_add에 지정된 그룹 이름과 정확히 일치하는지 확인합니다.

4. 기존 색인을 확인하거나 전환합니다.

   읽기 복제본에 색인이 이미 있으므로 백그라운드 프로세스에서 색인을 만들려고 하면 mysql.cloudsql_replica_idx_status에 FAILED 상태의 오류가 표시될 수 있습니다. 다음 방법 중 하나를 선택할 수 있습니다.

   • 복제본 다시 만들기 대기: 상태 테이블에서 FAILED 상태를 무시해도 됩니다. Cloud SQL은 복제본 다시 만들기 이벤트 후 관리형 복제본 색인 메서드를 사용하여 보조 색인을 자동으로 다시 만듭니다.

   • 즉시 전환: Cloud SQL에서 복제본 재생성을 기다리지 않고 즉시 색인을 관리하도록 하려면 읽기 복제본에 연결하고 mysql.dropSecondaryIdxOnReplica 저장 프로시저를 사용하여 자체 관리형 색인을 삭제합니다.

     CALL mysql.dropSecondaryIdxOnReplica('INDEX_NAME', 'DATABASE.TABLE', '');

     다음 백그라운드 유지보수 주기 (약 5분마다) 동안 Cloud SQL은 관리형 복제본 색인을 자동으로 다시 만들고 추적합니다.

     주의: 이 방법을 사용하면 자체 관리형 색인을 삭제하고 관리형 복제본 색인을 만드는 간격 동안 읽기 쿼리 성능이 저하될 수 있습니다.

복제본 색인 문제 해결

복제본 색인 문제를 해결하려면 다음을 확인하세요.

• 복제본 인스턴스에 관리형 복제본 색인이 사용 설정되어 있는지 확인합니다.

  관리형 복제본 색인을 사용하는 경우 읽기 복제본에서 cloudsql_index_recreate_enable 데이터베이스 플래그가 on로 설정되어 있는지 확인합니다.

  데이터베이스 플래그 구성에 대한 자세한 내용은 데이터베이스 플래그 구성을 참조하세요.

• 작업 상태 및 오류 확인:

  읽기 복제본에 연결하고 mysql.cloudsql_replica_idx_status를 쿼리하거나 CALL mysql.cloudsql_replica_idx_show_errors();를 실행하여 실패한 작업의 오류 메시지를 확인합니다. 한 색인에서 오류가 발생해도 큐에 있는 후속 색인의 실행이 차단되지 않습니다.

다음 단계

• 읽기 복제본 색인에 대해 자세히 알아보세요.
• 읽기 복제본 관리 방법 알아보기
• 읽기 복제본을 만드는 방법 알아보기
• Cloud SQL의 복제 알아보기
• 복제 지연 알아보기
• 데이터베이스 플래그 구성 방법 알아보기
• MySQL용 Cloud SQL의 저장 프로시져 알아보기
• 고급 재해 복구 (DR) 알아보기
• MySQL 클라이언트를 사용하여 연결하는 방법 알아보기