How to Enable and Monitor SBOM Migration in Xray

Use Case

JFrog Xray's SBOM Service manages scan results using an optimized data model for CVE search, SBOM generation, and impact analysis. This migration process transfers existing data to the new model seamlessly and runs in the background once enabled.

📘
This migration process is required only for Self-Hosted deployments.

Workflow Steps

Step 1: Verify Prerequisites

Before enabling the SBOM service, ensure the following requirements are met:

Database: PostgreSQL 10 or later
Disk Space: At least 50% free
Database CPU: Average usage under 60%
Xray Version: 3.131.20 or later
Run the following query to confirm worker configurations:

select convert_from(config, 'UTF8') from configuration where config_id = 'xrayConfig';

Ensure the following worker keys are not set to 0:

sbom_workers, usercatalog_workers, sbom_enricher_workers, sbom_dependencies_workers, sbomimpactanalysis_workers, migrationsbom_workers, and related *_existing_content_workers keys.

Step 2: Enable the SBOM Service

Edit the system.yaml file on all Xray nodes.
Add the following configuration:

sbom:
  enabled: true

Restart all Xray nodes.

Once restarted, the migration begins automatically in the background.

Step 3: Monitor Migration Progress

Check Overall Migration Status Run:

select * from sbom.migration_state;

Or Alternatively Use the Migration Status API endpoint:

curl -H "Authorization: Bearer <access-token>" -X GET "https://<your-jfrog-url>/xray/api/v1/sbomMigration/status"

This query returns:

root_files_to_migrate: total number of root files to migrate
start_time: migration start time
finished_time: completion timestamp (or NULL if ongoing)
finished_state: FinishedSuccessful, StoppedByApi, or NULL
count_all_migration: total files migrated so far
count_failed: failed root files
count_succeeded: successfully migrated root files

Check Status per Root File

For debugging specific files:

select * from sbom.migration;

Each record includes:

root_file_id, status, retries, and last_err
Possible statuses: Success, Fail, InProgress, FailedRetrying, ReadyForRetry

Step 4: Control Migration via API

You can manage the migration process using the following endpoints: All endpoints return HTTP 200 on success.

Action	HTTP Method	Endpoint	Description
Stop Migration	`POST`	/api/v1/sbomMigration/stop	Stops the migration process
Start Migration	`POST`	/api/v1/sbomMigration/start?only_failures=[true\|false]	Restarts the migration process. If `only_failures=true`, only failed root files are retried.
Pause Migration	`POST`	/api/v1/sbomMigration/pause	Pauses the running migration process.
Resume Migration	`POST`	/api/v1/sbomMigration/resume	Resumes a paused migration process.
Migration Status	`GET`	/api/v1/sbomMigration/status	Returns status of SBOM migration

📘
After "Start Migration" or "Resume Migration" endpoints - the Xray service requires a restart for migration to go in effect

Step 5: Troubleshooting

Configuration values are 0 Update the relevant worker counts in the configuration table.

UPDATE configuration SET xrayConfig=<MODIFIED CONFIG>;

Migration is too slow / not using DB resources Increase the number of migrant workers in system.yaml:

server:
  migrationSbomWorkers: 8

Migration too fast / DB overloaded Reduce workers:

server:
  migrationSbomWorkers: 1

Optionally, increase sleep intervals between artifact migrations:

sbom:
  sleepTimeSuccess: 5000000000
  sleepTimeFailed: 5000000000

Once the migration is complete, Xray operates using the new SBOM data model, improving performance for CVE search, dependency tracking, and impact analysis.