Deploy and schema updates for testing

server/migrations/0001_scrape_cache_and_state.sql

@@ -1,18 +1,32 @@
 --
 -- Scrape cache + per-attachment scrape lifecycle.
 --
--- This file is the human-readable record. It is NOT applied by hand: the same
--- statements live in server/helpers/Schema.js and are applied idempotently at
--- boot after an information_schema existence check, so dev and prod converge
--- without a migration runner.
+-- HOW THIS IS APPLIED
 --
--- Portability: dev is MariaDB 11.4, prod is MySQL 8. Nothing here may use
--- ADD COLUMN IF NOT EXISTS (MariaDB-only).
+--   ./applyScrapeSchema.sh      (from the repo root, as an admin)
+--
+-- Run it once per environment. The application does NOT apply this itself:
+-- production connects as a least-privilege `app` user with DML rights only, and
+-- deliberately holds no CREATE/ALTER. server/helpers/Schema.js only *verifies*
+-- that these objects exist and that the required privileges are held; if they
+-- are missing it disables link previews and logs the remedy.
+--
+-- Safe to re-run: every statement is conditional.
+--
+-- Portability: dev and production are both MariaDB 11.4, so ADD COLUMN IF NOT
+-- EXISTS and CREATE INDEX IF NOT EXISTS are available. If this project ever
+-- moves to MySQL 8 these become invalid and need information_schema guards
+-- instead.
 --
 
--- One row per URL, shared across users and notes. url_hash carries the UNIQUE
--- index because a UNIQUE on varchar(1000) utf8mb4 is 4000 bytes and exceeds
--- InnoDB's 3072-byte key limit.
+-- One row per URL, shared across users and notes.
+--
+-- url_hash carries the UNIQUE index because a UNIQUE on varchar(1000) utf8mb4
+-- is 4000 bytes and exceeds InnoDB's 3072-byte key limit. `url` is kept
+-- human-readable for debugging only.
+--
+-- COLLATE is stated explicitly to match the existing tables (utf8mb4_general_ci)
+-- rather than inheriting whatever the server default happens to be.
 CREATE TABLE IF NOT EXISTS `scrape_cache` (
   `id`            int(10) unsigned NOT NULL AUTO_INCREMENT,
   `url_hash`      char(64) NOT NULL,
@@ -38,14 +52,16 @@ CREATE TABLE IF NOT EXISTS `scrape_cache` (
   UNIQUE KEY `scrape_cache_url_hash` (`url_hash`),
   KEY `scrape_cache_expires_at` (`expires_at`),
   KEY `scrape_cache_fetch_state` (`fetch_state`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
 
--- Per-attachment lifecycle, so an in-memory queue survives a restart.
+-- Per-attachment lifecycle, so the in-memory scrape queue survives a restart.
 --
 -- scrape_state: 0 = pending, 1 = fetching, 2 = done, 3 = failed.
--- DEFAULT 2 is load-bearing: it keeps the ~2200 pre-existing rows out of the
--- recovery sweep on first boot.
-ALTER TABLE `attachment` ADD COLUMN `scrape_state`    tinyint(4) NOT NULL DEFAULT 2;
-ALTER TABLE `attachment` ADD COLUMN `scrape_attempts` tinyint(4) NOT NULL DEFAULT 0;
-ALTER TABLE `attachment` ADD COLUMN `enqueued_at`     int(11) DEFAULT NULL;
-ALTER TABLE `attachment` ADD KEY `attachment_scrape_state` (`scrape_state`, `enqueued_at`);
+--
+-- DEFAULT 2 is load-bearing: it keeps every pre-existing attachment row
+-- (~2200 in production) out of the boot recovery sweep.
+ALTER TABLE `attachment` ADD COLUMN IF NOT EXISTS `scrape_state`    tinyint(4) NOT NULL DEFAULT 2;
+ALTER TABLE `attachment` ADD COLUMN IF NOT EXISTS `scrape_attempts` tinyint(4) NOT NULL DEFAULT 0;
+ALTER TABLE `attachment` ADD COLUMN IF NOT EXISTS `enqueued_at`     int(11) DEFAULT NULL;
+
+CREATE INDEX IF NOT EXISTS `attachment_scrape_state` ON `attachment` (`scrape_state`, `enqueued_at`);