Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Published by Scroll Versions from space ML1 and version 5.3


Sv translation

Xpand performs online schema changes without blocking reads or writes to a table. 


Xpand uses MVCC (multi-version concurrency control) to avoid locking to tables undergoing a schema change. New temporary container(s) are created, and while data is being copied, a temporary transaction log records any writes run against the old containers. Once all the original records have been copied and logged transactions have been processed, the ALTER transaction completes, the new table is available, and the old table is discarded. All of these mechanics are performed automatically when you execute your ALTER SQL. 


Xpand maintains read consistency during the ALTER – read and write queries that run against the table before the ALTER commits see the original table schema. Reads and writes after the ALTER commits see the new schema. From the perspective of any single query or user, the ALTER is instantaneous.

Table of Contents

Best Practices



Xpand is designed to easily support online schema changes for tables of any size, the following best practices help to minimize negative and unforeseen impacts to your application. This includes: 

  1. Since an ALTER on a large table can take a while to complete, we suggest using screen or some other detachable terminal.

  2. Test the new schema with your application's queries in a non-production environment. Compare the output of the EXPLAIN plan before and after the change.

  3. Perform schema change(s) during off-peak hours or during a maintenance window.

  4. Ensure there is adequate disk space (see below).

  5. Understand impacts to replication and revise plan accordingly.

Estimating Disk Space Requirements

Online schema changes pins BigC, which means that undo log is not cleaned up until the ALTER completes. This means that for the ALTER to complete, there must be sufficient space. To calculate how much free space is required for an ALTER you should review the following:

  • The current amount of space used.
  • The minimum amount of free space desired. 
    • Plan to reserve a minimum of at least 10% free space throughout your schema changes.


    • Xpand will kill long-running transactions (including the ALTER) if free space falls under 5%.
  • Ensure there is sufficient space to store a full copy of the table, including replicas. The size of a table can be estimated from system.table_sizes.
  • The estimated amount of time it will take to complete the ALTER
  • New data growth rate.
  • Undo log size. The undo log for all INSERT, UPDATE, and DELETE operations will accumulate during the ALTER.
  • Binlog size and growth rate. During the ALTER, binlog trims will still run, but the disk space will not be freed until BigC is unpinned.

When you add up all the planned growth and size of the table copy plus the current space consumed, you should still have at least 10% of disk remaining. If not, trimming binlogs, pruning tables, or expanding the cluster with additional servers is recommended before initiating the ALTER.

Example: Disk Space required for an ALTER

In the following example, a column will be added to a 1TB table that is part of a 10TB cluster. 

Description of Space RequirementTB Required

Our cluster is currently 10 TB of usable space and we know the system reserves 5% for internal operations. If we exceed this, writes can be blocked and the ALTER will roll-back.

0.5 TB
Our users have requested we leave at least 10% of space free at all times to handle surges in load.1.0 TB
The new table will consume a bit over 1 TB due to the additional column. We could calculate rows times bytes, but let's assume 1.1 TB. Because this is a copy, we have to reserve this space until the ALTER is complete.1.1 TB

The entire cluster receives approximately ~1.5 TB per day of write transactions (including writes to the binlogs) so (1.5 / 24) * 25 hours = 1.5625 TB

1.6 TB
Total free space required to safely begin the ALTER:4.2 TB

A conservative estimate would be that there should be at least 4.5 TB available space on the cluster to allow the ALTER to complete.

Monitoring the Progress of an ALTER

To view the status of an ALTER in-process, use this SQL.

sql> select * from system.alter_progress;

Replication Concerns

Performing ALTER operations in replicated environments requires additional planning. Whenever possible, it is recommended to allow the ALTER to run over the replication stream.

Running the ALTER over replication means that the ALTER must execute sequentially, first on the master, then on the slave. Furthermore, the slave must process the ALTER sequentially within the replication stream, and all other writes are paused while the slave processes through the ALTER. For large tables, ALTER operations can cause the slave to fall behind the master. Plan to adjust binlog retention on the master and monitor replication regularly to ensure the slave does not exceed your master's binlog retention during this process.

Column Matching

When replicating via row-based binlogs, column synchronization is critical. RBR (row-based replication) sends both the old and new rows to the slave and the old must match before the new is applied. ALTER operations that modify columns must be executed within replication and in sequence to avoid slave errors trying to applying writes for one schema to the other.

When replicating via statement-based (SBR) binlogs, more flexibility is allowed, provided that the statements execute equally well on the old and new schema. However, for environments with high concurrency, it is extremely difficult to assess whether all statements are equivalent on the old and new schemas. 

Exceptions to these column matching concerns include ALTER operations that add an index, change the storage type, or modify the number of slices. Since these do not affect the insertion or update of rows, they may be executed in parallel outside the replication stream.

Scale-Out Concerns for Online Schema Changes

The performance of ALTER on user data will vary depending on your particular environment and workload. Take the following as guidance and adapt based on your own experience and testing.

Modifying a Simple, Small Table

For tables around N*10^6 rows or with light concurrency, ALTER can be done live and should complete within minutes depending on the cluster size, row size, and overall load. Cache and query plan refreshes occur regularly and the automatic refresh should handle any performance issues.

Medium Scale-Out Issues with Online Schema Changes

Tables that are being accessed with high concurrency or have more than N*10^7 rows may experience degraded cluster performance immediately after the ALTER completes.


Xpand stores statistics and query plans for each table, and these values are cached.


Xpand's periodic refresh and flush of that information may not occur quickly enough and may consequently impact performance. To avoid this, immediately flush the cache once the ALTER is complete by using the following commands:

sql> ALTER TABLE ...
shell> clx cmd 'mysql system -e "call pdcache_update()"'; 
shell> clx cmd 'mysql system -e "call qpc_flush()"'; 

Note that qpc_flush and pdcache_update are done on a per-node basis. Therefore, these should be executed using the clx cmd utility to ensure they are run on all nodes.

Chaining these commands together in the shell as command && command && command is recommended to avoid delays between the completion of the ALTER and flushing of the caches.

Sv translation

Clustrix는 테이블에 읽기 및 쓰기를 차단하지 않고 온라인으로 스키마를 변경하는 기능을 제공합니다. 스키마 변경은 단순히 인덱스 또는 열을 추가하거나 스키마를 완전히 다시 설계하는 것까지 포함합니다. 다른 데이터베이스 시스템에서는 스키마 변경 프로세스가 각 행을 처리하거나 데이터 구조를 변환하는 동안 부분 또는 전체 테이블 잠금을 필요로 합니다.

Clustrix 데이터베이스는 새로운 임시 컨테이너(또는 컨테이너 세트)를 만들고 변경된 새로운 구조(structure)로 데이터를 복사하여 잠금 문제를 해결합니다. 변경되는 테이블에 DML 작업이 있는 경우 임시 트랜잭션 로그에 기존 컨테이너에 대해서 수행된 쓰기 또는 업데이트 트랜잭션을 기록한 다음 그것들을 새로운 컨테이너에 적용합니다. 모든 레코드가 복사되고 로그에 기록된 트랜잭션이 처리되면 ALTER 트랜잭션이 커밋되고 새 테이블이 활성화되면서 기존 테이블은 삭제됩니다.

Clustrix은 ALTER 실행 중에 읽기 일관성을 유지합니다 - ALTER가 커밋되기 전에 테이블에 실행된 읽기 및 쓰기 쿼리는 원본 테이블 스키마를 참조합니다. ALTER가 커밋된 이후 읽기 및 쓰기는 새로운 스키마를 참조합니다. 단일 쿼리 또는 사용자 관점에서 ALTER는 즉시 실행됩니다.

Table of Contents


Clustrix 데이터베이스 엔진은 모든 크기의 테이블에 대한 온라인 스키마 변경도 쉽게 지원하도록 설계되었습니다. 다음 모범 사례는 응용 프로그램에 대한 예기치 않은 부정적인 영향을 최소화하는 데 도움이 됩니다. 여기에는 다음과 같은 내용이 포함되어 있습니다.

  1. 데이터를 백업하십시오.

  2. 격리된 환경에서 응용 프로그램의 쿼리를 사용하여 새로운 스키마를 테스트하십시오. 변경 전과 변경 후의 EXPLAIN <query> 플랜의 출력을 비교하여 쿼리 플랜에 부정적인 영향이 미치지 않았는지 확인하십시오.

  3. 서비스 부하가 낮은 시간대나 유지 보수 기간 동안 스키마 변경을 수행하십시오.

  4. 디스크 공간이 충분한지 확인하십시오 (아래 참조).

  5. 복제에 미치는 영향을 이해하고 그에 따라 작업 계획을 수정하십시오.

디스크 공간 요구 사항 예측

ALTER를 실행하기 전에 필요한 여유 디스크 공간을 파악하려면 먼저 BigC라고 하는 Clustrix 가비지 컬렉션 프로세스를 이해해야 합니다.

BigC는 본질적으로 트랜잭션이 완료되는 시간에 따라 지속적으로 이동하는 체크포인트입니다. 클러스터의 BigC 값(system.stats에 표시)은 현재 실행 중인 가장 오래된 트랜잭션이 시작된 시점을 항상 표시합니다. 모든 명시적 트랜잭션은 BigC를 고정시킵니다. 가비지 컬렉션이 고정되어 있는 동안 오래 실행 중인 트랜잭션이 실패하고 롤백 될 경우에 클러스터는 쓰기, 삭제, 업데이트 및 DDL 트랜잭션을 UNDO 로그에 기록합니다.

ALTER 명령은 DDL 트랜잭션이기 때문에 BigC를 고정합니다. 이는 ALTER가 실행되는 동안 모든 가비지 컬렉션이 중단되는 다는 것을 의미합니다.

ALTER에 필요한 디스크 공간을 계산하려면 다음 각 항목을 평가해야 합니다.

  • 현재 사용 중인 디스크 공간
  • 최소 여유 공간
    • 디스크 공간이 5% 이하로 떨어지면 ClustrixDB는 오래 실행되는 트랜잭션을 종료합니다. 그러면 ALTER가 롤백 됩니다.
    • 스키마 변경 시 최소 10%의 여유 공간을 확보하도록 계획합니다.
  • ALTER 되는 테이블의 크기
    • 테이블 복사본을 저장할 충분한 디스크 공간이 있는지 확인하십시오.
    • 테이블 크기는 system.table_sizes를 사용하여 계산할 수 있습니다.
  • ALTER를 완료하는 데 걸리는 예상 시간
    • 이것은 클러스터의 크기에 따라 달라집니다 (예를 들어, 서버가 많으면 더 빠름).
    • 이전의 더 작은 ALTER 작업 속도를 기반으로 추정할 수 있습니다.
  • 새로운 데이터 증가율
  • Undo 로그 증가율. 모든 INSERT, UPDATES, DELETES에 대한 Undo 로그는 ALTER가 수행되는 동안 누적됩니다.
  • 복제하는 경우 binlog 증가율
    • Binlog 트림은 여전히 실행되지만 BigC 고정이 해제될 때까지 디스크 공간은 해제되지 않습니다.

테이블 복사본의 계획된 증가 및 크기에 현재 사용 중인 공간을 합하여 적어도 10%의 디스크 공간이 남아있어야 합니다. 그렇지 않은 경우 ALTER를 시작하기 전에 binlog를 트림하거나, 테이블을 정리하거나 추가 서버로 클러스터를 확장하는 것이 좋습니다.

복제 문제

복제 환경에서 ALTER를 실행하려면 추가 계획이 필요합니다. 스키마 구조가 변경되는지 여부에 따라 ALTER는 복제와 함께 또는 독립적으로 수행될 수 있습니다. 가능하면 트랜잭션이 이전 스키마 또는 새 스키마를 찾는 복제 오류를 피하려면 복제 스트림을 통해 ALTER를 실행하는 것이 좋습니다.

복제를 통해 ALTER를 수행한다는 것은 ALTER가 먼저 마스터에서 실행되고 다음으로 슬레이브에서 순차적으로 실행되어야 한다는 것을 의미합니다. 또한, 슬레이브는 복제 스트림에서 ALTER를 순차적으로 처리하고 슬레이브가 ALTER를 처리하는 동안 다른 모든 쓰기는 일시 중지됩니다. 큰 테이블 ALTER의 경우 이로 인해 슬레이브가 마스터보다 뒤처질 수 있습니다. 이 처리 동안 슬레이브가 마스터의 binlog 보관 기간을 벗어나지 않도록 마스터에서 binlog 보관 기간에 대한 계획을 수립하고 복제를 정기적으로 모니터링하십시오.

열 매칭

행 기반 binlog를 통해 복제하는 경우 열 동기화가 중요합니다. RBR(행 기반 복제)는 이전 행과 새로운 행을 모두 슬레이브로 보내며 이전 행은 새로운 행이 적용되기 전에 일치해야 합니다. 하나의 스키마에 대한 쓰기를 다른 스키마에 적용하는 슬레이브 오류를 방지하기 위해서 열을 변경하는 ALTER는 복제 내에서 순차적으로 실행되어야 합니다.

문 기반(SBR) binlog를 통해 복제하는 경우 이전 스키마나 새 스키마에서 모두 문이 잘 실행된다면 더 많은 융통성이 허용됩니다. 그러나, 동시성이 높은 환경에서 모든 문이 이전 또는 새 스키마에서 동일한지 여부를 평가하는 것은 매우 어렵습니다.

이러한 열 일치 문제에 대한 예외로는 인덱스 추가, 스토리지 유형 변경 또는 슬라이스 수 변경에 대한 ALTER가 해당됩니다. 이것은 행의 추가 또는 업데이트에 영향을 주지 않기 때문에 복제 스트림 외부에서 병렬로 실행될 수 있습니다.

온라인 스키마 변경으로 인한 스케일 아웃 문제

사용자 데이터에서 ALTER 성능은 특정 환경 및 작업 부하에 따라 다릅니다. 다음을 지침으로 삼아 사용자 개인의 경험과 테스트에 따라 적용하십시오.

작고 간단한 테이블 변경

N*10^6개의 행이 있거나 동시성이 낮은 테이블의 경우 ALTER는 클러스터 크기, 행 크기 및 전체 부하에 따라 라이브로 수행될 수 있고 몇 분 안에 완료되어야 합니다. 캐시 및 쿼리 플랜 갱신(refresh)은 주기적으로 발생하며 자동 갱신은 모든 성능 문제를 처리할 것입니다.

온라인 스키마 변경으로 인한 중간 규모 스케일 아웃 문제

동시성이 높은 테이블 또는 N*10^7개 이상의 행이 있는 테이블은 ALTER가 완료된 직후에 클러스터의 성능이 저하 될 수 있습니다. Clustrix는 각 테이블에 대한 통계 및 쿼리 플랜을 저장하며 이 값은 캐시 됩니다. Clustrix는 성능에 영향을 주지 않도록 이러한 캐시를 빠르게 새로 고치거나 플러시 하지 않을 수 있습니다. 일단 ALTER가 완료되면 다음 명령을 사용하여 캐시를 플러시 하십시오.

Code Block
$ clx cmd 'mysql system -e "call qpc_flush()"'; 
$ clx cmd 'mysql system -e "call pdcache_update()"';

qpc_flush와 pdcache_update는 노드별로 수행됩니다. 그러므로, 모든 노드에서 실행되도록 하려면 clx cmd 유틸리티를 사용하여 수행되어야 합니다.

ALTER 완료와 캐시 플러시 사이의 지연을 피하려면 command && command && command처럼 셸에서 명령을 함께 묶는 것이 좋습니다.

온라인 스키마 변경 예

다음 예제에서는 열을 추가하기 위해 1TB 테이블을 ALTER 합니다. 필요한 시간을 예측하는 것은 과학보다 예술이며, ALTER를 실행하는 클러스터의 크기에 따라 달라집니다. 이 예에서 작은 테이블에 대한 이전 ALTER 경험을 바탕으로 1TB 테이블에 대해 ALTER가 완료되는 데 25시간까지 걸릴 것이라고 생각하게 되었습니다.

10TB 클러스터 여유 공간 계획을 생각해 보겠습니다.

공간 요구 사항에 대한 설명필요한 TB

클러스터에 현재 10TB 사용 가능한 공간이 있고 시스템은 내부 작업을 위해 5%를 예약합니다. 이를 초과하면 쓰기가 차단되고 ALTER는 롤백 됩니다.

0.5 TB
사용자는 부하의 급증에 대처하기 위해 적어도 10%의 상시 여유 공간을 요청했습니다.1.0 TB
새 테이블은 추가 열로 인해 1TB 조금 넘게 소모합니다. 행 곱하기 바이트(byte)로 계산할 수 있지만, 1.1TB로 가정합니다. 이것은 사본이기 때문에 ALTER가 완료될 때까지 이 공간을 예약해야 합니다.1.1 TB

전체 클러스터는 매일 약 1.5TB의 쓰기 트랜잭션을 (binlog 쓰기 포함) 받기 때문에 (1.5/24)*25 hours = 1.5625TB가 필요합니다.

1.6 TB
ALTER를 안전하게 수행하기 위해 필요한 총 디스크 공간4.2 TB

보수적으로 예측하면 ALTER를 완료하기 위해 클러스터에 적어도 4.5TB의 여유 공간이 있어야 합니다.


클러스터에 원격으로 연결하는 경우 세션이 끊어지면 다음의 장기 실행 트랜잭션은 실패하고 롤백 됩니다. screen 또는 기타 착탈식(detachable) 터미널을 사용하는 것이 좋습니다.

하나의 terminal 커넥션을 사용하여 Session A를 시작하고 BigC를 고정하기 위해 트랜잭션을 시작합니다.

Code Block

별도의 터미널에서 Session B를 시작하고 ALTER를 시작합니다. 다음의 세 가지 명령은 연속해서 수행해야 하기 때문에 다음과 같이 그것을 연결합니다.

Code Block
$ mysql -e "ALTER TABLE database.hugetable ADD COLUMN foo varchar(255)"; \
$ clx cmd 'mysql -e "call system.task_run(\'pdcache_update\')"'; \
$ clx cmd 'mysql -e "call system.qpc_flush()"'

몇 시간 후에 ALTER 및 캐시 플러시가 완료된 후, Session A가 보유한 트랜잭션을 릴리스할 수 있습니다. 가비지 컬렉션이 무거울 수 있기 때문에 피크 부하가 없어질 때까지 기다릴 수도 있지만, layer_merges를 낮게 설정해도 특별한 차이는 없습니다.

Session A 터미널에서,

Code Block