Online Schema & Shard Changes User Guide

Online Schema & Shard Changes User Guide

Overview

Modify sharding keys, add shards, or change distribution strategies without downtime using zero-copy shard splits and online schema changes.

Benefits

• Zero downtime
• No application changes
• Automatic data migration
• Rollback support

Prerequisites

• HeliosDB v3.2+ cluster
• Sufficient capacity for temp data
• Metadata service online

Configuration

online_changes:
  enabled: true
  max_migration_bandwidth_mbps: 200
  validation_mode: strict
  rollback_on_error: true

SQL Examples

Change Shard Key

-- Change shard key online
ALTER TABLE orders
    RESHARD BY user_id;  -- Was order_id

-- Progress monitoring
SELECT
    phase,  -- preparing, migrating, validating, finalizing
    progress_percent,
    estimated_completion
FROM heliosdb.online_change_status
WHERE table_name = 'orders';

Add Shard

-- Add shard to existing sharded table
ALTER TABLE large_table
    ADD SHARD ON 'node-4';

-- Automatic rebalancing

Split Shard

-- Zero-copy split
SELECT heliosdb.split_shard(
    'large_table',
    shard_id => 1,
    split_keys => ARRAY[1000000]
);

Migration Phases

1. Preparing: Create shadow structures
2. Migrating: Copy data (online, non-blocking)
3. Validating: Verify integrity
4. Finalizing: Atomic switch

Best Practices

1. Test on staging first
2. Schedule during low traffic
3. Monitor progress closely
4. Have rollback plan
5. Validate after completion

For more: /docs/operations/online-changes.md