[mig/maintainability] add some detail comments to migration files

trifid-api/migrations/20230204174853_create_users.sql

@@ -17,10 +17,10 @@
 CREATE TABLE users (
     id SERIAL NOT NULL PRIMARY KEY,
     email VARCHAR(320) NOT NULL UNIQUE,
-    created_on INTEGER NOT NULL,
+    created_on INTEGER NOT NULL,            -- Unix (seconds) timestamp of user creation
 
-    banned INTEGER NOT NULL,
-    ban_reason VARCHAR(1024) NOT NULL,
+    banned INTEGER NOT NULL,                -- Is the user banned? 1=Yes 0=No
+    ban_reason VARCHAR(1024) NOT NULL,      -- What is the reason for this user's ban?
 
     totp_secret VARCHAR(128) NOT NULL,
     totp_verified INTEGER NOT NULL,

trifid-api/migrations/20230204185754_magic_links.sql

@@ -17,5 +17,5 @@
 CREATE TABLE magic_links (
     id VARCHAR(39) NOT NULL PRIMARY KEY UNIQUE,
     user_id SERIAL NOT NULL REFERENCES users(id),
-    expires_on INTEGER NOT NULL
+    expires_on INTEGER NOT NULL                     -- Unix (seconds) timestamp of when this link expires
 );

trifid-api/migrations/20230206012409_create_session_tokens.sql

@@ -17,5 +17,5 @@
 CREATE TABLE session_tokens (
     id VARCHAR(39) NOT NULL PRIMARY KEY,
     user_id SERIAL NOT NULL REFERENCES users(id),
-    expires_on INTEGER NOT NULL
+    expires_on INTEGER NOT NULL                     -- Unix (seconds) timestamp of when this session expires
 );

trifid-api/migrations/20230207145453_create_totp_tokens.sql

@@ -16,7 +16,7 @@
 
 CREATE TABLE totp_create_tokens (
     id VARCHAR(41) NOT NULL PRIMARY KEY,
-    expires_on INTEGER NOT NULL,
+    expires_on INTEGER NOT NULL,            -- The unix (seconds) timestamp of when this TOTP create token expires
     totp_otpurl VARCHAR(3000) NOT NULL,
     totp_secret VARCHAR(128) NOT NULL
 );

trifid-api/migrations/20230224000741_create_orgs.sql

@@ -17,8 +17,8 @@
 CREATE TABLE organizations (
     id SERIAL NOT NULL PRIMARY KEY,
     owner SERIAL NOT NULL REFERENCES users(id),
-    ca_key VARCHAR(3072) NOT NULL,
-    ca_crt VARCHAR(3072) NOT NULL,
-    iv VARCHAR(128) NOT NULL
+    ca_key VARCHAR(3072) NOT NULL,  -- The hex-encoded ENCRYPTED (see below) concatenation of all CA keys on this org
+    ca_crt VARCHAR(3072) NOT NULL,  -- The concatenation of all CA certificates on this org. This is passed directly to NebulaCAPool
+    iv VARCHAR(128) NOT NULL        -- The 12-byte hex-encoded IV, used to encrypt ca_key with the instance AES key
 );
 CREATE INDEX idx_organizations_owner ON organizations(owner);