How to Migrate Existing Data to AiToEarn: Complete TypeORM SQLite Guide

AiToEarn automatically upgrades existing SQLite databases using TypeORM migrations that execute when the Electron client starts, ensuring your data persists across schema changes without manual SQL scripting.

AiToEarn is an open-source Electron application that stores persistent data in a local SQLite database managed by TypeORM. When you migrate existing data to AiToEarn, the built-in migration system handles all schema updates automatically, bringing your database from any previous state to the current version while preserving your historic records.

Understanding AiToEarn's Database Architecture

The application stores all persistent data in a local SQLite file within the Electron client (project/aitoearn-electron). The database connection is initialized in [electron/db/index.ts](https://github.com/yikart/AiToEarn/blob/main/project/aitoearn-electron/electron/db/index.ts), where TypeORM is configured to automatically execute pending migrations on startup:

migrations: Object.values(migrations),
migrationsRun: true,

This configuration ensures that whenever you start the application with an existing database file, TypeORM checks against the hidden migrations table and applies any pending schema changes before the UI initializes.

Step-by-Step Migration Process

Migrating existing data requires placing your SQLite file in the correct location and letting TypeORM handle the schema updates. Follow these steps to ensure a safe migration.

Backup Your Current Database

Before migrating, create a copy of your existing db.sqlite file (or whatever filename your current database uses). This guarantees you can roll back if a migration fails or produces unexpected results.

Place the Database File

Move your backup file to the path expected by the AiToEarn Electron client. By default, the application looks for the database at electron/db/data.db, though this path is configurable in the connection settings within electron/db/index.ts.

Verify Migration Files

Ensure all migration classes are present in project/aitoearn-electron/electron/db/migrations/. Run the following commands in the Electron workspace to compile the latest migrations:

cd project/aitoearn-electron
pnpm install
pnpm build

Missing migration files (such as [1707791500-InitialMigration.ts](https://github.com/yikart/AiToEarn/blob/main/project/aitoearn-electron/electron/db/migrations/1707791500-InitialMigration.ts) or [1707801786-AddAccountStatus.ts](https://github.com/yikart/AiToEarn/blob/main/project/aitoearn-electron/electron/db/migrations/1707801786-AddAccountStatus.ts)) will prevent the automatic migration runner from updating the schema correctly.

Run the Electron Client

Start the application to trigger automatic migration execution:

pnpm nx serve aitoearn-electron

When the createConnection function runs in electron/db/index.ts, TypeORM loads all migrations specified in the migrations array and executes any that haven't been recorded in the database's internal tracking table.

Check Migration Logs

Monitor the console output for migration messages. You should see "Running migration …" for each pending migration, followed by "Migrations complete". This confirms that the schema now matches the current codebase expectations.

Manual Migration Execution (Headless)

If you need to apply migrations without launching the full Electron UI, use the TypeORM CLI through the NX runner:

pnpm nx run aitoearn-electron:run -- --migrationRun

Alternatively, create a standalone TypeScript script that imports the migrations directly:

// scripts/run-migrations.ts
import { createConnection } from 'typeorm';
import * as migrations from '../electron/db/migrations';

async function main() {
  await createConnection({
    type: 'sqlite',
    database: './electron/db/data.db',
    migrations: Object.values(migrations),
    migrationsRun: true,
  });
  console.log('All migrations applied');
}

main().catch(console.error);

Execute the script with:

pnpm ts-node scripts/run-migrations.ts

How TypeORM Migrations Work Internally

Each migration in AiToEarn implements the MigrationInterface and defines two methods: up for applying changes and down for reverting them. The initial schema is defined in 1707791500-InitialMigration.ts, which creates core tables including user, account, pubRecord, video, account_stats, and video_stats.

Subsequent migrations like 1707801786-AddAccountStatus.ts demonstrate how later schema changes (such as adding a status column to the account table) are structured. TypeORM compares the migration class timestamps against entries in the migrations table to determine which up methods need execution.

Verifying Migration Success

After migration, verify your data integrity using the SQLite CLI:

sqlite3 ./electron/db/data.db "SELECT * FROM migrations;"

This displays the migration history showing which versions have been applied. Confirm your historic data survived by querying specific tables:

sqlite3 ./electron/db/data.db "SELECT * FROM user LIMIT 5;"

Summary

• TypeORM manages schema changes through migration classes stored in electron/db/migrations/
• Automatic execution occurs on startup when migrationsRun: true is set in electron/db/index.ts
• Backup first to prevent data loss during the migration process
• Manual execution is possible via NX commands or standalone TypeORM scripts for headless environments
• Verification uses the SQLite CLI to inspect the migrations table and confirm data integrity

Frequently Asked Questions

Can I migrate data from a non-AiToEarn SQLite database?

You can import external SQLite data by placing the file in the expected path, but the schemas must be compatible. If the external database lacks AiToEarn's specific table structures, the migrations will attempt to create them, potentially causing conflicts. Export your data to CSV and import it after letting AiToEarn create a fresh schema, or manually map your existing tables to AiToEarn's expected schema before migration.

What happens if a migration fails during startup?

If a migration fails, TypeORM throws an error and the database connection fails to initialize, preventing the Electron app from fully loading. Check the console logs for the specific SQL error, restore your database from the backup you created earlier, and ensure all migration files are properly compiled and present in the migrations folder.

How do I check which migrations have already been applied?

Query the internal migrations table using the SQLite command line: sqlite3 data.db "SELECT * FROM migrations;". This returns rows containing the migration ID, timestamp, and class name, showing exactly which schema changes have been executed against your database.

Is it safe to downgrade to a previous version of AiToEarn after migrating?

Downgrading is risky because TypeORM does not automatically run down migrations when you switch to older code. The down methods exist in the migration files for rollback purposes, but the application only executes up migrations when migrationsRun: true is set. To downgrade safely, manually run the down migration using the TypeORM CLI or restore your database from a pre-migration backup.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}