hexarocket-dmat: Installation & Usage Guide

hexarocket-dmat is a CLI tool that analyzes database schemas and application source code to identify migration friction points when moving to PostgreSQL.

Supported Databases: hexarocket-dmat supports Oracle and SQL Server as source databases. Each database entry requires an explicit db_type field (e.g., oracle, sqlserver).

Prerequisites
Installation
Quick Start
Configuration
Database Scan
- Required Database Permissions
- Output Formats
Code Scan
- Linking Source Code to Databases
- Filtering Detections
Encrypted Reports & Assisted Review
CLI Reference
Troubleshooting

Prerequisites

Requirement	Details
Database Access	Required for the `dbscan` command. Oracle: read access to metadata views. SQL Server: read access to `sys.*` views and `INFORMATION_SCHEMA`.

No Oracle client libraries are required. hexarocket-dmat ships as a single self-contained binary with no external dependencies.

Installation

Download the latest release for your platform from the HexaCluster product portal: https://products.hexacluster.ai

Linux

chmod +x hexarocket-dmat
./hexarocket-dmat version                  # Verify installation
sudo mv hexarocket-dmat /usr/local/bin/    # Optional: add to PATH

macOS

chmod +x hexarocket-dmat
./hexarocket-dmat version                  # Verify installation
sudo mv hexarocket-dmat /usr/local/bin/    # Optional: add to PATH

If macOS blocks the binary, see macOS Gatekeeper warning in Troubleshooting.

Windows

Extract hexarocket-dmat.exe from the downloaded archive.
Open Command Prompt or PowerShell and navigate to the directory containing the binary.
Verify the installation:

.\hexarocket-dmat.exe version

Optionally add the directory to your system PATH:

Open Start > Settings > System > About > Advanced system settings.
Click Environment Variables.
Under System variables, select Path and click Edit.
Add the directory containing hexarocket-dmat.exe.

Note: On Windows, replace ./hexarocket-dmat with .\hexarocket-dmat.exe in all commands shown in this guide.

Quick Start

Create a hexarocket-dmat.yaml file using the Complete Configuration Reference below. Include only the sections you need.
Fill in your database connection details, db_type, and schemas.

Run:

./hexarocket-dmat dbscan --config hexarocket-dmat.yaml       # Database scan
./hexarocket-dmat appscan --config hexarocket-dmat.yaml   # Source code scan

Reports are written to the reports/ directory by default.

Configuration

All behavior is controlled through a single YAML configuration file. Since only the binary is distributed, use the complete reference below to create your hexarocket-dmat.yaml. You only need to include the sections relevant to the commands you plan to use.

Complete Configuration Reference

# =============================================================================
# HEXAROCKET-DMAT Configuration
# =============================================================================

# ---------------------
# Shared Settings
# ---------------------

# Number of parallel workers for code analysis.
# Set to -1 to use all available CPU cores.
analysis_workers: 16

# Enable debug logging.
debug: false

# ---------------------
# Database Scan (dbscan)
# ---------------------
# Optional: omit this entire section if you only use the appscan command.
dbscan:
  # List of databases to scan.
  # Required fields per database: id, db_type, db_url, schemas (at least one).
  databases:
    - id: PROD                                             # Unique label (used in reports and logs)
      db_type: oracle                                      # Database dialect: oracle, sqlserver
      db_url: "oracle://user:password@host1:1521/proddb"   # Oracle connection string
      schemas:
        - SCHEMA1
        - SCHEMA2
    - id: MSSQL_DEV
      db_type: sqlserver
      db_url: "sqlserver://user:password@host2:1433?database=devdb"
      schemas:
        - dbo
        - app

  # Number of database objects to fetch per SQL query batch.
  # Set to -1 for unlimited (fetch all at once).
  fetch_batch_size: 1000

  # Maximum number of databases to scan in parallel.
  # Set to -1 to scan all databases concurrently.
  max_concurrent_dbs: -1

  # Maximum number of schemas to process in parallel per database.
  # Set to -1 to process all schemas concurrently.
  max_concurrent_schemas: -1

  # Oracle metadata view prefix: DBA, ALL, or USER.
  # Controls which set of Oracle dictionary views are queried.
  view_prefix: DBA

  # Schema validation behavior:
  # - true: fail this database if any configured schema is missing
  # - false: continue scan and report schema existence in outputs
  verify_schema_strict: false

  # Extract function/procedure signatures with argument details.
  extract_callable_signatures: true

  # Extract database-level insights (version, storage metrics, data types,
  # partitions, redo log configuration, etc.).
  extract_database_insights: true

  # Output report formats: html, xlsx, json, summary_html
  output_formats:
    - html
    - xlsx
    - json
    - summary_html

  # Output filename template.
  # Placeholders: {DB} = database ID, {DATETIME} = current timestamp.
  outputfile_basename: "reports/HEXAROCKET_DMAT_{DB}_{DATETIME}"

# ---------------------------
# Source Code Scan (appscan)
# ---------------------------
# Optional: omit this entire section if you only use the dbscan command.
appscan:
  # Global includes (apply to ALL source roots).
  global_includes:
    # File patterns to scan. If empty, all files are included.
    patterns:
      - "*.sql"
      - "*.pkb"
      - "*.pks"
    # categories and detection_ids are available for internal/advanced use.
    # categories: []
    # detection_ids: []

  # Global excludes (apply to ALL source roots).
  global_excludes:
    # File path patterns to skip (glob or substring matching).
    patterns:
      - "test"
      - "*_test.sql"
    # categories and detection_ids are available for internal/advanced use.
    # categories: []
    # detection_ids: []

  # Optional: databases for DB object usage mapping.
  # When configured, appscan matches source code references against the database
  # object catalog and reports usage status (direct, dependency, unused).
  databases:
    - id: APPDB
      db_type: oracle
      db_url: "oracle://user:password@host:1521/appdb"
      schemas:
        - SCHEMA1
        - SCHEMA2

  # List of source code directories to scan.
  # Required fields per root: id, path.
  source_roots:
    - id: backend
      path: ./src/backend
      # Link this root to database(s) for DB object usage analysis.
      db_ids:
        - APPDB
      # Root-level includes (merged with global by default).
      includes:
        patterns: []
        # categories: []        # Internal use
        # detection_ids: []     # Internal use
      # Root-level excludes (merged with global by default).
      excludes:
        patterns:
          - "generated"
        # categories: []        # Internal use
        # detection_ids: []     # Internal use
      # false = merge root filters with global filters (additive)
      # true  = use only root-level filters, ignore global
      override_global: false
    - id: database
      path: ./db/scripts
      # No root-level overrides -- uses global filters only.

  # Maximum number of source roots to scan in parallel.
  # Set to -1 to scan all roots concurrently.
  max_concurrent_roots: -1

  # Maximum number of files to process in parallel per source root.
  max_concurrent_files: 100

  # Skip files larger than this size (in KB).
  max_file_size_kb: 512

  # Source for Oracle built-in definitions: "static" (embedded) or "database".
  # "static" allows fully offline scanning with no database connection.
  builtin_source: static

  # Schema validation behavior for linked databases:
  # - true: fail root processing when any mapped DB has missing schemas
  # - false: continue and include schema checks in report output
  verify_schema_strict: false

  # Enable scanning for Oracle reserved words and pseudo-columns.
  scan_keywords: true

  # Enable scanning for Oracle built-in functions (STANDARD + DBMS/UTL packages).
  scan_builtin_functions: true

  # Resolve transitive dependencies using DBA_DEPENDENCIES.
  # When true, objects not directly referenced but depended upon by referenced
  # objects are reported as "dependency" usage.
  resolve_dependencies: false

  # Enable content-aware parsing for XML/HTML files.
  # Extracts text content and attributes for analysis instead of raw markup.
  markup_content_parsing_enabled: true

  # Output report formats: xlsx, json
  output_formats:
    - xlsx
    - json

  # Output filename template.
  # Placeholders: {ROOT} = source root ID, {DATETIME} = current timestamp.
  outputfile_basename: "reports/HEXAROCKET_DMAT_APPSCAN_{ROOT}_{DATETIME}"

Shared Settings

Key	Default	Description
`analysis_workers`	`16`	Number of parallel workers for code analysis. `-1` = all CPU cores.
`debug`	`false`	Enable debug logging (also available as `--debug` CLI flag).

DBScan Configuration

Key	Default	Description
`dbscan.databases`	—	List of databases to scan. Each entry requires `id`, `db_type`, `db_url`, and `schemas`.
`dbscan.databases[].id`	—	Unique label for the database (used in reports and logs).
`dbscan.databases[].db_type`	—	Required. Database dialect: `oracle` or `sqlserver`.
`dbscan.databases[].db_url`	—	Connection string. Oracle: `oracle://user:pass@host:port/service`. SQL Server: `sqlserver://user:pass@host:port?database=db`.
`dbscan.databases[].schemas`	—	List of schema names to scan in this database.
`dbscan.fetch_batch_size`	`1000`	Number of objects fetched per SQL query batch. `-1` = unlimited.
`dbscan.max_concurrent_dbs`	`-1`	Maximum databases scanned in parallel. `-1` = all.
`dbscan.max_concurrent_schemas`	`-1`	Maximum schemas processed in parallel per database. `-1` = all.
`dbscan.view_prefix`	`DBA`	Oracle metadata view prefix: `DBA`, `ALL`, or `USER`.
`dbscan.verify_schema_strict`	`false`	`true` = fail on missing schemas; `false` = continue and report.
`dbscan.extract_callable_signatures`	`true`	Extract function/procedure signatures with argument details.
`dbscan.extract_database_insights`	`true`	Extract database-level insights (version, storage, data types, partitions, etc.).
`dbscan.output_formats`	`[html, xlsx, json, summary_html]`	Report formats to generate.
`dbscan.outputfile_basename`	`reports/HEXAROCKET_DMAT_{DB}_{DATETIME}`	Output filename template. Placeholders: `{DB}`, `{DATETIME}`.

AppScan Configuration

Key	Default	Description
`appscan.global_includes.patterns`	`[]`	File patterns to scan across all roots. Empty = all files.
`appscan.global_excludes.patterns`	`[]`	File path patterns to skip across all roots.
`appscan.databases`	`[]`	Optional databases for DB object usage mapping. Same structure as scan databases.
`appscan.source_roots`	—	List of source directories to scan. Each entry requires `id` and `path`.
`appscan.source_roots[].id`	—	Unique label for the source root.
`appscan.source_roots[].path`	—	Path to the source code directory.
`appscan.source_roots[].db_ids`	`[]`	Link this root to database(s) for DB object usage analysis.
`appscan.source_roots[].includes`	`{}`	Root-level include filters (merged with global by default).
`appscan.source_roots[].excludes`	`{}`	Root-level exclude filters (merged with global by default).
`appscan.source_roots[].override_global`	`false`	`true` = ignore global filters; `false` = merge with global.
`appscan.max_concurrent_roots`	`-1`	Maximum source roots scanned in parallel. `-1` = all.
`appscan.max_concurrent_files`	`100`	Maximum files processed in parallel per source root.
`appscan.max_file_size_kb`	`512`	Skip files larger than this size (KB).
`appscan.builtin_source`	`static`	Source for Oracle built-in definitions: `static` (offline) or `database`.
`appscan.verify_schema_strict`	`false`	`true` = fail on missing schemas; `false` = continue and report.
`appscan.scan_keywords`	`true`	Scan for Oracle reserved words and pseudo-columns.
`appscan.scan_builtin_functions`	`true`	Scan for Oracle built-in functions (STANDARD + DBMS/UTL packages).
`appscan.resolve_dependencies`	`false`	Resolve transitive dependencies via `DBA_DEPENDENCIES`.
`appscan.markup_content_parsing_enabled`	`true`	Content-aware parsing for XML/HTML files.
`appscan.output_formats`	`[xlsx, json]`	Report formats to generate.
`appscan.outputfile_basename`	`reports/HEXAROCKET_DMAT_APPSCAN_{ROOT}_{DATETIME}`	Output filename template. Placeholders: `{ROOT}`, `{DATETIME}`.

Database Scan

The dbscan command connects to databases (Oracle or SQL Server) and analyzes specified schemas. It:

Inventories database objects -- tables, views, procedures, functions, packages, triggers, sequences, types, synonyms, and more.
Analyzes source code -- examines stored procedures, functions, packages/modules, triggers, and views line by line.
Detects migration friction points -- identifies dialect-specific patterns organized into categories (e.g., PL/SQL Features, T-SQL Features, Data Types, Transaction Management, Architecture).

./hexarocket-dmat dbscan --config hexarocket-dmat.yaml

Required Database Permissions

The view_prefix setting controls which Oracle metadata views are queried:

`view_prefix`	Views Queried	Permissions Required
`DBA`	`DBA_OBJECTS`, `DBA_SOURCE`, etc.	`SELECT_CATALOG_ROLE` or `SELECT ANY DICTIONARY`
`ALL`	`ALL_OBJECTS`, `ALL_SOURCE`, etc.	Default grants (objects accessible to the user)
`USER`	`USER_OBJECTS`, `USER_SOURCE`, etc.	No special grants (user's own objects only)

Scan Output Formats

Reports are written to the path defined by outputfile_basename ({DB} = database ID, {DATETIME} = timestamp).

Format	Description
`html`	Interactive dashboard with charts and filterable detection tables
`summary_html`	Lightweight one-page summary
`xlsx`	Excel workbook with inventory, detections, and statistics
`json`	Machine-readable report (can be aggregated into PostgreSQL)

Code Scan

The appscan command scans local source code files for Oracle-specific patterns without requiring a database connection. Supported file types include .sql, .pkb, .pks, .java, .py, .cs, .sh, .xml, .html, and more.

./hexarocket-dmat appscan --config hexarocket-dmat.yaml

Output formats: xlsx and json (configured via output_formats). The {ROOT} placeholder in outputfile_basename is replaced with the source root ID.

Linking Source Code to Databases

Optionally link source roots to Oracle databases to enable database object usage analysis. Configure appscan.databases with your database connections and reference them via db_ids in each source root (see the configuration reference for the full structure).

The report shows each object's usage status: direct (referenced in code), dependency (transitive dependency of a referenced object, requires resolve_dependencies: true), or unused.

Filtering Detections

AppScan supports include/exclude filters at two levels: global_includes/global_excludes (apply to all roots) and per-root includes/excludes. Use patterns to control which files are scanned or skipped. Root-level filters merge with global by default (override_global: false) or replace them (override_global: true).

Note: The categories and detection_ids filter options are reserved for internal use and are not required for standard operation.

Encrypted Reports & Assisted Review

All generated reports are encrypted by default, except for the Summary report (summary_html) which remains unencrypted for quick local review.

To get a detailed assisted review from the HexaCluster team:

Locate your encrypted report files (.enc) in the output directory.
Upload them at https://products.hexacluster.ai/products/dmat-download
The HexaCluster team will analyze your reports and schedule a review meeting to walk through the findings and migration recommendations.

Note: Your data is handled securely. Only the HexaCluster team can decrypt the uploaded reports using the corresponding private key.

CLI Reference

All scan and appscan behavior is controlled through the YAML configuration file. The CLI has only two global flags:

Flag	Default	Description
`--config <file>`	`hexarocket-dmat.yaml`	Path to configuration file
`--debug`	`false`	Enable verbose debug logging

Command	Description	Command-specific Flags
`dbscan`	Scan Oracle database schemas	None
`appscan`	Scan source code files	None
`version`	Print version and build info	None

Troubleshooting

"no databases configured" -- Add at least one entry under dbscan.databases with id, db_type, db_url, and schemas.

"no source roots configured" -- Add at least one entry under appscan.source_roots with id and path.

Schema not found warnings -- With verify_schema_strict: false (default), the scan continues and reports schema existence. Set to true to fail on missing schemas.

Connection errors -- Verify db_url format. Oracle: oracle://user:password@host:port/service_name. SQL Server: sqlserver://user:password@host:port?database=dbname. Ensure the database is reachable and the user has required permissions.

Performance on large databases -- Increase fetch_batch_size (e.g., 5000 or -1) and set analysis_workers: -1.

Files skipped due to size -- Increase max_file_size_kb.

Debug mode -- Use the --debug flag or set debug: true in the configuration file.

Graceful shutdown -- Ctrl+C / SIGTERM triggers graceful shutdown; in-progress work completes and partial results are written.

Error resilience -- Errors in one database or source root do not affect others. The tool only exits with an error code if all targets fail.

macOS Gatekeeper warning -- macOS may block the binary with a "cannot be opened because it is from an unidentified developer" message. To resolve:

Open System Settings > Privacy & Security.
Under the Security section, click "Allow Anyway" next to the hexarocket-dmat message.
Run the binary again.