> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wirekite.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Operations

> Monitor, pause, and control running Wirekite migrations using metadata tables.

## Overview

Wirekite uses two metadata tables to track migration progress and enable operational control:

* **wirekite\_progress** - Tracks every file/operation processed, storing position checkpoints for crash recovery
* **wirekite\_action** - Single-row control table for pause/stop/resume operations

These tables are created automatically in the target database when a migration starts.

## Metadata Tables

### wirekite\_progress

This table tracks the state of every extraction and loading operation, enabling crash recovery and progress monitoring.

**Schema:**

```sql theme={null}
CREATE TABLE wirekite.wirekite_progress (
    source VARCHAR(256),
    target VARCHAR(256),
    operation TEXT NOT NULL,
    transmission TEXT NOT NULL DEFAULT 'F',
    mark VARCHAR(64) NULL,
    table_name VARCHAR(256) NULL,
    start_time TIMESTAMP NOT NULL,
    finish_time TIMESTAMP NULL,
    restarts INT DEFAULT 0 NOT NULL,
    PRIMARY KEY (source, target)
);
```

<Note>
  The schema name varies by database: `wirekite` for PostgreSQL, MySQL, Oracle, SingleStore; `public` for Snowflake and Firebolt.
</Note>

**Column Reference:**

<ResponseField name="source" type="string">
  Primary key component. Identifies the file or resource being processed (e.g., `0.ckt`, `schema.table.0.dkt`, binlog name).
</ResponseField>

<ResponseField name="target" type="string">
  Primary key component. Identifies the destination or operation type.
</ResponseField>

<ResponseField name="operation" type="string">
  Operation code:

  * `D` - Data Load
  * `CE` - Change Extract
  * `C` - Change Load
</ResponseField>

<ResponseField name="transmission" type="string">
  Transfer mode:

  * `F` - File-based processing
</ResponseField>

<ResponseField name="mark" type="string">
  Progress checkpoint. Meaning depends on operation type:

  * **Data loaders**: Row count successfully committed
  * **Change extractors**: LSN/binlog position/SCN (database-specific position marker)
  * **Change loaders**: Sequence number in .ckt file
</ResponseField>

<ResponseField name="table_name" type="string">
  Associated table name for multi-table operations.
</ResponseField>

<ResponseField name="start_time" type="timestamp">
  When this operation started.
</ResponseField>

<ResponseField name="finish_time" type="timestamp">
  `NULL` while in progress; set to completion time when done. This is the critical recovery indicator.
</ResponseField>

<ResponseField name="restarts" type="integer">
  Counter tracking how many times this operation was restarted after a crash.
</ResponseField>

### wirekite\_action

This single-row table controls the running state of loaders and extractors.

**Schema:**

```sql theme={null}
CREATE TABLE wirekite.wirekite_action (
    action VARCHAR(5),
    PRIMARY KEY (action)
);

INSERT INTO wirekite.wirekite_action VALUES ('RUN');
```

**Valid Values:**

| Value   | Behavior                                                        |
| ------- | --------------------------------------------------------------- |
| `RUN`   | Normal operation - processes data continuously                  |
| `PAUSE` | Pause operation - component sleeps for 5 seconds between checks |
| `STOP`  | Stop operation - component exits gracefully                     |

## Pause, Stop, and Resume

Wirekite components poll the `wirekite_action` table during processing. This enables non-disruptive control without restarting processes.

### Using the Web Interface

The easiest way to control migrations is through the [Web Interface](/run/execution/ux):

1. Navigate to the migration details page
2. Click **Pause** to pause replication
3. Click **Resume** to continue
4. Click **Stop** to gracefully shut down

### Using SQL Commands

You can also control migrations directly via SQL on the target database:

**Pause Replication:**

```sql theme={null}
UPDATE wirekite.wirekite_action SET action = 'PAUSE';
```

**Resume Replication:**

```sql theme={null}
UPDATE wirekite.wirekite_action SET action = 'RUN';
```

**Stop Replication:**

```sql theme={null}
UPDATE wirekite.wirekite_action SET action = 'STOP';
```

<Warning>
  Always use `STOP` for graceful shutdown rather than killing the process. This ensures the current transaction completes and progress is recorded.
</Warning>

## Monitoring Progress

### Check Migration Status

Query `wirekite_progress` to see the state of all operations:

```sql theme={null}
SELECT source, operation, mark, start_time, finish_time, restarts
FROM wirekite.wirekite_progress
WHERE operation IN ('D', 'CE', 'C')
ORDER BY start_time DESC;
```

### Find Incomplete Operations

Identify operations that are still in progress or may be stuck:

```sql theme={null}
SELECT source, operation, table_name, start_time, restarts
FROM wirekite.wirekite_progress
WHERE finish_time IS NULL
ORDER BY start_time DESC;
```

Records with `finish_time IS NULL` and an old `start_time` may indicate a hung process.

### Monitor Restart Counts

High values in the `restarts` column indicate repeated failures:

```sql theme={null}
SELECT source, operation, restarts, start_time
FROM wirekite.wirekite_progress
WHERE restarts > 0
ORDER BY restarts DESC;
```

## Crash Recovery

Wirekite automatically recovers from crashes using the `wirekite_progress` table:

1. On startup, components check for records with `finish_time IS NULL`
2. If found, processing resumes from the position stored in `mark`
3. The `restarts` counter is incremented

This ensures zero data loss - partially loaded files resume from the last committed position.

## Resetting Migration State

<Warning>
  Resetting migration state can cause duplicate data if not done correctly. Always truncate both the progress table AND the target tables together.
</Warning>

To reset a migration and start fresh:

**1. Stop the migration:**

```sql theme={null}
UPDATE wirekite.wirekite_action SET action = 'STOP';
```

**2. Wait for processes to exit, then truncate progress on both source and target:**

```sql theme={null}
TRUNCATE TABLE wirekite.wirekite_progress;
```

**3. Truncate target tables that will be reloaded.**

**4. Reset action to RUN:**

```sql theme={null}
UPDATE wirekite.wirekite_action SET action = 'RUN';
```

**5. Restart the migration.**

## Safety Guidelines

<CardGroup cols={2}>
  <Card title="Never Delete Progress Records" icon="triangle-exclamation">
    Deleting records from `wirekite_progress` can cause duplicate data in the target or missed changes during replication.
  </Card>

  <Card title="Monitor Restarts" icon="rotate">
    High restart counts indicate repeated failures. Investigate the root cause before the issue compounds.
  </Card>

  <Card title="Check for Stuck Records" icon="clock">
    Records with NULL `finish_time` and old `start_time` may indicate hung processes that need investigation.
  </Card>

  <Card title="Coordinate Resets" icon="arrows-rotate">
    When resetting, always truncate `wirekite_progress` AND target tables together to prevent duplicates.
  </Card>
</CardGroup>