Fixing Git Database File Locking Issues in .NET Core Projects

Problem Description

When working with SQLite databases in .NET Core applications, you may encounter Git errors where database files cannot be unlinked:

error: unable to unlink old 'CDISV2Core/CDISV2Core.db': Invalid argument
error: unable to unlink old 'CDISV2Core/CDISV2Core.db-shm': Invalid argument  
error: unable to unlink old 'CDISV2Core/CDISV2Core.db-wal': Invalid argument
fatal: Could not reset index file to revision 'HEAD'.

Root Cause

This occurs when:

• SQLite database files are locked by running application processes
• Multiple instances of the application are running
• Visual Studio or other development tools have the database open
• The application crashed and left orphaned processes

SQLite creates these files:

• .db – Main database file
• .db-shm – Shared memory file
• .db-wal – Write-ahead log file

Solution Steps

1. Identify Running Processes

Check for running application processes:

# Check for your specific application
tasklist | Select-String "CDISV2Core"

# Check for dotnet processes
tasklist | Select-String "dotnet"

2. Terminate Locking Processes

Force kill the application processes:

# Kill specific application processes
taskkill /F /IM "CDISV2Core.exe"

# If needed, kill specific dotnet processes by PID
taskkill /F /PID <process_id>

3. Restore Git State

Once processes are terminated, restore the files:

# Check Git status
git status

# Restore the database files
git restore CDISV2Core/CDISV2Core.db CDISV2Core/CDISV2Core.db-shm CDISV2Core/CDISV2Core.db-wal

# Verify clean state
git status

4. Prevention – Update .gitignore

Add SQLite files to .gitignore to prevent tracking:

# SQLite database files
*.db
*.db-shm
*.db-wal
*.sqlite
*.sqlite3

Best Practices

Development Workflow

• Always stop the application before Git operations
• Use dotnet run instead of running multiple instances
• Close Visual Studio database connections when not needed

Database Management

• Use test databases for development (as per project rules)
• Delete migrations when modifying models in development
• Use InitialSeed.sql for database seeding

Debugging Tips

• Check Task Manager for orphaned processes
• Restart Visual Studio if database connections persist
• Use lsof (Linux/Mac) or handle (Windows) to identify file handles

Project-Specific Notes

Based on our project rules:

• Models in CDISV2Core\Models1 are scaffolded/DB-generated – don’t modify
• We use a test database for development
• Delete all migrations when modifying models
• Run builds periodically to check progress
• Update documentation to track progress and avoid repeating mistakes

Common Scenarios

Scenario 1: Multiple Debug Sessions

When debugging in Visual Studio, multiple instances may start. Always check for multiple processes.

Scenario 2: Application Crash

If the application crashes, processes may remain running in the background.

Scenario 3: Database Browser Tools

Database management tools can lock files. Close them before Git operations.

Troubleshooting Commands

# List all processes with database file handles (Windows)
handle.exe CDISV2Core.db

# Force unlock files (if handle.exe available)
handle.exe -c <handle_id> -p <process_id>

# Alternative: Restart machine (nuclear option)
shutdown /r /t 0

Verification

After applying the fix:

1. git status should show “working tree clean”
2. No CDISV2Core processes in Task Manager
3. Database files should not appear in Git changes
4. Application should start normally

Related Issues

• Path errors when debugging in Visual Studio
• Database migration conflicts
• File permission issues on Windows

This fix ensures smooth Git operations while maintaining database functionality for .NET Core development with SQLite.