github.com/pingcap/tiflow@v0.0.0-20240520035814-5bf52d54e205/dm/pkg/shardddl/pessimism/doc.go (about)

     1  // Copyright 2020 PingCAP, Inc.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // See the License for the specific language governing permissions and
    12  // limitations under the License.
    13  
    14  // The sequence of coordinate a shard DDL lock:
    15  //   1. DM-master GET all history `Info` & construct/sync shard DDL locks (revision-M1).
    16  //      - also PUT the `Operation` of synced locks as step-4.
    17  //   2. DM-worker construct `Info` based on received shard DDL & PUT the `Info` into etcd (revision-W1).
    18  //   3. DM-master get `Info` through WATCH (after revision-M1) & try to construct/sync the `Lock`.
    19  //   4. DM-master PUT the `Operation` into etcd (revision-M2).
    20  //   5. DM-worker get `Operation` through WATCH (after revision-W1).
    21  //   6. DM-worker exec the `Operation` (execute/skip the shard DDL statements).
    22  //   7. DM-worker flush the checkpoint.
    23  //   8. DM-worker PUT `done=true` of `Operation` & DELETE the `Info` (in one txn, revision-W2).
    24  //   9. DM-master get `done=true` of `Operation` through WATCH (after revision-M1).
    25  //   10. DM-master DELETE the `Operation` after all DM-worker finished the operation (revision-M3).
    26  //
    27  // for step-4:
    28  //   1. DM-master PUT `exec=true` `Operation` for the shard DDL lock owner.
    29  //   2. DM-master wait for the owner to finish the `Operation`.
    30  //   3. DM-master PUT `exec=false` `Operation` for other DM-workers.
    31  //
    32  // the order of revision:
    33  //   * revision-M1 < revision-W1 < revision-M2 < revision-W2 < revision-M3.
    34  //
    35  // the operation on `Info`:
    36  //   * PUT & DELETE by DM-worker (in revision-W1 & revision-W2).
    37  //   * GET & WATCH by DM-master (for all revision).
    38  //
    39  // the operation on `Operation`:
    40  //   * PUT & DELETE by DM-master (in revision-M2 & revision-M3).
    41  //   * PUT (update) by DM-worker (in revision-W2).
    42  //   * GET by DM-worker (after revision-W1).
    43  //   * WATCH by DM-master (after revision-M1).
    44  //
    45  // re-entrant of DM-worker:
    46  //   * before step-6:
    47  //     * just re-run the sequence of the flow is fine.
    48  //   * in step-6:
    49  //     * operation has canceled: like `before step-6`.
    50  //     * operation has done: need to tolerate the re-execution of DDL statements,
    51  //       such as ignore `ErrColumnExists` for `ADD COLUMN`.
    52  //       TODO(csuzhangxc): flush checkpoint before execute/skip shard DDL statements.
    53  //   * in step-7:
    54  //     * operation has canceled: like `operation has done` in step-6.
    55  //     * operation has done: need to use `unlock-ddl-lock` resolve the lock manually.
    56  //       TODO(csuzhangxc): if we can find out this case correctly, it may be handled automatically later.
    57  //   * in step-8:
    58  //     * operation has canceled: like `operation has done` in step-7.
    59  //     * operation has done: just re-run the sequence of the flow is fine.
    60  //   * after step-8:
    61  //     * just re-run the sequence of the flow is fine.
    62  //
    63  // re-entrant of DM-master:
    64  //   * just re-run the sequence of the flow is fine.
    65  //   * do not overwrite the result of `Operation` PUTed by DM-worker in step-4.
    66  
    67  package pessimism