fix: improve documentation for SHOW TASKS and cutover flow#95
Open
meskill wants to merge 1 commit into
Open
Conversation
levkk
reviewed
Jul 1, 2026
| ``` | ||
|
|
||
| !!! note "Admin database tasks only" | ||
| `SHOW TASKS` lists the background tasks running *inside this PgDog process* — the ones started by the admin database commands above. The equivalent [CLI commands](../features/sharding/resharding/index.md#running-the-steps-manually) (`pgdog data-sync`, `pgdog schema-sync`) run as a separate, one-off `pgdog` process in the foreground: they block until they finish and are stopped with `Ctrl-C`, so they neither return a `task_id` nor appear here. |
Contributor
There was a problem hiding this comment.
Suggested change
| `SHOW TASKS` lists the background tasks running *inside this PgDog process* — the ones started by the admin database commands above. The equivalent [CLI commands](../features/sharding/resharding/index.md#running-the-steps-manually) (`pgdog data-sync`, `pgdog schema-sync`) run as a separate, one-off `pgdog` process in the foreground: they block until they finish and are stopped with `Ctrl-C`, so they neither return a `task_id` nor appear here. | |
| `SHOW TASKS` lists the background tasks running inside the same PgDog process. The equivalent [CLI commands](../features/sharding/resharding/index.md#running-the-steps-manually) (`pgdog data-sync`, `pgdog schema-sync`) spawn their own process in the foreground instead, and block until they finish or are stopped with `SIGINT` (or `SIGTERM`). |
levkk
reviewed
Jul 1, 2026
| elapsed_ms | 191569 | ||
| ``` | ||
|
|
||
| The most recently started task is listed first. |
Contributor
There was a problem hiding this comment.
Suggested change
| The most recently started task is listed first. | |
| Tasks are ordered by creation date, starting at the oldest. |
levkk
reviewed
Jul 1, 2026
|
|
||
| | Column | Description | | ||
| |-|-| | ||
| | `id` | The task's id. This is the handle you pass to [`STOP_TASK`](#stopping-a-task) and [`CUTOVER`](../features/sharding/resharding/cutover.md). Only **root** rows carry an id; subtasks share their root's id and leave this column empty. | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `id` | The task's id. This is the handle you pass to [`STOP_TASK`](#stopping-a-task) and [`CUTOVER`](../features/sharding/resharding/cutover.md). Only **root** rows carry an id; subtasks share their root's id and leave this column empty. | | |
| | `id` | The task ID. This is the handle you pass to [`STOP_TASK`](#stopping-a-task) and [`CUTOVER`](../features/sharding/resharding/cutover.md). Only root tasks have an ID; subtasks share their parent's ID and leave this column empty. | |
levkk
reviewed
Jul 1, 2026
| |-|-| | ||
| | `id` | The task's id. This is the handle you pass to [`STOP_TASK`](#stopping-a-task) and [`CUTOVER`](../features/sharding/resharding/cutover.md). Only **root** rows carry an id; subtasks share their root's id and leave this column empty. | | ||
| | `scope` | `root` for a top-level task, `subtask` for a step it spawned (e.g. the `copy_data` and `replication` steps of a `reshard`). | | ||
| | `type` | What the task is, usually with the source and destination databases — e.g. `reshard`, `copy_data`, `replication`, `replication ... (reverse)`, `schema_sync(pre)`. | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `type` | What the task is, usually with the source and destination databases — e.g. `reshard`, `copy_data`, `replication`, `replication ... (reverse)`, `schema_sync(pre)`. | | |
| | `type` | What the task is, usually with the source and destination databases, e.g., `reshard`, `copy_data`, `replication`, `replication [...] (reverse)`, `schema_sync(pre)`. | |
levkk
reviewed
Jul 1, 2026
| | `scope` | `root` for a top-level task, `subtask` for a step it spawned (e.g. the `copy_data` and `replication` steps of a `reshard`). | | ||
| | `type` | What the task is, usually with the source and destination databases — e.g. `reshard`, `copy_data`, `replication`, `replication ... (reverse)`, `schema_sync(pre)`. | | ||
| | `status` | The lifecycle status of the task. See [Statuses](#statuses). | | ||
| | `inner_status` | Fine-grained progress within the current status. See [Progress](#progress). For a finished or failed task, this keeps the last progress it reported. | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `inner_status` | Fine-grained progress within the current status. See [Progress](#progress). For a finished or failed task, this keeps the last progress it reported. | | |
| | `inner_status` | Fine-grained progress within the current status. See [Progress](#progress). For a finished or failed task, this shows the last progress it reported. | |
levkk
reviewed
Jul 1, 2026
| | `status` | The lifecycle status of the task. See [Statuses](#statuses). | | ||
| | `inner_status` | Fine-grained progress within the current status. See [Progress](#progress). For a finished or failed task, this keeps the last progress it reported. | | ||
| | `started_at` | When the task started. | | ||
| | `updated_at` | When the task last changed status or progress. For a terminal task this is when it finished. | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `updated_at` | When the task last changed status or progress. For a terminal task this is when it finished. | | |
| | `updated_at` | When the task last changed status or progress. For a finished task this is when it finished. | |
levkk
reviewed
Jul 1, 2026
| | `inner_status` | Fine-grained progress within the current status. See [Progress](#progress). For a finished or failed task, this keeps the last progress it reported. | | ||
| | `started_at` | When the task started. | | ||
| | `updated_at` | When the task last changed status or progress. For a terminal task this is when it finished. | | ||
| | `elapsed` / `elapsed_ms` | How long the task ran. For a terminal task this is the total run time (measured to `updated_at`), not a clock that keeps ticking. | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `elapsed` / `elapsed_ms` | How long the task ran. For a terminal task this is the total run time (measured to `updated_at`), not a clock that keeps ticking. | | |
| | `elapsed` / `elapsed_ms` | How long the task ran. For a completed task this is the total run time (measured to `updated_at`). | |
levkk
reviewed
Jul 1, 2026
| | `failed: <error>` | The task errored. The error message is included in the status. | | ||
| | `panicked: <error>` | The task hit an unexpected internal error. | | ||
|
|
||
| `finished`, `cancelled`, `failed`, and `panicked` are **terminal**. Terminal tasks stay listed with their final status (and last progress) for a while so you can inspect the outcome, then they're pruned automatically. |
Contributor
There was a problem hiding this comment.
Suggested change
| `finished`, `cancelled`, `failed`, and `panicked` are **terminal**. Terminal tasks stay listed with their final status (and last progress) for a while so you can inspect the outcome, then they're pruned automatically. | |
| `finished`, `cancelled`, `failed`, and `panicked` are terminal. Terminal tasks stay listed with their final status (and last progress) for a while so you can inspect the outcome, then they're pruned automatically. |
levkk
reviewed
Jul 1, 2026
|
|
||
| ## Finding the right id | ||
|
|
||
| `STOP_TASK` and `CUTOVER` always operate on the **root** `id`: |
Contributor
There was a problem hiding this comment.
Suggested change
| `STOP_TASK` and `CUTOVER` always operate on the **root** `id`: | |
| `STOP_TASK` and `CUTOVER` always operate on the parent ID: |
Contributor
|
This will need a de-AI pass. Will come back to it in a bit. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
related to pgdogdev/pgdog#1106