Idempotent upsert with ON CONFLICT DO UPDATE so imports can be re-run

# ======================================================================
# Q: Write the upsert so the import can be re-run without duplicate records.
#
# Idempotency rests on a natural key (external_id) with a unique constraint. If
# the job dies midway, I re-run it from the start without harm. The where clause
# prevents an old file from overwriting newer data.
# ======================================================================

from sqlalchemy.dialects.postgresql import insert as pg_insert

def upsert_events(session, rows):
    stmt = pg_insert(Event).values(rows)
    stmt = stmt.on_conflict_do_update(
        index_elements=[Event.external_id],         # unique constraint
        set_={'severity': stmt.excluded.severity,
              'host': stmt.excluded.host,
              'updated_at': func.now()},
        where=Event.occurred_at <= stmt.excluded.occurred_at)  # newer data only
    session.execute(stmt)