Skip to main content
This covers common database migration-related problems in Sonamu and how to resolve them.

Checksum File Parsing Error

Symptoms

Running these causes the following error:

Cause

The sonamu.lock file is corrupted. Common causes:
  1. Sync interrupted (Ctrl+C) causing incomplete file save
  2. File is empty or has invalid JSON format
  3. Multiple processes modified the file simultaneously

Solutions

The --force flag removes the existing sonamu.lock and performs a full sync from scratch. This is safe and brings every tracked asset back into a consistent state.

2. Check File Contents

If the file is empty or contains only {}, delete and regenerate.

3. Prevention

  • Wait for sync to complete before interrupting
  • Don’t run pnpm dev in multiple terminals simultaneously

Migration File Conflict

Symptoms

Cause

Multiple migrations created on the same day have duplicate timestamps.

Solutions

1. Manually Rename Files

2. Use Timestamp Format

Sonamu supports YYYYMMDD_HHMMSS format:

Generated Column Error

Symptoms

Cause

This occurs when trying to modify a PostgreSQL Generated Column. Generated Columns are automatically computed from other column values and cannot be modified directly.

Solutions

1. Drop and Recreate Generated Column

2. Modify entity.json

Timestamp Precision Error

Symptoms

Cause

Precision for PostgreSQL timestamp type is not specified, causing mismatch with default value.

Solutions

1. Specify Precision in entity.json

2. Fix in Migration File

Foreign Key Constraint Error

Symptoms

Cause

Attempted to delete or modify a record that is being referenced.

Solutions

1. Use CASCADE Option

2. Fix with Migration

Migration Rollback Failure

Symptoms

Cause

Migration file is missing or has improperly implemented down() function.

Solutions

1. Implement down() Function

2. Complex Migration Rollback

Migration State Mismatch

Symptoms

Or

Causes

  1. Migration file was deleted but record remains in DB
  2. Migrations were applied differently across environments

Solutions

1. Check Migration Table

2. Remove Invalid Records

3. Re-apply Migrations

Migrating from MySQL to PostgreSQL

Symptoms

Various errors when converting existing MySQL-based projects to PostgreSQL

Solutions

1. Change Data Types

2. Change Auto Increment

3. String Types

4. Boolean Type

5. JSON Type