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

# Migration helper

> REST endpoints that generate the DirectQuery schema and export in-memory data to database-ready CSV files.

The migration helper is a set of REST endpoints that automate the one-off task of seeding a DirectQuery database from an existing in-memory Atoti Market Risk deployment. It generates the SQL DDL that matches the Atoti Market Risk datastore schema and extracts the in-memory data into database-ready CSV files.

<Warning>
  **The migration helper requires an in-memory data cube.** It reads rows directly from the in-memory `IDatastore` and uses the runtime `IActivePivotManagerDescription` to generate schema-compatible DDL. It is therefore only available when the application starts with `starter.deployment.type=in-memory` (the default). It is intentionally **not registered** when:

  * `starter.deployment.type=direct-query` — there is no in-memory dataset to extract.
  * `starter.deployment.type=query-node` — query-only nodes do not host a data cube.
</Warning>

## Typical workflow

1. Start Atoti Market Risk in in-memory mode and load the dataset you want to migrate.
2. Call the migration helper endpoints to produce the DDL and CSV files (see below).
3. Apply the DDL to your target database and load the CSV files.
4. Restart Atoti Market Risk with the DirectQuery profile pointing at the now-populated database (see [Getting started](../configuration-getting-started/supported-databases)).

## Endpoints

The controller is mounted at `host:port/mr-application/migrationHelper/` and exposes:

| Endpoint                                         | Method | Purpose                                                                                                                                                                                  |
| ------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/migrationHelper/sqlSchema`                     | `GET`  | Generates SQL DDL statements for the configured datastore schema. Query parameters: `database` (`SNOWFLAKE`, `MSSQL`, `DATABRICKS` — defaults to `SNOWFLAKE`), `databaseName`, `schema`. |
| `/migrationHelper/extract`                       | `POST` | Returns the DDL for a `DatabaseExtractionDTO` body. No CSVs are written.                                                                                                                 |
| `/migrationHelper/extractForDatabase/{database}` | `POST` | Full extraction: writes CSV files under the requested `outputDirectory` and returns the DDL.                                                                                             |

Names are mapped through [MrDirectQueryNameMapper](./name-mapper), so tables and columns in the generated DDL follow the same convention as the runtime DirectQuery schema (e.g. `TradePnLs` → `TRADEPNLS`, not `TRADE_PN_LS`).

The following stores are excluded from the generated schema by default (see `MRMigrationHelperRestController.getDefaultExtractionBuilder()`):

* Parent-child stores: `BookParentChild`, `CounterpartyParentChild`, `LegalEntityParentChild` — these are used to populate their hierarchy stores and are not needed in the DQ schema.
* Summary cube base stores: `BaseStore`, `SensiBaseStore`, `PnLBaseStore` — summary cubes are not supported under DirectQuery.
* The WhatIf simulation persistence table.
* Sign-off companion stores for `TradePnLs`, `TradeSensitivities`, `PnL`.

To customise the set of exported stores, subclass `MRMigrationHelperRestController` and override `getDefaultExtractionBuilder()`.

## Configuration properties

| Property                       | Default          | Description                                                                                                                                                                                             |
| ------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mr.migration.export.enabled`  | `true`           | Registers the `MRMigrationHelperRestController`. Set to `false` to remove the endpoints from deployments that do not need them.                                                                         |
| `mr.migration.export.base-dir` | `java.io.tmpdir` | Allowed base directory for CSV exports. Any `outputDirectory` requested by `POST /migrationHelper/extract*` that resolves outside this path (after normalization) is rejected with a runtime exception. |

Example:

```yaml theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
mr:
  migration:
    export:
      enabled: true
      base-dir: /data/mr-exports
```