elemes/docs/11-database-migration.md

Migrasi Database: CSV → PostgreSQL

Status: SELESAI — live di PostgreSQL (STORAGE_BACKEND=postgresql, cutover Agustus 2026). CSV tetap dipelihara sebagai backup read-only (/app/tokens.csv, mount :ro). Dokumen ini menjelaskan arsitektur, alur migrasi, operasional, dan rollback.

1. Kenapa migrasi?

Penyimpanan lama tokens_siswa.csv (satu baris = satu siswa, satu kolom per lesson):

Masalah	Dampak
read-modify-write dengan file lock	Race condition saat banyak siswa submit bersamaan
Token siswa plaintext di file + bocor ke log & payload report	Kebocoran credential
Tidak ada relasi / constraint	Progress rusak tanpa error
Satu file membesar seiring lesson & siswa	Semakin lambat dibaca setiap request
Role guru = "baris pertama"	Fragile & ambigu

PostgreSQL + SQLAlchemy menyelesaikan semuanya: transaksi ACID, relasi, constraint, index, token hanya disimpan sebagai HMAC-SHA256 digest.

2. Stack

Komponen	Teknologi	Versi (verified)
Database	PostgreSQL	18 (image postgres:18-alpine)
ORM	SQLAlchemy	2.0.51
Migrasi schema	Alembic	1.19.0
Driver	psycopg	3.3.4 (psycopg[binary])
Hashing token	HMAC-SHA256 + pepper (TOKEN_PEPPER)	—

3. Arsitektur

Flask routes (auth, progress, lessons, compile)
        │  (hanya kenal facade)
        ▼
services/token_service.py  ← facade, kontrak publik
        │
        ▼
services/storage/  (dipilih via STORAGE_BACKEND)
   ├── csv_backend.py       → tokens_siswa.csv  (transisi/rollback)
   └── postgres_backend.py  → repositories → SQLAlchemy → PostgreSQL

• services/models.py — users, access_tokens (token_hash unik), lessons (registry metadata), student_progress (unique user+lesson).
• migrations/ — Alembic; 0001_initial_schema.py (hand-written, deterministik).
• services/csv_importer.py — import idempotent CSV → PG (3/4 legacy → state=scored, score_earned=3, score_total=4).
• services/lesson_registry.py — sync daftar lesson dari home.md (lesson hilang → is_active=false, bukan dihapus).

Keamanan token

• Token mentah tidak pernah disimpan: access_tokens.token_hash = HMAC-SHA256(token, TOKEN_PEPPER) — deterministik untuk lookup, tak reversibel.
• Pepper (TOKEN_PEPPER) di .env, di luar database. Hilang = semua token invalid (regenerate & import ulang).
• Report & export tidak menyertakan token mentah; reset guru memakai student_id anonim (user.id di PG, sha256(token) di CSV).

4. Alur migrasi (production)

cd elemes

# 1. Set variabel di ../.env (lihat .env.example):
#    POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD (strong!)
#    DATABASE_URL=postgresql+psycopg://<user>:<pass>@127.0.0.1:5432/<db>
#    TOKEN_PEPPER=<random 48 hex>      # JANGAN hilangkan — hash bergantung padanya
#    STORAGE_BACKEND=csv               # tetap csv selama transisi

# 2. Build ulang image (deps baru: SQLAlchemy, alembic, psycopg) + start postgres
./elemes.sh runclearbuild

# 3. Buat schema + import data (idempotent — aman dijalankan ulang)
./elemes.sh dbupgrade
./elemes.sh synclessons
./elemes.sh dbimport            # lihat laporan
./elemes.sh dbimport --dry-run  # simulasi tanpa menulis

# 4. PARITY CHECK — wajib lulus sebelum cutover
./elemes.sh dbverify

# 5. Cek versi schema & backup pertama
./elemes.sh dbstatus
./elemes.sh dbbackup

# 6. Cutover: ubah STORAGE_BACKEND=postgresql di ../.env, lalu
./elemes.sh run     # restart service dengan backend baru

Setelah cutover, CSV tetap ada di /app/tokens.csv sebagai backup read-only — tapi tidak lagi dibaca oleh aplikasi.

5. Operasional harian

Perintah	Fungsi
./elemes.sh dbupgrade	Jalankan migrasi schema (alembic upgrade head)
./elemes.sh dbstatus	Versi schema aktif & head
./elemes.sh dbimport	Impor/refresh data dari CSV (idempotent)
./elemes.sh synclessons	Sinkronisasi daftar lesson dari home.md
./elemes.sh dbverify	Parity check CSV ↔ PG
./elemes.sh dbbackup	pg_dump → backups/elemes_<ts>.sql
./elemes.sh dbrestore	Restore backup terbaru
./elemes.sh dbexport	Snapshot PG → pg_snapshot.csv (tanpa token)

6. Rollback (kembali ke CSV)

Selama transisi, STORAGE_BACKEND=csv → aplikasi memakai CSV lagi. CSV tidak berubah oleh operasi PG (write PG tidak menyentuh CSV). Catatan: progress yang masuk lewat PG selama periode postgresql tidak otomatis balik ke CSV — jalankan dbexport dulu bila perlu.

7. Load test endpoint database

cd elemes/load-test
python content_parser.py --content-dir ../../content --tokens-file ../../tokens_siswa.csv
locust -f locustfile_db.py    # set host ke URL Elemes

Skenario: login/validate-token, baca lesson, track-progress (siswa), progress-report + export-csv (guru).

8. Test

# Unit & kontrak (host): backend aktif default = csv tanpa DATABASE_URL
PYTHONPATH=services python -m pytest services/tests -q

# Integrasi (butuh DATABASE_URL + postgres hidup): jalankan di container
podman exec -w /app -e PYTHONPATH=services lms-dev_elemes_1 \
  python -m pytest services/tests -q

Suite round-trip siswa (test_student_roundtrip.py, test_repositories.py, test_student_management_routes.py) dijalankan pada DB test terpisah (elemes_test):

podman exec -w /app -e PYTHONPATH=services \
  -e DATABASE_URL="$DATABASE_URL_TEST" \
  lms-dev_elemes_1 python -m pytest services/tests/test_student_roundtrip.py \
    services/tests/test_repositories.py services/tests/test_student_management_routes.py -q

Jangan pernah menjalankan integration test dengan DATABASE_URL produksi — fixture conftest me-TRUNCATE semua tabel sebelum tiap test.

9. Manajemen Siswa: Round-Trip CSV (export → edit → import)

Sejak Agustus 2026, halaman /progress memakai satu format CSV round-trip untuk export dan import siswa, menggantikan rancangan "download template":

student_id;token;nama_siswa;<lesson_slugs...>

Export (POST /students/export-csv, teacher-only)

• Export siswa terpilih bila ada selection; seluruh siswa bila selection kosong. Teacher tidak pernah ikut.
• Kolom token selalu kosong — PostgreSQL hanya menyimpan HMAC-SHA256(token, TOKEN_PEPPER) dan tidak ada recovery/export token.
• Encoding UTF-8 BOM, delimiter ;, filename data_siswa_YYYYMMDD_HHMMSS.csv.
• Duplicate/malformed/unknown/teacher ID pada selection membuat seluruh request gagal.

Import (/students/import/preview & /students/import, teacher-only)

• Create + restore/update, all-or-nothing: seluruh row divalidasi dulu; satu saja baris bermasalah → seluruh file ditolak tanpa write.
• Baris dengan student_id terisi = siswa existing: user wajib sudah ada dan ber-role student. Token boleh kosong (hasil export) → user & token lama dipertahankan, nama & progress diperbarui (restore/update, bukan create). Mengisi token pada baris existing ditolak sebagai konflik/ambigu.
• Baris dengan student_id kosong = siswa baru: token wajib non-kosong; dibuatkan user + access-token digest. student_id terisi yang tidak dikenal ditolak (tidak ada create-with-ID diam-diam); teacher tidak pernah bisa diubah lewat import siswa.
• Setelah siswa dihapus, UUID lama tidak bisa langsung dipakai ulang untuk create (ditolak sebagai ID tak dikenal) — buat baris baru dengan student_id kosong agar UUID baru dibuat server.
• Progress completed/<earned>/<total> diterapkan via set_progress(); not_started/kosong tetap sparse (tidak ada row), dan progress lama yang tidak ada di CSV tidak dihapus (merge, bukan snapshot penuh).
• Upload diproses in-memory; preview/response/log tidak pernah memuat token plaintext maupun hash.
• File CSV berisi token yang diisi guru adalah satu-satunya salinan plaintext token.

Bulk delete (POST /students/bulk-delete, teacher-only)

• Menerima 1–1000 UUID; seluruh target divalidasi sebelum delete pertama (duplicate/malformed/unknown/teacher ID → zero delete).
• Menghapus permanen user + cascade token & progress; lesson tidak terpengaruh.
• Setelah commit, siswa tidak lagi ada; UUID lama tidak bisa dipakai ulang oleh importer (ditolak sebagai ID tak dikenal). Untuk memperbarui nama/progress tanpa menghapus, cukup re-import hasil export (token kosong); untuk menambah siswa baru, gunakan baris dengan student_id kosong.

Berkas kunci

• services/student_roundtrip.py — parser/serializer murni (schema + validasi).
• services/progress_status.py — parse/format status legacy bersama (dipakai importer & postgres_backend agar tidak divergen).
• services/repositories.py — list_students_for_export, preview_student_import, run_student_import, delete_students, create_user(user_id=...).
• routes/student_management.py — 4 endpoint teacher-only (cookie HttpOnly student_token + validasi Origin).
• Frontend: selection berbasis UUID, dialog import preview, dialog bulk delete (src/routes/progress/+page.svelte + komponen di src/lib/components/).

Out of scope: mengganti token siswa existing lewat import, export/recovery token, vault, soft delete, dan import format lama (dbexport/CSV migrasi).

• Kontrak suite (test_token_service_contract.py, test_auth_routes.py, test_progress_routes.py) dijalankan terhadap kedua backend.
• Test integrasi (test_repositories.py, test_csv_importer.py, test_lesson_registry.py) otomatis skip bila DATABASE_URL tidak diset.
• Isolasi antar test (DB bersama): conftest punya fixture autouse yang TRUNCATE semua tabel sebelum tiap test; TOKENS_FILE/CONTENT_DIR di-PAKSA ke fixture (jangan setdefault — env container membawa path produksi). Integration test dijalankan di DB terpisah (mis. elemes_test): CREATE DATABASE + alembic upgrade.
• Script di /app/scripts (dbverify/dbexport) butuh PYTHONPATH=/app (bukan services) agar from services... resolve — sudah di-apply di elemes.sh.