-- @database: main
--
-- Adds the country of the address a session was opened from.
--
-- Resolved ONCE at session creation (from the full address, before
-- IpAnonymizer masks it for storage) rather than looked up on every display:
-- one lookup instead of one per read, and the value stays correct even after
-- the geolocation database is refreshed underneath it.
--
-- It also opens the door to dropping `ip_address` entirely later on: the
-- country is what a user actually needs to recognise a session ("connexion
-- depuis la France"), without keeping the address that identifies the network.
--
-- NULL means "unknown", never "not applicable": sessions created before this
-- migration, addresses absent from the database, or a server where the MMDB
-- file is not deployed. `bin/session-country-backfill.php` fills the existing
-- rows from the masked addresses already stored.

ALTER TABLE `user_session`
    ADD COLUMN `country` CHAR(2) NULL DEFAULT NULL COMMENT 'ISO 3166-1 alpha-2, resolved at creation' AFTER `ip_address`;
