Skip to main content

Migration Guide

This guide helps you migrate between different versions of XeroLite and update your configurations accordingly.

Table of Contents​

Upgrading XeroLite​

Understanding XeroLite Database​

XeroLite uses an H2 database file (data.mv.db) to store all your data and settings:

  • Location: The data.mv.db file is created in the root folder of your XeroLite installation when you first start the application
  • Contains ALL Data:
    • ✅ Webhook URL
    • ✅ License key
    • ✅ IP whitelist table
    • ✅ Alert logs (all historical alert records)
    • ✅ Transaction logs (all order transaction history)
    • ✅ Configuration settings
    • ✅ All other application data
  • Purpose: Allows you to retain all your data when upgrading within the same major version. See Database Migration for what migration means.

Database Migration Rules​

✅ Upgrading Within Same Major Version​

When upgrading within the same major version (e.g., 0.3.2 → 0.3.3, or 1.1.0 → 1.1.1 → 1.2.0):

  1. Install New Version

    • Download and extract the new XeroLite version to a new folder
    • Follow the Installation Guide

  2. Copy Database File

    • Locate data.mv.db in your old XeroLite installation folder
    • Copy data.mv.db to the root folder of the new XeroLite installation
    • Important: Copy the file before starting the new version for the first time

  3. Retained Data (ALL Preserved)

    • ✅ Webhook URL (no need to update TradingView alerts)
    • ✅ License key (no need to re-enter)
    • ✅ IP whitelist table (all whitelisted IPs preserved)
    • ✅ Alert logs (complete historical alert records preserved)
    • ✅ Transaction logs (complete order transaction history preserved)
    • ✅ All configuration settings (all preferences and settings preserved)
    • ✅ All other application data (everything in the database is retained)

  4. Launch New Version

    • Start the new XeroLite version
    • Your settings should be preserved automatically

⚠️ Upgrading Across Major Versions (Breaking Changes)​

When upgrading across major versions (e.g., 0.3.x → 1.0.0 Beta / 1.1.0+):

  1. Cannot Use Old Database

    • ❌ The old data.mv.db file is not compatible with the new major version
    • ❌ Database schema changed significantly between major versions
    • ❌ You must install from scratch

  2. Install New Version

    • Download and extract the new XeroLite version
    • Follow the Installation Guide
    • Do NOT copy the old data.mv.db file

  3. New Installation Required - All Data Lost

    • ⚠️ All data will be lost (cannot migrate database)
    • ✅ You will receive a new webhook URL (must update all TradingView alerts)
    • ✅ You must re-enter your license key
    • ✅ You must reconfigure IP whitelist settings
    • ✅ You must reconfigure all other settings
    • ⚠️ Alert logs and transaction history will be lost (fresh start)

  4. Update TradingView Alerts

    • Copy the new webhook URL from XeroLite
    • Update webhook URL in all TradingView alerts
    • Test each alert to verify the new URL works

General Upgrade Steps​

  1. Backup Your Configuration

    • Note your current webhook URL and API key
    • Document any custom IP whitelist settings
    • Save your current alert configurations
    • For same major version upgrades: Locate your data.mv.db file

  2. Download Latest Version

    • Download the latest XeroLite version from XeroLite Downloads & Resources
    • Select the appropriate version for your operating system (Windows or Linux)
    • Ensure compatibility with your operating system

  3. Install New Version

    • Extract the new version to a new folder
    • Follow the Installation Guide
    • For same major version: Copy data.mv.db from old installation before first launch
    • For major version upgrade: Do NOT copy old database, install fresh

  4. Verify Configuration

    • Same major version: Check that your webhook URL, license, alert logs, transaction logs, and all settings are preserved
    • Major version upgrade: Enter new license key and note new webhook URL (all previous data is lost)
    • Verify IP whitelisting settings are intact (or reconfigure if needed)
    • Test connection to Interactive Brokers
    • Same major version: Verify alert logs and transaction history are accessible

  5. Test Alerts

    • Major version upgrade: Update all TradingView alerts with new webhook URL
    • Use paper trading to test your alerts
    • Verify orders are being placed correctly
    • Check alert message formats are compatible

Version-Specific Migration​

Important Version Notes​

  • Version 1.0.0 Beta (2024-12-02): Introduced limit orders, take profit, and stop loss. This was a beta release.
  • Version 1.1.0 (2025-05-23): First stable release with limit orders, stop-loss, and take-profit. Added automatic price rounding.
  • Version 1.2.0 (2025-12-16): Added trailing stop orders.

For production use, we recommend version 1.1.0 or higher.

Migrating to Version 1.2.0​

✅ Same Major Version - Database Migration Supported​

Database Migration:

  • ✅ You can copy data.mv.db from version 1.1.x to version 1.2.0
  • ✅ ALL data will be preserved:
    • Webhook URL
    • License key
    • Alert logs (complete historical records)
    • Transaction logs (complete order history)
    • IP whitelist table (all whitelisted IPs)
    • All configuration settings
  • ✅ No need to update TradingView alerts or re-enter license
  • ✅ Your complete alert and transaction history will be retained

New Features​

  • Trailing Stop Orders: New TRAIL order type with trail_amt field
  • Enhanced Transaction List: Improved parent-child order hierarchy display
  • Pagination: Better performance for alerts and transactions

Breaking Changes​

  • None - backward compatible with v1.1.x

Migration Steps​

  1. Update to XeroLite 1.2.0
  2. Review Alert Request Format v1.2.x for new features
  3. Optional: Update alerts to use new TRAIL order type if needed
  4. See Combo Order Types for trail order details

Alert Format Updates​

If you want to use trailing stops, update your alerts:

{
  "name": "AAPL_Trail",
  "symbol": "AAPL",
  "action": "BUY",
  "qty": "10",
  "order_type": "TRAIL",
  "price": "150.00",
  "trail_amt": "2.00%",
  "currency": "USD",
  "asset_class": "STOCK",
  "exch": "SMART"
}

Migrating to Version 1.1.0​

✅ Same Major Version - Database Migration Supported​

Database Migration:

  • ✅ You can copy data.mv.db from version 1.0.0 Beta to version 1.1.0
  • ✅ ALL data will be preserved:
    • Webhook URL
    • License key
    • Alert logs (complete historical records)
    • Transaction logs (complete order history)
    • IP whitelist table (all whitelisted IPs)
    • All configuration settings
  • ✅ No need to update TradingView alerts or re-enter license
  • ✅ Your complete alert and transaction history will be retained

New Features​

  • Automatic Price Rounding: Prices automatically rounded to IB market rules (new in 1.1.0)
  • Transaction Table: New transaction tracking and logging
  • Alert Request Builder: Enhanced builder tool
  • Stability Improvements: First stable release with limit orders, stop-loss, and take-profit

Breaking Changes​

  • None - backward compatible with v1.0.0 Beta

Migration Steps​

  1. Update to XeroLite 1.1.0 (recommended for production use)
  2. Review Alert Request Format v1.1.x for field details
  3. Optional: Add stop-loss and take-profit to your alerts (available since 1.0.0 Beta)
  4. See Combo Order Types for SL/TP usage

Note: Stop-loss and take-profit were introduced in version 1.0.0 Beta. Version 1.1.0 is the first stable release with these features and includes automatic price rounding.

Alert Format Updates​

Stop-loss and take-profit were introduced in version 1.0.0 Beta. You can add them to your alerts:

{
  "name": "AAPL_Market_SL_TP",
  "symbol": "AAPL",
  "action": "BUY",
  "qty": "10",
  "order_type": "MARKET",
  "price": "150.00",
  "sl_offset": "5%",
  "tp_offset": "10%",
  "currency": "USD",
  "asset_class": "STOCK",
  "exch": "SMART"
}

Migrating from Version 1.0.0 Beta to 1.1.0+​

✅ Same Major Version - Database Migration Supported​

Database Migration:

  • ✅ You can copy data.mv.db from version 1.0.0 Beta to version 1.1.0
  • ✅ ALL data will be preserved:
    • Webhook URL
    • License key
    • Alert logs (complete historical records)
    • Transaction logs (complete order history)
    • IP whitelist table (all whitelisted IPs)
    • All configuration settings
  • ✅ No need to update TradingView alerts or re-enter license
  • ✅ Your complete alert and transaction history will be retained

Key Changes​

  • Price Rounding: Prices are now automatically rounded (no manual adjustment needed)
  • Enhanced Validation: Improved alert message validation
  • Stability Improvements: Version 1.1.0 is the first stable release with limit orders, stop-loss, and take-profit

Migration Steps​

  1. Copy Database File

    • Locate data.mv.db in your version 1.0.0 Beta installation folder
    • Copy it to the root folder of the new version 1.1.0 installation
    • Copy before starting version 1.1.0 for the first time

  2. Update to XeroLite 1.1.0

    • Install version 1.1.0 or later (recommended for production use)
    • Launch XeroLite - your settings should be preserved

  3. No Alert Changes Required

    • No changes required to existing alerts - they will continue to work
    • Optional: Update alerts to use new SL/TP features
    • Remove any manual price rounding logic from your alerts (now automatic)

Note: Version 1.0.0 Beta introduced limit orders, stop-loss, and take-profit. Version 1.1.0 is the first stable release with these features. If you're using 1.0.0 Beta, we strongly recommend upgrading to 1.1.0 or higher for production use.

Migrating from Version 0.3.x to 1.0.0 Beta / 1.1.0+​

⚠️ Major Version Upgrade - Database Migration Required​

Important: This is a major version upgrade with breaking changes. You cannot use your old data.mv.db file.

Database Migration:

  • ❌ Do NOT copy data.mv.db from version 0.3.x to version 1.0.0 Beta / 1.1.0+
  • ✅ Install version 1.0.0 Beta / 1.1.0+ as a fresh installation
  • ✅ You will receive a new webhook URL (must update all TradingView alerts)
  • ✅ You must re-enter your license key
  • ✅ You must reconfigure all settings (IP whitelist, etc.)

Breaking Changes​

The alert request JSON format changed significantly in version 1.0.0 Beta:

Old Field (v0.3.x)New Field (v1.0.0 Beta+)Notes
con_idsymbol + currencyReplaced with symbol and currency
sec_typeasset_classRenamed for clarity
volumeqtyRenamed for consistency

Migration Steps​

  1. Install Fresh Version

    • Install version 1.0.0 Beta or 1.1.0+ as a fresh installation
    • Do NOT copy old data.mv.db file
    • You will receive a new webhook URL
    • Re-enter your license key

  2. Update TradingView Alerts with New Webhook URL

    • Copy the new webhook URL from XeroLite
    • Update webhook URL in all TradingView alerts
    • Test each alert to verify the new URL works

  3. Update Alert Messages

    • Replace con_id with symbol and currency fields
    • Change sec_type to asset_class
    • Change volume to qty

  4. Example Migration

    Old Format (v0.3.x):

    {
      "con_id": 265598,
      "sec_type": "STK",
      "action": "BUY",
      "volume": "10",
      "order_type": "MKT"
    }

    New Format (v1.0.0 Beta+):

    {
      "symbol": "AAPL",
      "currency": "USD",
      "asset_class": "STOCK",
      "action": "BUY",
      "qty": "10",
      "order_type": "MARKET",
      "exch": "SMART"
    }

  5. Update All Alerts

    • Review all TradingView alerts
    • Update alert messages to new format
    • Test each alert in paper trading mode
    • Use Alert Request Builder to generate correct format

  6. Field Mapping Reference

    • con_id → symbol + currency:

      • Old: "con_id": 265598
      • New: "symbol": "AAPL", "currency": "USD"

    • sec_type → asset_class:

      • Old: "sec_type": "STK"
      • New: "asset_class": "STOCK"
      • Common mappings: STK → STOCK, CASH → FOREX, FUT → FUTURE

    • volume → qty:

      • Old: "volume": "10"
      • New: "qty": "10" (same value, different field name)

    • order_type values:

      • Old: "MKT" → New: "MARKET"
      • Old: "LMT" → New: "LIMIT"

  7. Required New Fields

    • exch: Exchange code (e.g., "SMART" for US stocks)
    • Ensure all required fields are present (see Alert Request Format v1.0.x for 1.0.0 Beta format)
    • Recommendation: Use version 1.1.0 or higher for stable production use

Alert Format Version Migration​

Choosing the Right Format Version​

XeroLite supports multiple alert format versions for backward compatibility:

  • v1.2.x: Latest version with trailing stops
  • v1.1.x: Includes stop-loss and take-profit
  • v1.0.x: Modern format with symbol/currency
  • v0.3.x: Legacy format (deprecated)

Migration Strategy​

  1. Identify Current Format

  2. Plan Migration

    • Decide target format version (recommend v1.2.x for new features)
    • List all alerts that need updating
    • Prioritize critical alerts first

  3. Update Alerts Gradually

    • Test one alert at a time
    • Verify order execution in paper trading
    • Update remaining alerts once verified

  4. Use Alert Request Builder

    • Use the Alert Request Builder to generate correct format
    • Ensures all required fields are present
    • Validates JSON syntax

Configuration Migration​

Webhook URL Changes​

When Webhook URL Changes:

  • Major version upgrades (0.3.x → 1.x.x): Webhook URL will change (fresh installation)
  • Same major version upgrades (1.1.0 → 1.1.1 → 1.2.0): Webhook URL is preserved if you copy data.mv.db

If your webhook URL changes after upgrade:

  1. Update TradingView Alerts

    • Copy new webhook URL from XeroLite
    • Update webhook URL in all TradingView alerts
    • Test each alert to verify new URL works

  2. IP Whitelisting

    • Same major version: All IP whitelist settings are preserved if you copy data.mv.db
    • Major version upgrade: You must reconfigure IP whitelist settings (all whitelisted IPs are lost)
    • Add any new IP addresses if needed
    • Test webhook accessibility

  3. Historical Data

    • Same major version: All alert logs and transaction logs are preserved when copying data.mv.db
    • Major version upgrade: All historical alert logs and transaction logs will be lost (fresh start)

TWS API Settings​

After upgrading XeroLite:

  1. Verify TWS API Settings

    • Check that API is still enabled in TWS
    • Verify port settings haven't changed
    • Ensure "Read-Only API" is unchecked if placing orders

  2. Reconnect XeroLite

    • Disconnect and reconnect XeroLite to TWS
    • Verify connection status
    • Test with a paper trading order

Testing After Migration​

Pre-Production Testing​

  1. Paper Trading Test

    • Enable paper trading mode in TWS
    • Test all updated alerts
    • Verify orders are placed correctly
    • Check order parameters match expectations

  2. Validation Checklist

    • ✅ All alerts updated to new format
    • ✅ Webhook URLs updated
    • ✅ IP whitelisting configured
    • ✅ TWS connection verified
    • ✅ Test orders execute successfully
    • ✅ Stop-loss/take-profit work (if using)
    • ✅ Price rounding works correctly

  3. Monitor Initial Trades

    • Watch first few live trades carefully
    • Verify order execution matches alert parameters
    • Check transaction logs for any issues
    • Review Incoming Alerts log for errors

Rollback Plan​

If you encounter issues after migration:

  1. Keep Old Version Available

    • Don't delete old XeroLite installation immediately
    • Keep backup of old alert configurations

  2. Revert Alerts

    • If needed, revert alerts to previous format
    • Restore old webhook URL if changed
    • Contact support for assistance

  3. Contact Support

    • Email: [email protected]
    • Provide version information
    • Describe migration issues encountered

Common Migration Issues​

Issue: Alerts Stop Working After Upgrade​

Solution:

  • Major version upgrade: Ensure you updated webhook URL in all TradingView alerts (new URL is generated)
  • Same major version: Verify you copied data.mv.db correctly to preserve webhook URL
  • Verify alert format matches your XeroLite version
  • Check webhook URL is correct
  • Review Incoming Alerts log for errors
  • Ensure all required fields are present

Issue: License Key Not Working After Upgrade​

Solution:

  • Major version upgrade: You must re-enter your license key (database is not compatible)
  • Same major version: If you copied data.mv.db, license should be preserved. If not, re-enter license key.
  • Verify license key is valid and active
  • Contact support if license issues persist

Issue: Missing Alert Logs or Transaction History After Upgrade​

Solution:

  • Same major version: Ensure you copied data.mv.db before first launch - all historical data should be preserved
  • Major version upgrade: Historical data cannot be migrated - this is expected behavior (fresh installation)
  • If you need historical data from major version upgrade, you must export it before upgrading

Issue: Orders Not Executing​

Solution:

Issue: Price Rounding Errors​

Solution:

  • XeroLite 1.1.0+ handles rounding automatically (introduced in 1.1.0)
  • Version 1.0.0 Beta requires manual price adjustment
  • Remove any manual rounding from alerts if upgrading to 1.1.0+
  • Verify prices are within valid increments
  • See Price Rounding Rules

Need more help? Contact support at [email protected]

See also:

Last Updated: December 2025