From 3c2db53a2722a695afca1b91c43fa87ee33b25a2 Mon Sep 17 00:00:00 2001 From: Brandon Thomas Date: Tue, 14 Apr 2026 02:40:45 -0400 Subject: [PATCH] migrate tables --- .claude/rules/code-style.md | 6 +++ .../down.sql | 31 +++++++++++++++ .../up.sql | 5 +++ .../down.sql | 5 +++ .../up.sql | 39 +++++++++++++++++++ _database/sql/migrations/CLAUDE.md | 38 ++++++++++++++++++ _database/sql/migrations_squashed/CLAUDE.md | 26 +++++++++++++ .../migrations_squashed/staff_audit_logs.sql | 2 +- .../schema/database/mysql_queries/CLAUDE.md | 5 +++ 9 files changed, 156 insertions(+), 1 deletion(-) create mode 100644 _database/sql/migrations/2026-04-14-062939-0000_drop_staff_audit_logs/down.sql create mode 100644 _database/sql/migrations/2026-04-14-062939-0000_drop_staff_audit_logs/up.sql create mode 100644 _database/sql/migrations/2026-04-14-062950-0000_recreate_staff_audit_logs/down.sql create mode 100644 _database/sql/migrations/2026-04-14-062950-0000_recreate_staff_audit_logs/up.sql create mode 100644 _database/sql/migrations/CLAUDE.md create mode 100644 _database/sql/migrations_squashed/CLAUDE.md diff --git a/.claude/rules/code-style.md b/.claude/rules/code-style.md index 0d1c7c41cf..c527a3411e 100644 --- a/.claude/rules/code-style.md +++ b/.claude/rules/code-style.md @@ -60,8 +60,14 @@ then the story, then the fine print. `use artcraft_router::...::CommonResolution as CommonResolutionRouter;` This avoids long fully-qualified paths in function signatures and bodies. +## MySQL + +- MySQL tables: primary key `id` columns must be `BIGINT(20) UNSIGNED`. Do not use signed IDs. +- Always create tables with `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin`. + ## TypeScript / Frontend - TypeScript with React, Vite, Zustand, Three.js - Nx monorepo under `crates/frontend/` - Two spaces for indentation + diff --git a/_database/sql/migrations/2026-04-14-062939-0000_drop_staff_audit_logs/down.sql b/_database/sql/migrations/2026-04-14-062939-0000_drop_staff_audit_logs/down.sql new file mode 100644 index 0000000000..9c8a1c49ba --- /dev/null +++ b/_database/sql/migrations/2026-04-14-062939-0000_drop_staff_audit_logs/down.sql @@ -0,0 +1,31 @@ +-- noinspection SqlDialectInspectionForFile +-- noinspection SqlNoDataSourceInspectionForFile +-- noinspection SqlResolveForFile + +-- Recreate with the original signed BIGINT id. +CREATE TABLE staff_audit_logs ( + + id BIGINT(20) NOT NULL AUTO_INCREMENT, + + token VARCHAR(32) NOT NULL, + + audit_action VARCHAR(32) NOT NULL, + + maybe_entity_type VARCHAR(16) DEFAULT NULL, + + maybe_entity_token VARCHAR(32) NOT NULL, + + staff_user_token VARCHAR(32) DEFAULT NULL, + + staff_ip_address VARCHAR(40) NOT NULL, + + created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + + PRIMARY KEY (id), + UNIQUE KEY (token), + KEY index_maybe_entity_type (maybe_entity_type), + KEY index_maybe_entity_token (maybe_entity_token), + KEY index_staff_user_token (staff_user_token), + KEY index_created_at (created_at) + +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin; diff --git a/_database/sql/migrations/2026-04-14-062939-0000_drop_staff_audit_logs/up.sql b/_database/sql/migrations/2026-04-14-062939-0000_drop_staff_audit_logs/up.sql new file mode 100644 index 0000000000..bb527f6d6e --- /dev/null +++ b/_database/sql/migrations/2026-04-14-062939-0000_drop_staff_audit_logs/up.sql @@ -0,0 +1,5 @@ +-- noinspection SqlDialectInspectionForFile +-- noinspection SqlNoDataSourceInspectionForFile +-- noinspection SqlResolveForFile + +DROP TABLE IF EXISTS staff_audit_logs; diff --git a/_database/sql/migrations/2026-04-14-062950-0000_recreate_staff_audit_logs/down.sql b/_database/sql/migrations/2026-04-14-062950-0000_recreate_staff_audit_logs/down.sql new file mode 100644 index 0000000000..bb527f6d6e --- /dev/null +++ b/_database/sql/migrations/2026-04-14-062950-0000_recreate_staff_audit_logs/down.sql @@ -0,0 +1,5 @@ +-- noinspection SqlDialectInspectionForFile +-- noinspection SqlNoDataSourceInspectionForFile +-- noinspection SqlResolveForFile + +DROP TABLE IF EXISTS staff_audit_logs; diff --git a/_database/sql/migrations/2026-04-14-062950-0000_recreate_staff_audit_logs/up.sql b/_database/sql/migrations/2026-04-14-062950-0000_recreate_staff_audit_logs/up.sql new file mode 100644 index 0000000000..8ca26db660 --- /dev/null +++ b/_database/sql/migrations/2026-04-14-062950-0000_recreate_staff_audit_logs/up.sql @@ -0,0 +1,39 @@ +-- noinspection SqlDialectInspectionForFile +-- noinspection SqlNoDataSourceInspectionForFile +-- noinspection SqlResolveForFile + +CREATE TABLE staff_audit_logs ( + + -- Not used for anything except replication. + id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT, + + -- Effective "primary key" of the audit log item (in case we add a UI or notes) + token VARCHAR(32) NOT NULL, + + -- The type of action taken + audit_action VARCHAR(32) NOT NULL, + + -- The type of entity acted upon (if any) + maybe_entity_type VARCHAR(16) DEFAULT NULL, + + -- The token of the entity mutated (if any) + maybe_entity_token VARCHAR(32) NOT NULL, + + -- The staff user who performed the action. + staff_user_token VARCHAR(32) DEFAULT NULL, + + -- For abuse tracking. + -- Wide enough for IPv4/6 + staff_ip_address VARCHAR(40) NOT NULL, + + created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + + -- INDICES -- + PRIMARY KEY (id), + UNIQUE KEY (token), + KEY index_maybe_entity_type (maybe_entity_type), + KEY index_maybe_entity_token (maybe_entity_token), + KEY index_staff_user_token (staff_user_token), + KEY index_created_at (created_at) + +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin; diff --git a/_database/sql/migrations/CLAUDE.md b/_database/sql/migrations/CLAUDE.md new file mode 100644 index 0000000000..d5423532c5 --- /dev/null +++ b/_database/sql/migrations/CLAUDE.md @@ -0,0 +1,38 @@ +# SQL Migrations + +Incremental schema changes applied in order by timestamp prefix. + +## Naming Convention + +Migration directories follow the format: + +``` +YYYY-MM-DD-HHMMSS-NNNN_description_goes_here/ + up.sql + down.sql +``` + +These are created with the `diesel` tool, and in particular: + +> `diesel migration generate description_goes_here` + +- `NNNN` is a zero-padded sequence number for ordering multiple migrations on the same timestamp. +- `up.sql` applies the migration forward. +- `down.sql` reverses it. + +## Table Conventions + +- Primary key `id` columns must be `BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT`. Do not use signed IDs. +- Always create tables with `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin`. +- All SQL files should start with the standard IntelliJ noinspection comments: + ```sql + -- noinspection SqlDialectInspectionForFile + -- noinspection SqlNoDataSourceInspectionForFile + -- noinspection SqlResolveForFile + ``` + +## Rules + +- Every `up.sql` must have a corresponding `down.sql` that cleanly reverses the migration. +- For `CREATE TABLE` migrations, the `down.sql` is typically `DROP TABLE IF EXISTS table_name;`. +- For `ALTER TABLE` migrations, the `down.sql` reverses the alteration (e.g. `DROP COLUMN`). diff --git a/_database/sql/migrations_squashed/CLAUDE.md b/_database/sql/migrations_squashed/CLAUDE.md new file mode 100644 index 0000000000..95248459cd --- /dev/null +++ b/_database/sql/migrations_squashed/CLAUDE.md @@ -0,0 +1,26 @@ +# Squashed / Materialized Schemas + +Fully materialized table definitions representing the current state of each table +after all migrations have been applied. These are not executed — they exist as +human-readable documentation of the current schema. + +## When to Update + +Update the corresponding squashed file whenever a migration changes a table's schema +(adding columns, changing types, dropping and recreating, etc.). + +## Table Conventions + +- Primary key `id` columns must be `BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT`. Do not use signed IDs. +- Always create tables with `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin`. +- All SQL files should start with the standard IntelliJ noinspection comments: + ```sql + -- noinspection SqlDialectInspectionForFile + -- noinspection SqlNoDataSourceInspectionForFile + -- noinspection SqlResolveForFile + ``` + +## File Organization + +Files are named after their table (e.g. `users.sql`, `media_files.sql`). +Some tables are grouped into subdirectories (e.g. `user_tables/`). diff --git a/_database/sql/migrations_squashed/staff_audit_logs.sql b/_database/sql/migrations_squashed/staff_audit_logs.sql index cc55e5823d..8ca26db660 100644 --- a/_database/sql/migrations_squashed/staff_audit_logs.sql +++ b/_database/sql/migrations_squashed/staff_audit_logs.sql @@ -5,7 +5,7 @@ CREATE TABLE staff_audit_logs ( -- Not used for anything except replication. - id BIGINT(20) NOT NULL AUTO_INCREMENT, + id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT, -- Effective "primary key" of the audit log item (in case we add a UI or notes) token VARCHAR(32) NOT NULL, diff --git a/crates/schema/database/mysql_queries/CLAUDE.md b/crates/schema/database/mysql_queries/CLAUDE.md index c6e268671e..c10c15976b 100644 --- a/crates/schema/database/mysql_queries/CLAUDE.md +++ b/crates/schema/database/mysql_queries/CLAUDE.md @@ -52,6 +52,11 @@ schema metadata. For **new tables**, you may need to: 2. Run `cargo sqlx prepare` to regenerate the cache 3. Or manually create cache entries for simple INSERT/UPDATE queries (they only need parameter count) +### Table Conventions + +- Primary key `id` columns must be `BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT`. Do not use signed IDs. +- Always create tables with `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin`. + ### Error Types New queries should return `Result` instead of the legacy `AnyhowResult`.