---
phase: 14-postgresql-migration
plan: 05
subsystem: database
tags: [sqlite, postgres, migration, data-migration, bun-sqlite]

# Dependency graph
requires:
  - phase: 14-01
    provides: PostgreSQL schema definitions (Drizzle pgTable)
provides:
  - One-time SQLite-to-PostgreSQL data migration script
  - db:migrate-from-sqlite npm script
affects: [14-06, deployment, upgrade-docs]

# Tech tracking
tech-stack:
  added: []
  patterns: [dependency-ordered table migration, unix-to-Date conversion, serial sequence reset]

key-files:
  created:
    - scripts/migrate-sqlite-to-postgres.ts
  modified:
    - package.json

key-decisions:
  - "Used postgres.js unsafe() for sequence reset instead of drizzle-orm sql template (simpler for raw DDL)"
  - "Row-by-row insert for error tracing (per-row catch identifies failing record)"

patterns-established:
  - "Migration scripts live in scripts/ directory"
  - "Type conversion helpers (unixToDate, intToBool) for SQLite-to-Postgres data transforms"

requirements-completed: [DB-04]

# Metrics
duration: 2min
completed: 2026-04-04
---

# Phase 14 Plan 05: SQLite-to-Postgres Migration Script Summary

**One-time data migration script converting all 13 tables from SQLite to PostgreSQL with timestamp/boolean type conversions and serial sequence reset**

## Performance

- **Duration:** 2 min
- **Started:** 2026-04-04T10:26:29Z
- **Completed:** 2026-04-04T10:28:29Z
- **Tasks:** 1
- **Files modified:** 2

## Accomplishments
- Created standalone migration script that reads SQLite and writes to PostgreSQL
- Handles all type conversions: unix epoch integers to Date objects, integer booleans to native booleans
- Migrates tables in FK dependency order (4 waves: no-FK, FK-to-parents, FK-to-intermediates, junction tables)
- Resets all 11 serial sequences after migration to prevent duplicate key errors
- Added `db:migrate-from-sqlite` npm script for easy invocation

## Task Commits

Each task was committed atomically:

1. **Task 1: Create SQLite-to-Postgres migration script** - `b4c3813` (feat)

## Files Created/Modified
- `scripts/migrate-sqlite-to-postgres.ts` - One-time migration script with type conversions and sequence reset
- `package.json` - Added db:migrate-from-sqlite script

## Decisions Made
- Used `postgres.js` `unsafe()` for raw `setval` queries instead of drizzle-orm `sql` template -- simpler for dynamic table name interpolation in DDL
- Row-by-row inserts instead of bulk for better error diagnostics (each failed row logs its ID)

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered
- Biome lint flagged unused `sql` import from drizzle-orm (used `pg.unsafe()` instead) and unnecessary suppression comments -- removed both

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness
- Migration script ready for use during SQLite-to-Postgres upgrade
- Requires DATABASE_URL env var and existing SQLite file
- Can be tested against a dev Postgres instance with `docker compose up`

---
*Phase: 14-postgresql-migration*
*Completed: 2026-04-04*