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

> Migrate existing data to AiToEarn effortlessly with TypeORM SQLite. Auto-upgrades ensure data persistence across schema changes when your Electron client starts. No manual scripting needed.

- Repository: [yikart/AiToEarn](https://github.com/yikart/AiToEarn)
- Tags: migration-guide
- Published: 2026-05-12

---

**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/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:

```typescript
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`](https://github.com/yikart/AiToEarn/blob/main/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:

```bash
cd project/aitoearn-electron
pnpm install
pnpm build

```

Missing migration files (such as [[`1707791500-InitialMigration.ts`](https://github.com/yikart/AiToEarn/blob/main/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/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:

```bash
pnpm nx serve aitoearn-electron

```

When the `createConnection` function runs in [`electron/db/index.ts`](https://github.com/yikart/AiToEarn/blob/main/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:

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

```

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

```typescript
// 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:

```bash
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`](https://github.com/yikart/AiToEarn/blob/main/1707791500-InitialMigration.ts), which creates core tables including `user`, `account`, `pubRecord`, `video`, `account_stats`, and `video_stats`.

Subsequent migrations like [`1707801786-AddAccountStatus.ts`](https://github.com/yikart/AiToEarn/blob/main/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:

```bash
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:

```bash
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`](https://github.com/yikart/AiToEarn/blob/main/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.