config.go

package ghostferry

import (
	"crypto/tls"
	"crypto/x509"
	"errors"
	"fmt"
	"io/ioutil"
	"strings"
	"time"

	sql "github.com/Shopify/ghostferry/sqlwrapper"

	"github.com/go-sql-driver/mysql"
)

const (
	VerifierTypeChecksumTable  = "ChecksumTable"
	VerifierTypeIterative      = "Iterative"
	VerifierTypeInline         = "Inline"
	VerifierTypeNoVerification = "NoVerification"

	DefaultNet          = "tcp"
	DefaultMarginalia   = "application:ghostferry"
	MySQLNumParamsLimit = 1<<16 - 1 // see num_params https://dev.mysql.com/doc/internals/en/com-stmt-prepare-response.html
)

type TLSConfig struct {
	CertPath   string
	ServerName string

	tlsConfig *tls.Config
}

func (this *TLSConfig) BuildConfig() (*tls.Config, error) {
	if this.tlsConfig == nil {
		certPool := x509.NewCertPool()
		pem, err := ioutil.ReadFile(this.CertPath)
		if err != nil {
			return nil, err
		}

		if ok := certPool.AppendCertsFromPEM(pem); !ok {
			return nil, errors.New("unable to append pem")
		}

		this.tlsConfig = &tls.Config{
			RootCAs:    certPool,
			ServerName: this.ServerName,
		}
	}

	return this.tlsConfig, nil
}

type DatabaseConfig struct {
	Host      string
	Port      uint16
	Net       string
	User      string
	Pass      string
	Collation string
	Params    map[string]string
	TLS       *TLSConfig

	// ReadTimeout is used to configure the MySQL client timeout for waiting for data from server.
	// Timeout is in seconds. Defaults to 0, which means no timeout.
	ReadTimeout uint64

	// WriteTimeout is used to configure the MySQL client timeout for writing data to server.
	// Timeout is in seconds. Defaults to 0, which means no timeout.
	WriteTimeout uint64

	// SQL annotations used to differentiate Ghostferry's DMLs
	// against other actor's. This will default to the defaultMarginalia
	// constant above if not set.
	//
	// This is used to ensure any changes to the Target during the move process
	// are performed only by Ghostferry (until cutover). Otherwise, the modification
	// will be identified as data corruption and fail the move.
	Marginalia string
}

func (c *DatabaseConfig) MySQLConfig() (*mysql.Config, error) {
	var addr string

	if c.Net == "unix" {
		addr = c.Host
	} else {
		addr = fmt.Sprintf("%s:%d", c.Host, c.Port)
	}

	cfg := &mysql.Config{
		User:                 c.User,
		Passwd:               c.Pass,
		Net:                  c.Net,
		Addr:                 addr,
		Collation:            c.Collation,
		Params:               c.Params,
		AllowNativePasswords: true,
		MultiStatements:      true,
	}

	if c.ReadTimeout != 0 {
		cfg.ReadTimeout = time.Duration(c.ReadTimeout) * time.Second
	}

	if c.WriteTimeout != 0 {
		cfg.WriteTimeout = time.Duration(c.WriteTimeout) * time.Second
	}

	if c.TLS != nil {
		tlsConfig, err := c.TLS.BuildConfig()
		if err != nil {
			return nil, fmt.Errorf("failed to build TLS config: %v", err)
		}

		cfgName := fmt.Sprintf("%s@%s:%d", c.User, c.Host, c.Port)

		err = mysql.RegisterTLSConfig(cfgName, tlsConfig)
		if err != nil {
			return nil, fmt.Errorf("failed to register TLS config: %v", err)
		}

		cfg.TLSConfig = cfgName
	}

	return cfg, nil
}

func (c *DatabaseConfig) Validate() error {
	if c.Host == "" {
		return fmt.Errorf("host is empty")
	}

	if c.Port == 0 {
		return fmt.Errorf("port is not specified")
	}

	if c.Net == "" {
		c.Net = DefaultNet
	} else if c.Net == "unix" {
		c.Port = 0
	} else if c.Net != "tcp" && c.Net != "unix" {
		return fmt.Errorf("net is unknown (valid modes: tcp, unix)")
	}

	if c.User == "" {
		return fmt.Errorf("user is empty")
	}

	err := c.assertParamSet("time_zone", "'+00:00'")
	if err != nil {
		return err
	}

	err = c.assertParamSet("sql_mode", "'STRICT_ALL_TABLES,NO_BACKSLASH_ESCAPES'")
	if err != nil {
		return err
	}

	if c.Marginalia == "" {
		c.Marginalia = DefaultMarginalia
	}

	return nil
}

func (c *DatabaseConfig) SqlDB(logger Logger) (*sql.DB, error) {
	dbCfg, err := c.MySQLConfig()
	if err != nil {
		return nil, fmt.Errorf("failed to build database config: %s", err)
	}

	if logger != nil {
		logger.WithField("dsn", MaskedDSN(dbCfg)).Info("connecting to database")
	}

	return sql.Open("mysql", dbCfg.FormatDSN(), c.Marginalia)
}

func (c *DatabaseConfig) assertParamSet(param, value string) error {
	if c.Params == nil {
		c.Params = make(map[string]string)
	}

	if c.Params[param] != "" && c.Params[param] != value {
		return fmt.Errorf("%s must be set to %s", param, value)
	}
	c.Params[param] = value

	return nil
}

type InlineVerifierConfig struct {
	// The maximum expected downtime during cutover, in the format of
	// time.ParseDuration. If nothing is specified (or it is zero), the
	// InlineVerifier does not enforce a downtime limit in VerifyBeforeCutover;
	// verification itself still takes place.
	MaxExpectedDowntime string

	// The interval at which the periodic binlog reverification occurs, in the
	// format of time.ParseDuration. Default: 1s.
	VerifyBinlogEventsInterval string

	verifyBinlogEventsInterval time.Duration
	maxExpectedDowntime        time.Duration
}

func (c *InlineVerifierConfig) Validate() error {
	var err error
	if c.MaxExpectedDowntime != "" {
		c.maxExpectedDowntime, err = time.ParseDuration(c.MaxExpectedDowntime)
		if err != nil {
			return err
		}
	} else {
		c.maxExpectedDowntime = time.Duration(0)
	}

	if c.VerifyBinlogEventsInterval == "" {
		c.VerifyBinlogEventsInterval = "1s"
	}

	c.verifyBinlogEventsInterval, err = time.ParseDuration(c.VerifyBinlogEventsInterval)
	if err != nil {
		return err
	}

	return nil
}

type IterativeVerifierConfig struct {
	// List of tables that should be ignored by the IterativeVerifier.
	IgnoredTables []string

	// List of columns that should be ignored by the IterativeVerifier.
	// This is in the format of table_name -> [list of column names]
	IgnoredColumns map[string][]string

	// The number of concurrent verifiers. Note that a single table can only be
	// assigned to one goroutine and currently multiple goroutines per table
	// is not supported.
	Concurrency int

	// The maximum expected downtime during cutover, in the format of
	// time.ParseDuration.
	MaxExpectedDowntime string

	// Map of the table and column identifying the compression type
	// (if any) of the column. This is used during verification to ensure
	// the data was successfully copied as some compression algorithms can
	// output different compressed data with the same input data.
	//
	// The data structure is a map of table names to a map of column names
	// to the compression algorithm.
	// ex: {books: {contents: snappy}}
	//
	// Currently supported compression algorithms are:
	//	1. Snappy (https://google.github.io/snappy/) as "SNAPPY"
	//
	// Optional: defaults to empty map/no compression
	//
	// Note that the IterativeVerifier is in the process of being deprecated.
	// If this is specified, CompressedColumnsForVerification should also be
	// filled out in the main Config.
	TableColumnCompression TableColumnCompressionConfig
}

func (c *IterativeVerifierConfig) Validate() error {
	if c.MaxExpectedDowntime != "" {
		_, err := time.ParseDuration(c.MaxExpectedDowntime)
		if err != nil {
			return err
		}
	}

	if c.Concurrency == 0 {
		c.Concurrency = 4
	}

	return nil
}

type ControlServerConfig struct {
	// enable/disable http control server
	Enabled bool

	// Bind control server address
	ServerBindAddr string

	// Path to the directory containing the `webui` directory
	WebBasedir string

	// TODO: refactor control server config out of the base ferry at some point
	// This adds optional buttons in the web ui that runs a script located at the
	// path specified.
	// The format is "script name" => ["path to script", "arg1", "arg2"]. The script name
	// will be displayed on the web ui.
	CustomScripts map[string][]string
}

func (c *ControlServerConfig) Validate() error {
	// this is used to update the web base dir path from the debian packager
	if WebUiBasedir != "" {
		c.WebBasedir = WebUiBasedir
	}

	if c.ServerBindAddr == "" {
		c.ServerBindAddr = "0.0.0.0:8000"
	}

	if c.WebBasedir == "" {
		c.WebBasedir = "."
	}

	return nil
}

// SchemaName => TableName => ColumnName => CompressionAlgorithm
// Example: blog1 => articles => body => snappy
//
//	(SELECT body FROM blog1.articles => returns compressed blob)
type ColumnCompressionConfig map[string]map[string]map[string]string

func (c ColumnCompressionConfig) CompressedColumnsFor(schemaName, tableName string) map[string]string {
	tableConfig, found := c[schemaName]
	if !found {
		return nil
	}

	columnsConfig, found := tableConfig[tableName]
	if !found {
		return nil
	}

	return columnsConfig
}

// SchemaName => TableName => ColumnName => struct{}{}
// These columns will be ignored during InlineVerification
type ColumnIgnoreConfig map[string]map[string]map[string]struct{}

func (c ColumnIgnoreConfig) IgnoredColumnsFor(schemaName, tableName string) map[string]struct{} {
	tableConfig, found := c[schemaName]
	if !found {
		return nil
	}

	columnsConfig, found := tableConfig[tableName]
	if !found {
		return nil
	}

	return columnsConfig
}

// SchemaName => TableName => IndexName
// These indices will be forced for queries in InlineVerification
type ForceIndexConfig map[string]map[string]string

func (c ForceIndexConfig) IndexFor(schemaName, tableName string) string {
	tableConfig, found := c[schemaName]
	if !found {
		return ""
	}

	index, found := tableConfig[tableName]
	if !found {
		return ""
	}

	return index
}

// CascadingPaginationColumnConfig to configure pagination columns to be
// used. The term `Cascading` to denote that greater specificity takes
// precedence.
//
// IMPORTANT: All configured pagination columns must contain unique values.
// When specifying a FallbackColumn for tables with composite primary keys,
// ensure the column has a unique constraint to prevent data loss during migration.
type CascadingPaginationColumnConfig struct {
	// PerTable has greatest specificity and takes precedence over the other options
	PerTable map[string]map[string]string // SchemaName => TableName => ColumnName

	// FallbackColumn is a global default to fallback to and is less specific than the
	// default, which is the Primary Key.
	// This column MUST have unique values (ideally a unique constraint) for data integrity.
	FallbackColumn string
}

// PaginationColumnFor is a helper function to retrieve the column name to paginate by
func (c *CascadingPaginationColumnConfig) PaginationColumnFor(schemaName, tableName string) (string, bool) {
	if c == nil {
		return "", false
	}

	tableConfig, found := c.PerTable[schemaName]
	if !found {
		return "", false
	}

	column, found := tableConfig[tableName]
	if !found {
		return "", false
	}

	return column, true
}

// FallbackPaginationColumnName retreives the column name specified as a fallback when the Primary Key isn't suitable for pagination
func (c *CascadingPaginationColumnConfig) FallbackPaginationColumnName() (string, bool) {
	if c == nil || c.FallbackColumn == "" {
		return "", false
	}

	return c.FallbackColumn, true
}

type DataIterationBatchSizePerTableOverride struct {
	// Lower limit for rowSize, if a rowSize <= MinRowSize, ControlPoints[MinRowSize] will be used
	MinRowSize int
	// Upper limit for rowSize, if a rowSize >= MaxRowSize, ControlPoints[MaxRowSize] will be used
	MaxRowSize int
	// Map of rowSize  => batchSize used to calculate batchSize for new rowSizes, results stored in TableOverride
	ControlPoints map[int]uint64
	// Map of schemaName(source schema) => tableName => batchSize to override default values for certain tables
	TableOverride map[string]map[string]uint64
}

func (d *DataIterationBatchSizePerTableOverride) Validate() error {
	if d != nil {
		if _, found := d.ControlPoints[d.MinRowSize]; !found {
			return fmt.Errorf("must provide batch size for MinRowSize")
		}
		if _, found := d.ControlPoints[d.MaxRowSize]; !found {
			return fmt.Errorf("must provide batch size for MaxRowSize")
		}
		if d.TableOverride == nil {
			d.TableOverride = map[string]map[string]uint64{}
		}
	}
	return nil
}

func (d *DataIterationBatchSizePerTableOverride) UpdateBatchSizes(db *sql.DB, tables TableSchemaCache) error {
	schemaTablesMap := map[string][]string{}

	for _, table := range tables {
		if _, found := d.TableOverride[table.Schema][table.Name]; found {
			continue
		}
		schemaTablesMap[table.Schema] = append(schemaTablesMap[table.Schema], table.Name)
	}

	for schemaName, tableNames := range schemaTablesMap {
		if _, found := d.TableOverride[schemaName]; !found {
			d.TableOverride[schemaName] = map[string]uint64{}
		}
		query := fmt.Sprintf(
			`SELECT T1.TABLE_NAME, AVG_ROW_LENGTH, MAX_BATCH_SIZE
					FROM information_schema.TABLES T1
						JOIN (SELECT TABLE_NAME, TABLE_SCHEMA, floor(%d / count(*)) MAX_BATCH_SIZE
						FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = '%s' AND TABLE_NAME in ('%s')
						GROUP BY table_name) T2 USING (TABLE_SCHEMA, TABLE_NAME);`,
			MySQLNumParamsLimit,
			schemaName,
			strings.Join(tableNames, `', '`),
		)
		rows, err := db.Query(query)
		if err != nil {
			return err
		}
		defer rows.Close()
		for rows.Next() {
			var avgRowLength, maxBatchSize int
			var tableName string
			err = rows.Scan(&tableName, &avgRowLength, &maxBatchSize)
			if err != nil {
				return err
			}
			// MySQL has an upper limit of 2^16 for num_params for prepared statements. This will cause an error when
			// we attempt to execute a INSERT statement with > 65535 parameters.
			// If batchSize > 65535/num_columns, we will use 65535/num_columns
			batchSize := d.CalculateBatchSize(avgRowLength)
			if batchSize >= maxBatchSize {
				batchSize = maxBatchSize
			}
			d.TableOverride[schemaName][tableName] = uint64(batchSize)
		}

	}
	return nil
}

func (d *DataIterationBatchSizePerTableOverride) CalculateBatchSize(rowSize int) int {
	if batchSize, found := d.ControlPoints[rowSize]; found {
		return int(batchSize)
	}
	if rowSize >= d.MaxRowSize {
		return int(d.ControlPoints[d.MaxRowSize])
	}
	if rowSize <= d.MinRowSize {
		return int(d.ControlPoints[d.MinRowSize])
	}

	closestPointLessThanRowSize := d.MinRowSize
	closestPointGreaterThanRowSize := d.MaxRowSize
	for size := range d.ControlPoints {
		if size < rowSize && rowSize-size < rowSize-closestPointLessThanRowSize {
			closestPointLessThanRowSize = size
		}
		if size > rowSize && size-rowSize < closestPointGreaterThanRowSize-rowSize {
			closestPointGreaterThanRowSize = size
		}
	}
	return linearInterpolation(
		rowSize, closestPointLessThanRowSize,
		int(d.ControlPoints[closestPointLessThanRowSize]),
		closestPointGreaterThanRowSize,
		int(d.ControlPoints[closestPointGreaterThanRowSize]),
	)
}

func linearInterpolation(x, x0, y0, x1, y1 int) int {
	return y0*(x1-x)/(x1-x0) + y1*(x-x0)/(x1-x0)
}

type Config struct {
	// Source database connection configuration
	//
	// Required
	Source *DatabaseConfig

	// Target database connection configuration
	//
	// Required
	Target *DatabaseConfig

	// Map database name on the source database (key of the map) to a
	// different name on the target database (value of the associated key).
	// This allows one to move data and change the database name in the
	// process.
	//
	// Optional: defaults to empty map/no rewrites
	DatabaseRewrites map[string]string

	// Map the table name on the source database to a different name on
	// the target database. See DatabaseRewrite.
	//
	// Optional: defaults to empty map/no rewrites
	TableRewrites map[string]string

	// The maximum number of retries for writes if the writes failed on
	// the target database.
	//
	// Optional: defaults to 5.
	DBWriteRetries int

	// Filter out the databases/tables when detecting the source databases
	// and tables.
	//
	// Required
	TableFilter TableFilter

	// Filter out unwanted data/events from being copied.
	//
	// Optional: defaults to nil/no filter.
	CopyFilter CopyFilter

	// The server id used by Ghostferry to connect to MySQL as a replication
	// slave. This id must be unique on the MySQL server. If 0 is specified,
	// a random id will be generated upon connecting to the MySQL server.
	//
	// Optional: defaults to an automatically generated one
	MyServerId uint32

	// The maximum number of binlog events to write at once. Note this is a
	// maximum: if there are not a lot of binlog events, they will be written
	// one at a time such the binlog streamer lag is as low as possible. This
	// batch size will only be hit if there is a log of binlog at the same time.
	//
	// Optional: defaults to 100
	BinlogEventBatchSize int

	// This optional config uses different data points to calculate
	// batch size per table using linear interpolation
	DataIterationBatchSizePerTableOverride *DataIterationBatchSizePerTableOverride

	// The maximum number of retries for reads if the reads fail on the source
	// database.
	//
	// Optional: defaults to 60
	DBReadRetries int

	// This specifies the number of concurrent goroutines, each iterating over
	// a single table.
	//
	// Concurrency is across tables: a single table is always iterated by one
	// goroutine and is not split among workers.
	//
	// Optional: defaults to 4
	DataIterationConcurrency int

	// This specifies if Ghostferry will pause before cutover or not.
	//
	// Optional: defaults to false
	AutomaticCutover bool

	// This specifies whether or not Ferry.Run installs a SIGINT and SIGTERM
	// handler that reports the signal as a fatal error, so that the error
	// handler can dump the current state for resuming Ghostferry. With the
	// default error handler, the state is only written to stdout if
	// DumpStateToStdoutOnError is also set (and sent to the ErrorCallback, if
	// configured). A signal received during cutover is logged and ignored; a
	// signal received after the run is done exits the process.
	DumpStateOnSignal bool

	// This specifies whether or not Ghostferry will dump the current state to stdout
	// before exiting due to an error.
	//
	// Optional: defaults to false
	DumpStateToStdoutOnError bool

	// This excludes schema cache from the state dump in both the HTTP callback
	// and the stdout dumping. This may save a lot of space if you don't need
	// to deal with schema migrations.
	DoNotIncludeSchemaCacheInStateDump bool

	// Config for the ControlServer
	ControlServerConfig *ControlServerConfig

	// Report progress via an HTTP callback. The Payload field of the callback
	// will be sent to the server as the CustomPayload field in the Progress
	// struct. The unit of ProgressReportFrequency is in milliseconds.
	ProgressCallback        HTTPCallback
	ProgressReportFrequency int

	// Report state via an HTTP callback. The serialized SerializableState
	// (the same JSON as the state dump) will be sent as the Payload parameter.
	// The unit of StateReportFrequency is in milliseconds.
	StateCallback        HTTPCallback
	StateReportFrequency int

	// Report error via an HTTP callback. The Payload field will contain a JSON
	// object with the ErrFrom, ErrMessage and StateDump fields.
	ErrorCallback HTTPCallback

	// Report when ghostferry is entering cutover
	CutoverLock HTTPCallback

	// Report when ghostferry is finished cutover
	CutoverUnlock HTTPCallback

	// If the callback returns a non OK status, these two values configure the number of times Ferry should attempt to
	// retry acquiring the cutover lock, and for how long the Ferry should wait
	// before attempting another lock acquisition
	// MaxCutoverRetries default is 1 retry
	// CutoverRetryWaitSeconds default is 1 second
	MaxCutoverRetries       int
	CutoverRetryWaitSeconds int

	// The state to resume from as dumped by the PanicErrorHandler.
	// If this is null, a new Ghostferry run will be started. Otherwise, the
	// reconciliation process will start and Ghostferry will resume after that.
	StateToResumeFrom *SerializableState

	// The data verifier to use during the run. Valid choices are:
	// ChecksumTable
	// Inline
	// Iterative (deprecated)
	// NoVerification
	//
	// If it is left blank, the Verifier member variable on the Ferry will be
	// used, which allows a custom verifier. If that member variable is nil, no
	// verification will be done. Target verification (see
	// SkipTargetVerification) is independent of this choice.
	VerifierType string

	// Only useful if VerifierType == Iterative.
	// This specifies the configurations to the IterativeVerifier.
	//
	// This option is in the process of being deprecated.
	IterativeVerifierConfig IterativeVerifierConfig

	// Only useful if VerifierType == Inline.
	// This specifies the configurations to the InlineVerifierConfig.
	InlineVerifierConfig InlineVerifierConfig

	// For old versions mysql<5.6.2, MariaDB<10.1.6 which has no related var
	// Make sure you have binlog_row_image=FULL when turning on this
	SkipBinlogRowImageCheck bool

	// BinlogCoordinateMode selects how binlog coordinates are tracked.
	//
	// Valid values:
	//   - "" or "file_position": the classic (file, position) coordinate. This
	//     is the default.
	//   - "gtid": GTID-set based coordinates (experimental, MySQL only).
	//     Requires @@GLOBAL.gtid_mode=ON on the source, on the target when
	//     target verification is enabled, and on the replication master when
	//     running from a replica.
	//
	// In GTID mode, LastSuccessfulBinlogPos still reports the streamed
	// file/position, while FinalBinlogPos remains unset; use
	// LastSuccessfulBinlogCoordinate and FinalBinlogCoordinate instead.
	BinlogCoordinateMode BinlogCoordinateType

	// This config is necessary for inline verification for a special case of
	// Ghostferry:
	//
	// - If you are copying a table where the data is already partially on the
	//   target through some other means.
	//   - Specifically, the PaginationKey of this row on both the source and the target are
	//     the same. Thus, INSERT IGNORE will skip copying this row, leaving the
	//     data on the target unchanged.
	//   - If the data on the target is already identical to the source, then
	//     verification will pass and all is well.
	// - However, if this data is compressed with a non-determinstic algorithm
	//   such as snappy, the compressed blob may not be equal even when the
	//   uncompressed data is equal.
	// - This column signals to the InlineVerifier that it needs to decompress
	//   the data to compare identity.
	//
	// Note: a similar option exists in IterativeVerifier. However, the
	// IterativeVerifier is being deprecated and this will be the correct place
	// to specify it if you don't need the IterativeVerifier.
	CompressedColumnsForVerification ColumnCompressionConfig

	// This config is also for inline verification for the same special case of
	// Ghostferry as documented with the CompressedColumnsForVerification option:
	//
	// - If you're copying a table where the data is partially already on the
	//   the target through some other means.
	// - A difference in a particular column could be acceptable.
	//   - An example would be a table with a data field and a created_at field.
	//     Maybe the created_at field is not important for data integrity as long
	//     as the data field is correct.
	// - Putting the column in this config will cause the InlineVerifier to skip
	//   this column for verification.
	IgnoredColumnsForVerification ColumnIgnoreConfig

	// Map an index to a table, will add `FORCE INDEX (index_name)` to the fingerprint SELECT query.
	// Index hinting might be necessary if you are running into slow queries during copy on your target.
	//
	// Example:
	//
	// "ForceIndexForVerification": {
	//   "blog": {
	//     "users": "ix_users_some_id"
	//   }
	// }
	//
	ForceIndexForVerification ForceIndexConfig

	// Ghostferry requires a single numeric or binary column to paginate over tables. Inferring that column is done in the following exact order:
	// 1. Use the PerTable pagination column, if configured for a table.
	// 2. Otherwise, use the table's primary key if it consists of a single column.
	// 3. Otherwise (no primary key, or a composite primary key), use the FallbackColumn, if configured.
	// Schema loading fails if no column is selected, if the selected column does not exist, or if it is not an
	// integer or binary column (BINARY/VARBINARY, or CHAR/VARCHAR with a binary collation). A single-column
	// primary key of an unsupported type is not replaced by the FallbackColumn; it fails.
	// Numeric pagination keys must be positive integers and binary pagination keys must be non-empty, as
	// pagination starts after zero/the empty value.
	//
	// IMPORTANT: The pagination column MUST contain unique, non-NULL values for data integrity. Ghostferry does
	// not validate this; the caller is responsible for it, ideally with a unique constraint on the column.
	// The pagination algorithm uses WHERE pagination_key > last_key ORDER BY pagination_key LIMIT batch_size.
	// If duplicate values exist, rows may be skipped during iteration, resulting in data loss during the migration.
	CascadingPaginationColumnConfig *CascadingPaginationColumnConfig

	// SkipTargetVerification is used to enable or disable target verification during moves.
	// When false (the default), target verification is enabled regardless of the VerifierType.
	//
	// Target verification streams the Target's binlog and inspects the annotations (configured as Marginalia
	// in the DatabaseConfig above), failing the move unless all applicable DMLs sent to the Target carry
	// Ghostferry's annotation. It detects unexpected writers; it does not compare row data.
	//
	// NOTE:
	// The Target database must be configured with binlog_rows_query_log_events
	// set to "ON" for this to function properly. While target verification
	// is enabled (this field is false), Ghostferry does not allow the move
	// process to begin if the Source has
	// binlog_rows_query_log_events set to "OFF".
	//
	// Optional: defaults to false
	SkipTargetVerification bool

	// During initialization, Ghostferry will raise an error if any
	// foreign key constraints are detected in the source database.
	//
	// This check can be bypassed by setting this value to true.
	//
	// WARNING:
	// Using Ghostferry with foreign keys is highly discouraged and
	// disabling this check makes no guarantees of the success of the run.
	//
	// Required: defaults to false
	SkipForeignKeyConstraintsCheck bool

	// EnableRowBatchsize is used to enable or disable the calculation of number of bytes written for each row batch.
	//
	// Optional: Defaults to false.
	//
	// NOTE:
	// Turning off the EnableRowBatchSize flag would show the NumBytes written per RowBatch to be zero
	// in the Progress. This behaviour is perfectly okay and doesn't mean there are no rows being written
	// to the target DB.
	EnableRowBatchSize bool

	// If the target DB is set to read_only ghostferry will throw an error during the initialization step.
	// AllowSuperUserOnReadOnly flag allows to run ghostferry even if the target DB is read_only. This is helpful in
	// scenarios where target DB needs to be restricted from writes made by any other user then the ghostferry user.
	//
	// Optional: Defaults to false.
	//
	// NOTE:
	// The ghostferry target user should have SUPER permissions to actually write to the target DB,
	// if ghostferry is ran with AllowSuperUserOnReadOnly = true and the target DB is set to read_only.
	AllowSuperUserOnReadOnly bool

	// If true, net/http/pprof will be enabled on port 6060.
	EnablePProf bool

	// LogBackend selects the logging backend to use.
	// Valid values: "logrus" (default), "zerolog".
	// Can also be set via the GHOSTFERRY_LOG_BACKEND environment variable.
	//
	// Optional: defaults to "logrus"
	LogBackend string

	// LogLevel sets the logging verbosity.
	// Valid values: "debug", "info", "warn", "error".
	// Can also be set via the GHOSTFERRY_LOG_LEVEL environment variable.
	// Note: the --verbose CLI flag, if present, takes precedence over this setting.
	//
	// Optional: defaults to "info"
	LogLevel string

	// ----------------------------------------------------------------------------------------------------------------
	// Updatable config
	// The following configs are updatable via the `Config.Update` method and should be passed by pointer

	UpdatableConfig UpdatableConfig

	// ----------------------------------------------------------------------------------------------------------------
	// DEPRECATED CONFIGS
	// The following configs are deprecated
	DataIterationBatchSize     uint64              // replaced by UpdatableConfig.DataIterationBatchSize
	ServerBindAddr             string              // replaced by ControlServerConfig.ServerBindAddr
	WebBasedir                 string              // replaced by ControlServerConfig.WebBasedir
	ControlServerCustomScripts map[string][]string // replaced by ControlServerConfig.CustomScripts
}

func (c *Config) ValidateConfig() error {
	// Configure logging backend and level early, before any validation logging occurs.
	if c.LogBackend != "" {
		SetLogBackend(LogBackendType(c.LogBackend))
	}

	if c.LogLevel != "" {
		level, ok := ParseLogLevel(c.LogLevel)
		if !ok {
			return fmt.Errorf("invalid LogLevel %q (valid: debug, info, warn, error)", c.LogLevel)
		}
		SetLogLevel(level)
	}

	if err := c.Source.Validate(); err != nil {
		return fmt.Errorf("source: %s", err)
	}

	if err := c.Target.Validate(); err != nil {
		return fmt.Errorf("target: %s", err)
	}

	if c.TableFilter == nil {
		return fmt.Errorf("Table filter function must be provided")
	}

	if c.StateToResumeFrom != nil && c.StateToResumeFrom.GhostferryVersion != VersionString {
		return fmt.Errorf("StateToResumeFrom version mismatch: resume = %s, current = %s", c.StateToResumeFrom.GhostferryVersion, VersionString)
	}

	switch c.BinlogCoordinateMode {
	case "":
		c.BinlogCoordinateMode = BinlogCoordinateFilePosition
	case BinlogCoordinateFilePosition, BinlogCoordinateGTID:
	default:
		return fmt.Errorf("invalid BinlogCoordinateMode %q, must be %q or %q", c.BinlogCoordinateMode, BinlogCoordinateFilePosition, BinlogCoordinateGTID)
	}

	if c.VerifierType == VerifierTypeIterative {
		if err := c.IterativeVerifierConfig.Validate(); err != nil {
			return fmt.Errorf("IterativeVerifierConfig invalid: %v", err)
		}
	} else if c.VerifierType == VerifierTypeInline {
		if err := c.InlineVerifierConfig.Validate(); err != nil {
			return fmt.Errorf("InlineVerifierConfig invalid: %v", err)
		}
	}

	if c.ControlServerConfig == nil {
		c.ControlServerConfig = &ControlServerConfig{}
	}

	c.checkForDeprecatedConfig()

	if err := c.ControlServerConfig.Validate(); err != nil {
		return fmt.Errorf("control_server: %s", err)
	}

	if c.DBWriteRetries == 0 {
		c.DBWriteRetries = 5
	}

	if err := c.UpdatableConfig.Validate(); err != nil {
		return fmt.Errorf("updatable config: %s", err)
	}

	if err := c.DataIterationBatchSizePerTableOverride.Validate(); err != nil {
		return fmt.Errorf("DataIterationBatchSizePoints invalid: %s", err)
	}

	if c.BinlogEventBatchSize == 0 {
		c.BinlogEventBatchSize = 100
	}

	if c.DataIterationConcurrency == 0 {
		c.DataIterationConcurrency = 4
	}

	if c.DBReadRetries == 0 {
		c.DBReadRetries = 60
	}

	if c.MaxCutoverRetries == 0 {
		c.MaxCutoverRetries = 1
	}

	if c.CutoverRetryWaitSeconds == 0 {
		c.CutoverRetryWaitSeconds = 1
	}

	return nil
}

func (c *Config) checkForDeprecatedConfig() {
	if c.DataIterationBatchSize != 0 {
		c.logDeprecated("DataIterationBatchSize", "UpdatableConfig.DataIterationBatchSize")
		c.UpdatableConfig.DataIterationBatchSize = c.DataIterationBatchSize
	}

	if c.ServerBindAddr != "" {
		c.logDeprecated("ServerBindAddr", "ControlServerConfig.ServerBindAddr")
		c.ControlServerConfig.ServerBindAddr = c.ServerBindAddr
	}

	if c.WebBasedir != "" {
		c.logDeprecated("WebBasedir", "ControlServerConfig.WebBasedir")
		c.ControlServerConfig.WebBasedir = c.WebBasedir
	}

	if len(c.ControlServerCustomScripts) != 0 {
		c.logDeprecated("ControlServerCustomScripts", "ControlServerConfig.CustomScripts")
		c.ControlServerConfig.CustomScripts = c.ControlServerCustomScripts
	}
}

func (c *Config) logDeprecated(deprecatedConfig string, newConfig string) {
	LogWithField("tag", "config").Warnf("Config.%s is deprecated in favour of Config.%s", deprecatedConfig, newConfig)
}

func (c *Config) Update(updatedConfig UpdatableConfig) {
	if updatedConfig.DataIterationBatchSize > 0 {
		c.UpdatableConfig.DataIterationBatchSize = updatedConfig.DataIterationBatchSize
	}
}

// UpdatableConfig defines config fields that support dynamic updates
type UpdatableConfig struct {
	// The maximum batch size used to iterate the data during data copy. A batch
	// may contain fewer rows (for example the last batch of a table), and
	// DataIterationBatchSizePerTableOverride can set other sizes per table.
	//
	// With the current implementation of Ghostferry, we need to lock the rows
	// we select. This means, the larger this number is, the longer we need to
	// hold this lock. On the flip side, the smaller this number is, the slower
	// the copy will likely be.
	//
	// Optional: defaults to 200
	DataIterationBatchSize uint64

	// End of Updatable config
	// ----------------------------------------------------------------------------------------------------------------
}

func (c *UpdatableConfig) Validate() error {
	if c.DataIterationBatchSize == 0 {
		c.DataIterationBatchSize = 200
	}

	return nil
}