HealthLog/scripts/migrate-demo-account.README.md

migrate-demo-account.sh

Copies exactly one user, the demo account named by DEMO_USER_ID, from a source instance's Postgres to the separate Postgres of a demo instance. No other user's rows are transferred under any circumstance.

Review the script first, then run it deliberately. It performs destructive, demo-scoped deletes on the target demo DB, then loads the demo slice from the source. It never writes to the source (read-only).

How it connects

Everything instance-specific comes from the environment:

• DEMO_USER_ID: the user id to copy. PROTECT_USER_ID: an id that must never appear on the target (the operator's own account).
• SRC_SSH and SRC_DB_CONTAINER_PATTERN: the source host's ssh alias and a grep -E pattern for its database container; psql healthlog/healthlog.
• DST_SSH: the target host's ssh alias. The demo Postgres container is not hardcoded: the script resolves it at runtime via docker ps | grep -iE 'postgres|^db-' and aborts if it cannot pick a single match (override with DST_DB_CONTAINER=db-xxxx). Match the demo app's own Postgres, not a docs or landing-page database on the same host.
• The target demo user id is resolved at runtime by username='demo' (it may differ from the source id). The wipe phase is scoped to that resolved id; the load then brings the source row in, so afterwards the target demo user carries the source's canonical id.

Each table is transferred with a scoped, server-side \copy ... TO STDOUT piped host-to-host into \copy ... FROM STDIN, using explicit column lists on both ends so secret columns can be NULLed and column order is pinned.

What moves (FK-parent-first, 20 tables)

#	Table	Scope predicate
1	users	id = demo (the one row; secrets NULLed, role='ADMIN')
2	measurements	user_id = demo AND deleted_at IS NULL (incl. RECOVERY/STRAIN/STRESS_SCORE rows)
3	cycle_profiles	user_id = demo
4	menstrual_cycles	user_id = demo
5	cycle_day_logs	user_id = demo (encrypted cols NULLed)
6	cycle_symptom_links	day_log_id IN (demo's day logs)
7	mood_entries	user_id = demo AND deleted_at IS NULL
8	mood_entry_tag_links	mood_entry_id IN (demo's entries) — global tags only
9	medications	user_id = demo
10	medication_schedules	medication_id IN (demo's meds)
11	medication_intake_events	user_id = demo AND deleted_at IS NULL
12	medication_dose_changes	medication_id IN (demo's meds)
13	medication_inventory_items	user_id = demo
14	medication_inventory_events	medication_id IN (demo's meds)
15	medication_side_effects	user_id = demo
16	reminder_phase_configs	medication_id IN (demo's meds)
17	personal_records	user_id = demo
18	user_achievements	user_id = demo
19	consent_receipts	user_id = demo (carries the ai_full consent)
20	audit_logs	user_id = demo AND action LIKE 'insights.%' (plaintext AI assessments)

Secret / credential columns NULLed on the users row

codex_access_token_encrypted, codex_refresh_token_encrypted, codex_token_expires_at, codex_connected_at (and codex_connection_status reset to 'disconnected'), ai_anthropic_key_encrypted, ai_local_key_encrypted, ai_openai_key_encrypted, withings_client_id_encrypted, withings_client_secret_encrypted, whoop_client_id_encrypted, whoop_client_secret_encrypted, fitbit_client_id_encrypted, fitbit_client_secret_encrypted, telegram_bot_token, telegram_chat_id, insurance_number_encrypted, insurer_name, insurer_ik_number.

Forced flags: telegram_enabled=false, role='ADMIN'.

Overwritten: password_hash. The row arrives carrying the source account's hash, and the load is immediately followed by an UPDATE that sets the Argon2id hash of the demo password the README publishes, then asserts the stored value matches it byte for byte and aborts if it does not. The source is the operator's own instance, so its demo password can be rotated at any time; carrying that hash across is what silently broke the advertised demo login in issue #805. The statement travels on psql's stdin, never inside the ssh command string, because the hash contains $argon2id / $v / $m / $t / $p segments that a remote shell would expand to nothing.

Kept: avatar_bytes / avatar_content_type / avatar_updated_at (profile photo), and all display / preference / layout JSON (thresholds_json, dashboard_widgets_json, insights_layout_json, coach_prefs_json, source_priority_json, doctor_report_prefs_json, notification_prefs, healthkit_config_json, unit prefs, height_cm, gender, timezone, locale, date_of_birth, display_name, onboarding state, research-mode acknowledgement).

What is excluded — and why

• Auth / device / push (sessions, passkeys, auth_challenges, api_tokens, refresh_tokens, devices, push_subscriptions, push_attempts, notification_channels, notification_preferences) — per-environment, never portable.
• Integration / OAuth (withings/whoop/fitbit connections, all *_oauth_states / *_connect_tickets, telegram scheduled-deletions + reminder messages, clinician_share_links, provider_health) — tied to live credentials.
• Encrypted-at-rest payloads the target cannot decrypt: insight_narratives and all coach_* (coach_conversations, coach_messages, coach_facts, coach_usage). The target does not hold the source's encryption key, so the AES-256-GCM ciphertext would be unreadable. The same reason drives NULLing cycle_day_logs.sensitive_encrypted / notes_encrypted while still carrying that table's plaintext cycle fields. The plaintext AI assessment text is preserved through the insights.% audit_logs rows (the text lives in the details JSON) instead.
• Transient / regenerable: idempotency_keys, rate_limits, data_backups, import_jobs, host_metrics, feedback, recommendation_feedback, and all rollup tables (measurement_rollups, mood_entry_rollups, strain_trimp_cache, cycle_predictions) — these rebuild on the target.
• No rows: workouts / workout_routes / workout_samples (demo has none).
• Instance / global: app_settings; global catalogues (mood_tags, cycle_symptoms) pre-exist on the target and the carried link rows reference the global ids only.

Encryption note

The demo instance is assumed not to share the source's encryption key. Every column whose value is AES-256-GCM ciphertext under the source key is either NULLed (secrets on users, cycle_day_logs.*_encrypted) or skipped entirely (insight_narratives, coach_messages.encryptedContent). Carrying that ciphertext would produce undecryptable rows that the app's fail-closed loader would reject.

role = ADMIN + DEMO_MODE expectations

The demo user is loaded with role='ADMIN' so the admin surfaces are viewable in the demo. This is only safe because DEMO_MODE must stay ON on the target: the proxy layer (src/proxy.ts) blocks every mutating request in demo mode, so an admin demo session can browse admin pages but cannot change anything. If DEMO_MODE were ever off on the target, this admin demo account would be a write-capable admin. Keep DEMO_MODE enabled.

Safety mechanisms built into the script

• set -euo pipefail and ON_ERROR_STOP=1 on every psql call.
• Pre-flight guard (source): for each carried set, a query that must return 0 foreign-owned rows — aborts on any non-zero. Includes a check that the demo owns 0 custom mood_tags (so every carried mood_entry_tag_link points at a global tag that pre-exists on the target) plus a defensive "non-global tag" link count.
• Scoped wipe-first (target): FK-child-first deletes, every one scoped to the runtime-resolved target demo id. No unscoped delete anywhere. Refuses to proceed if username='demo' on the target resolves to the operator id.
• Post-load verification (target): per-table demo row counts; a hard assertion that PROTECT_USER_ID appears in zero rows; a check that user_id-bearing carried tables hold only the demo id; and a confirmation the demo user exists with role=ADMIN.

Caveats / things to confirm before running

• FOREIGN_HITS assertion counts all non-demo rows in the carried tables on the target, not just what this run inserted. On a clean single-demo-user DB it is 0. If the target legitimately hosts other demo-only accounts, treat a non-zero value as a warning to inspect, not an automatic failure (the script prints it as a WARNING, not an abort).
• Confirm the target's psql credentials are healthlog/healthlog (the script verifies connectivity before any write; adjust PG_USER / PG_DB if the demo Postgres resource uses different ones).
• The script assumes the target's schema is at the same (or a compatible) Prisma migration level as the source. A column present on the source but missing on the target fails the \copy loudly rather than silently corrupting data; run migrations on the target first if the two have drifted.