# Configuration Reference

The data clone system is configured through a `.meadow.config.json` file and/or CLI flags. This document covers the full configuration schema, cascading resolution behavior, and complete working examples.

## Configuration File

The configuration file is named `.meadow.config.json`. The CLI toolkit (`pict-service-commandlineutility`) automatically searches for this file using a cascading strategy.

### Cascading Resolution Order

The configuration file is resolved in the following order (first match wins):

1. **Current working directory** -- `.meadow.config.json` in the directory where the command is run.
2. **Parent directories** -- Walks up the directory tree searching for `.meadow.config.json`.
3. **Home directory** -- `~/.meadow.config.json` as a fallback.

Settings from the configuration file are merged with the built-in defaults. CLI flags override configuration file values.

## Full Configuration Schema

```json
{
    "Source": {
        "ServerURL": "https://api.example.com/1.0/",
        "UserID": false,
        "Password": false
    },
    "Destination": {
        "Provider": "MySQL",
        "MySQL": {
            "server": "127.0.0.1",
            "port": 3306,
            "user": "root",
            "password": "",
            "database": "meadow",
            "connectionLimit": 20
        },
        "MSSQL": {
            "server": "127.0.0.1",
            "port": 1433,
            "user": "sa",
            "password": "",
            "database": "meadow",
            "ConnectionPoolLimit": 20
        }
    },
    "SchemaPath": "./schema/Model-Extended.json",
    "Sync": {
        "DefaultSyncMode": "Initial",
        "PageSize": 100,
        "SyncEntityList": [],
        "SyncEntityOptions": {}
    }
}
```

## Section Reference

### Source

Configuration for the remote Meadow API server to clone data from.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ServerURL` | string | `"https://localhost:8080/1.0/"` | Base URL of the Meadow API (must include trailing `/1.0/`) |
| `UserID` | string or false | `false` | Username for API authentication; set to `false` to skip auth |
| `Password` | string or false | `false` | Password for API authentication; set to `false` to skip auth |

When `UserID` and `Password` are both `false`, the system skips authentication and makes unauthenticated requests.

### Destination

Configuration for the local database where cloned data is stored.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `Provider` | string | `"MySQL"` | Database provider: `"MySQL"` or `"MSSQL"` |
| `MySQL` | object | See below | MySQL-specific connection settings |
| `MSSQL` | object | See below | MSSQL-specific connection settings |

Only the section matching the selected `Provider` is used.

#### MySQL Settings

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `server` | string | `"127.0.0.1"` | MySQL server hostname |
| `port` | number | `3306` | MySQL server port |
| `user` | string | `"root"` | Database username |
| `password` | string | `""` | Database password |
| `database` | string | `"meadow"` | Database name |
| `connectionLimit` | number | `20` | Connection pool size |

#### MSSQL Settings

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `server` | string | `"127.0.0.1"` | MSSQL server hostname |
| `port` | number | `1433` | MSSQL server port |
| `user` | string | `"sa"` | Database username |
| `password` | string | `""` | Database password |
| `database` | string | `"meadow"` | Database name |
| `ConnectionPoolLimit` | number | `20` | Connection pool size |

### SchemaPath

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `SchemaPath` | string | `"./schema/Model-Extended.json"` | Path to the Meadow extended schema JSON file (resolved relative to the config file or CWD) |

The schema file is a compiled Stricture model containing table definitions, column metadata, and Meadow schema information. It is generated by `stricture` during the build process.

### Sync

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `DefaultSyncMode` | string | `"Initial"` | Default sync mode: `"Initial"` or `"Ongoing"` |
| `PageSize` | number | `100` | Number of records to fetch per API request |
| `SyncEntityList` | array | `[]` | List of entity (table) names to sync. Empty array means sync all entities in the schema |
| `SyncEntityOptions` | object | `{}` | Per-entity configuration overrides (keyed by entity name) |

#### SyncEntityList

When `SyncEntityList` is an empty array `[]`, the system syncs every entity found in the loaded schema. To sync only specific entities, list them by their table name:

```json
{
    "Sync": {
        "SyncEntityList": ["Book", "Author", "BookAuthorJoin"]
    }
}
```

Entities are synced in the order they appear in this list.

#### SyncEntityOptions

Per-entity overrides, keyed by entity name. Values are merged on top of the global `Sync.*` defaults at entity construction (any key accepted by the entity constructor).

When the config is consumed via the data-cloner headless pipeline (`retold-data-service-clone --config`, or the `/clone/sync/start` POST route), the following keys also take effect as **runtime overrides per entity** and win over the global runtime values: `BackSyncTimeLimit`, `MaxRecordsPerEntity`, `DateTimePrecisionMS`, `TrueUpPageSize`, `UseAdvancedIDPagination`, `SyncDeletedRecords`.

```json
{
    "Sync": {
        "BackSyncTimeLimit": 30000,
        "SyncEntityOptions": {
            "AuditLog": {
                "PageSize": 500
            },
            "Document": {
                "BackSyncTimeLimit": 600000
            }
        }
    }
}
```

In the example above, `Document` gets a 600s bisection budget while every other entity uses the global 30s. Unknown entity names in `SyncEntityOptions` are logged as a warning and ignored.

## CLI Flag Overrides

All configuration values can be overridden via CLI flags. CLI flags take precedence over values from `.meadow.config.json`.

### Source (API) Flags

| Flag | Long Form | Description |
|------|-----------|-------------|
| `-a` | `--api_server` | Source API server URL |
| `-u` | `--api_username` | API username |
| `-p` | `--api_password` | API password |

### Destination (Database) Flags

| Flag | Long Form | Description |
|------|-----------|-------------|
| `-d` | `--db_provider` | Database provider (`MySQL` or `MSSQL`) |
| `-dh` | `--db_host` | Database server hostname |
| `-dp` | `--db_port` | Database server port |
| `-du` | `--db_username` | Database username |
| `-dw` | `--db_password` | Database password |
| `-dn` | `--db_name` | Database name |

### Other Flags

| Flag | Long Form | Default | Description |
|------|-----------|---------|-------------|
| `-sp` | `--schema_path` | From config | Path to Meadow extended schema JSON |
| `-s` | `--sync_mode` | `"Initial"` | Sync mode: `Initial` or `Ongoing` |
| `-w` | `--post_run_delay` | `0` | Minutes to wait after sync before exiting |

### Example with Full CLI Overrides

```bash
mdwint data-clone \
  --api_server "https://api.prod.example.com/1.0/" \
  --api_username "sync_user" \
  --api_password "s3cret" \
  --db_provider "MySQL" \
  --db_host "db.local" \
  --db_port 3306 \
  --db_username "clone_user" \
  --db_password "db_pass" \
  --db_name "prod_clone" \
  --schema_path "./schema/Model-Extended.json" \
  --sync_mode "Initial"
```

## Complete Working Examples

### Example 1: MySQL Initial Clone

`.meadow.config.json`:

```json
{
    "Source": {
        "ServerURL": "https://api.example.com/1.0/",
        "UserID": "admin",
        "Password": "admin_password"
    },
    "Destination": {
        "Provider": "MySQL",
        "MySQL": {
            "server": "127.0.0.1",
            "port": 3306,
            "user": "root",
            "password": "root_password",
            "database": "app_clone",
            "connectionLimit": 20
        }
    },
    "SchemaPath": "./schema/Model-Extended.json",
    "Sync": {
        "DefaultSyncMode": "Initial",
        "PageSize": 200,
        "SyncEntityList": []
    }
}
```

Run:

```bash
mdwint data-clone
```

### Example 2: MSSQL Ongoing Sync with Specific Entities

`.meadow.config.json`:

```json
{
    "Source": {
        "ServerURL": "https://api.example.com/1.0/",
        "UserID": "sync_service",
        "Password": "service_password"
    },
    "Destination": {
        "Provider": "MSSQL",
        "MSSQL": {
            "server": "sql-server.local",
            "port": 1433,
            "user": "sa",
            "password": "YourStrong!Passw0rd",
            "database": "warehouse",
            "ConnectionPoolLimit": 10
        }
    },
    "SchemaPath": "/opt/schemas/Model-Extended.json",
    "Sync": {
        "DefaultSyncMode": "Ongoing",
        "PageSize": 100,
        "SyncEntityList": [
            "Customer",
            "Order",
            "OrderItem",
            "Product"
        ],
        "SyncEntityOptions": {}
    }
}
```

Run:

```bash
mdwint data-clone
```

### Example 3: No Authentication (Public API)

`.meadow.config.json`:

```json
{
    "Source": {
        "ServerURL": "http://public-api.example.com/1.0/",
        "UserID": false,
        "Password": false
    },
    "Destination": {
        "Provider": "MySQL",
        "MySQL": {
            "server": "127.0.0.1",
            "port": 3306,
            "user": "root",
            "password": "",
            "database": "public_data",
            "connectionLimit": 20
        }
    },
    "SchemaPath": "./schema/PublicModel-Extended.json",
    "Sync": {
        "DefaultSyncMode": "Initial",
        "PageSize": 500,
        "SyncEntityList": []
    }
}
```

### Example 4: CLI Overrides on Top of Config File

Given a minimal `.meadow.config.json`:

```json
{
    "SchemaPath": "./schema/Model-Extended.json",
    "Sync": {
        "DefaultSyncMode": "Initial",
        "PageSize": 100
    }
}
```

Override the source and destination at runtime:

```bash
mdwint data-clone \
  --api_server "https://staging.example.com/1.0/" \
  --api_username "dev" \
  --api_password "dev_pass" \
  --db_host "localhost" \
  --db_name "staging_clone" \
  --sync_mode "Ongoing"
```

## Configuration Validation

The `data-clone` command validates the following before starting:

1. `Source.ServerURL` must be set (via config or `--api_server`).
2. `SchemaPath` must be set (via config or `--schema_path`).
3. The destination database configuration for the selected provider must include at least `server` and `database`.

If any of these are missing, the command exits with an error message indicating which configuration is required.

## Using the Explanation Command

The CLI includes a built-in command to display the resolved configuration:

```bash
mdwint config
```

This shows the merged result of default values, configuration file values, and CLI overrides, helping you verify what settings will be used before running a data clone.