HexaRocket DMAT: User Guide

HexaRocket DMAT (Database Migration Assessment Tool) finds the work that a migration to PostgreSQL needs. It reads your database catalog and your application source code. It does not change your database or your files.

Download the ZIP for your platform from the DMAT product page. It contains:

File	Purpose
`hexarocket-dmat` (`hexarocket-dmat.exe` on Windows)	The tool.
`hexarocket-dmat.yaml.example`	A full example configuration, with a comment for each setting.
`dmat-config-generator.html`	A form that makes a configuration file. Open it in a web browser.
`README.md`	The usage guide.

The tool stops working after its expiry date. Run version to see the date.

1. Install

Download the ZIP that matches your operating system and processor (Linux, macOS or Windows; amd64 for Intel or AMD, arm64 for ARM and Apple silicon), then extract it.

No other software is necessary. The database drivers are in the tool.

Linux and macOS

Make the tool executable:
```
chmod +x hexarocket-dmat
```
Check the tool:
```
./hexarocket-dmat version
```

If macOS shows "cannot be opened because it is from an unidentified developer":

Open System Settings > Privacy & Security.
Click Allow Anyway next to the message for hexarocket-dmat.
Run the command again.

Windows

Open PowerShell in the folder that contains the file.
Check the tool:
```
.\hexarocket-dmat.exe version
```

On Windows, use .\hexarocket-dmat.exe in place of ./hexarocket-dmat in all commands of this guide.

2. Choose the scan

Scan	Command	What it reads	Needs
Database scan	`dbscan`	The database catalog and the code stored in the database (procedures, functions, packages, triggers, views)	A database user with read access to the catalog (see section 5)
Source code scan	`appscan`	Application source files (SQL, Java, C#, Python, configuration files and more)	Read access to the source folders. A database connection is optional.

Supported source databases: Oracle, SQL Server, MySQL, MariaDB, EDB Postgres Advanced Server (EPAS) and CUBRID.

3. Make the configuration file

The tool reads its settings from hexarocket-dmat.yaml in the current folder. Use --config <file> to read another file.

Make the file in one of these ways:

Open dmat-config-generator.html in a web browser, fill in the form and copy the result.
Copy hexarocket-dmat.yaml.example and change it.
Copy one of the examples below.

The tool rejects a misspelled or unknown setting, and the error message names it.

Example: database scan

dbscan:
  databases:
    - db_type: oracle            # oracle, sqlserver, mysql, mariadb, epas, cubrid
      connection:
        db_url: "oracle://scan_user:password@dbhost:1521/ORCLPDB1"
      include_schemas:           # remove this list to scan all user schemas
        - HR
        - SALES

You can put more than one database in databases:. The tool scans them in one run and writes one combined report.

Example: source code scan

appscan:
  db_type: sqlserver             # the SQL dialect that the code uses
  repositories:
    - id: web-app
      path: /home/me/src/web-app
      exclude_tests: true        # do not count test projects
    - id: batch-jobs
      path: /home/me/src/batch
      excludes:
        - "**/*.min.js"

Each repository needs an id (a short name) and a path. The tool always skips node_modules, vendor, .git, build, dist, binary files and archives.

Connection strings (`db_url`)

Database	Format
Oracle	`oracle://user:password@host:1521/service_name`
SQL Server	`sqlserver://user:password@host:1433?database=dbname`
MySQL	`mysql://user:password@host:3306/dbname`
MariaDB	`mariadb://user:password@host:3306/dbname`
EPAS	`postgres://user:password@host:5432/dbname`
CUBRID	`cubrid://user:password@host:33000/dbname`

If the password contains a special character (@, :, /, #, ?, %), replace it with its percent code. For example, write @ as %40.

4. Run the scan

./hexarocket-dmat dbscan  --config hexarocket-dmat.yaml --out reports/
./hexarocket-dmat appscan --config hexarocket-dmat.yaml --out reports/

--out sets the report folder. The default is the current folder.
--debug writes more log lines. Use it when you report a problem.
Press Ctrl+C to stop a scan.

Exit code

0: at least one database or repository was scanned. A failure for one database or one repository is written in the report, and the other scans continue.
Not 0: all scans failed, or the configuration is not correct. The tool writes the reports before it stops, so the failures can be examined.

5. Database permissions

The tool connects with a read-only user. Before it scans, it checks that the user can read each catalog view that it needs. If a permission is missing, the tool stops for that database and shows the exact GRANT statements to run.

Database	Connect	Read the catalog
Oracle	`GRANT CREATE SESSION TO <user>;`	`GRANT SELECT_CATALOG_ROLE TO <user>;`
SQL Server (2012 or later)	`USE <db>; CREATE USER <user> FOR LOGIN <login>; GRANT CONNECT TO <user>;`	`GRANT VIEW SERVER STATE, VIEW ANY DEFINITION TO [<login>];`
EPAS	(roles can connect by default)	`GRANT pg_read_all_data, pg_monitor TO <user>;`
MySQL / MariaDB	`CREATE USER '<user>'@'%' IDENTIFIED BY '<password>';`	`GRANT SELECT ON <db>.* TO '<user>'@'%'; GRANT PROCESS ON . TO '<user>'@'%';`

6. Upload the reports

The tool writes these files in the report folder:

File	Content	Readable by you?
`report.json.enc`	All results, for HexaCluster	No (encrypted)
`report.xlsx.enc`	The results as a spreadsheet	No (encrypted)
`report.html.enc`	The interactive report	No (encrypted)
`report.summary.html`	A one-page summary (database scan only)	Yes
`report.identifiers.json.enc`, `report.identifiers.xlsx.enc`	The names of all objects and columns (database scan only)	No (encrypted)

The reports are encrypted with a key that only HexaCluster has. Put all files in the report folder into one ZIP file and upload it on the DMAT product page. HexaCluster then gives you the full results.

report.summary.html is not encrypted. Open it in a web browser to see the summary before you upload the files.

CAUTION: The reports can contain false positives: findings that do not need migration work. Thus, the effort in the summary can be different from the real effort. Do not use the summary as the final estimate. Get the reports reviewed by your HexaCluster representative for a correct estimate.

7. Troubleshooting

Message	What to do
`unknown top-level config key(s)` or `has invalid keys`	A setting name is wrong. Compare it with `hexarocket-dmat.yaml.example`.
`PreCheck failed for database ...`	Run the `GRANT` statements that the message shows, then run the scan again.
`ORA-01045` or `Login failed`	The user cannot connect. Give the connect permission (section 5).
`db_url password contains unencoded special characters`	Percent-encode the password (section 3).
`SQL Server 2008/R2 is not supported`	Scan a SQL Server 2012 or later instance.
`at least one repository is required`	The `appscan:` section has no `repositories:`, or a key name is misspelled.
Files skipped because of their size	Add `max_file_size_kb: 10240` under `appscan:` (the default is 5120).
The tool does not start after a date	The tool has expired. Ask HexaCluster for a new build.

Support

Contact your HexaCluster representative. Send the command that you ran, the full log output (run again with --debug) and your configuration file with the passwords removed.