CLI Reference
Command: iceberg-migrate migrate
Rewrite Iceberg metadata paths and register the table in AWS Glue Catalog.
Required Flags
| Flag | Description | Example |
|---|---|---|
--table-location |
S3 URI of the Iceberg table root | s3://bucket/warehouse/db/table |
--source-prefix |
Original path prefix to replace | s3a://minio-bucket/warehouse |
--dest-prefix |
New S3 path prefix | s3://aws-bucket/warehouse |
Optional Flags
| Flag | Default | Description |
|---|---|---|
--dry-run |
false |
Show planned changes without writing |
--verbose |
false |
Print per-file path substitution counts |
--glue-database |
Derived from table location | Override Glue database name |
--glue-table |
Derived from table location | Override Glue table name |
--json |
false |
Emit JSON to stdout; human summary to stderr |
--aws-region |
AWS_DEFAULT_REGION or us-east-1 |
AWS region for Glue |
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Partial failure (some writes completed) |
| 2 | Fatal error (failed before writes) |
Examples
Basic migration:
iceberg-migrate migrate \
--table-location s3://my-bucket/warehouse/analytics/events \
--source-prefix s3a://minio-prod/warehouse \
--dest-prefix s3://my-bucket/warehouse
HDFS source (non-S3 source prefix):
iceberg-migrate migrate \
--table-location s3://my-bucket/warehouse/analytics/events \
--source-prefix hdfs://namenode:8020/warehouse \
--dest-prefix s3://my-bucket/warehouse
Dry run with verbose output:
iceberg-migrate migrate \
--table-location s3://my-bucket/warehouse/analytics/events \
--source-prefix s3a://old-bucket/warehouse \
--dest-prefix s3://my-bucket/warehouse \
--dry-run --verbose
JSON output for scripting:
iceberg-migrate migrate \
--table-location s3://my-bucket/warehouse/analytics/events \
--source-prefix s3a://old-bucket/warehouse \
--dest-prefix s3://my-bucket/warehouse \
--json 2>/dev/null | jq .status
Custom Glue names:
iceberg-migrate migrate \
--table-location s3://my-bucket/warehouse/analytics/events \
--source-prefix s3a://old-bucket/warehouse \
--dest-prefix s3://my-bucket/warehouse \
--glue-database my_analytics \
--glue-table user_events
Lakekeeper source (gzip-compressed metadata):
# Lakekeeper writes .gz.metadata.json — the tool handles decompression automatically
iceberg-migrate migrate \
--table-location s3://my-bucket/warehouse/analytics/events \
--source-prefix s3a://lakekeeper-minio/warehouse \
--dest-prefix s3://my-bucket/warehouse
Source: docs/CLI.md on GitHub ↗