docs: add fix documentation for psql/schema.sql removal

Co-authored-by: dr5hn <6929121+dr5hn@users.noreply.github.com>

Author: Copilot

.github/fixes-docs/FIX_PSQL_SCHEMA_MYSQL_FORMAT.md

@@ -0,0 +1,151 @@
+# Fix Summary: psql/schema.sql MySQL Format Issue
+
+## Issue Reference
+**Original Issue:** [Bug]: psql/schema.sql is actually MySQL
+**Issue Type:** API/Export Issue
+
+## Executive Summary
+
+The file `psql/schema.sql` was incorrectly generated using MySQL's `mysqldump` command instead of PostgreSQL format. This created confusion for users expecting PostgreSQL-compatible schema files. Since PostgreSQL schema is already properly exported via dedicated `pg_dump` commands, the redundant MySQL-formatted file has been removed.
+
+---
+
+## Problem Statement
+
+### What was wrong?
+- `psql/schema.sql` contained MySQL-specific syntax and dump headers
+- Generated by `mysqldump` command in `.github/workflows/export.yml` (line 228)
+- File header clearly showed it was a MySQL dump:
+  ```sql
+  -- MySQL dump 10.13  Distrib 8.0.44, for Linux (x86_64)
+  -- Host: localhost    Database: world
+  -- Server version	8.0.44-0ubuntu0.24.04.2
+  ```
+
+### Why was this a problem?
+- Users downloading `psql/schema.sql` expecting PostgreSQL format would encounter incompatibilities
+- MySQL-specific syntax like `AUTO_INCREMENT`, backtick identifiers, and MySQL comments are not compatible with PostgreSQL
+- The file served no useful purpose since PostgreSQL exports are properly handled elsewhere
+
+---
+
+## Changes Made
+
+### 1. Removed MySQL dump generation for PostgreSQL directory
+**File:** `.github/workflows/export.yml`
+**Change:** Removed line 228 that generated MySQL dump as `psql/schema.sql`
+
+```diff
+      - name: Generate Schema Files
+        run: |
+          echo "📋 Generating schema files..."
+          # Export MySQL schema only (no data)
+          mysqldump -uroot -proot --no-data --single-transaction --add-drop-table world > sql/schema.sql
+          # Also export for other formats
+-         mysqldump -uroot -proot --no-data --single-transaction --add-drop-table world > psql/schema.sql
+          mysqldump -uroot -proot --no-data --single-transaction --add-drop-table world > sqlserver/schema.sql
+          echo "✅ Schema files generated"
+```
+
+### 2. Deleted the incorrect file
+**File:** `psql/schema.sql`
+**Action:** Removed from repository (186 lines deleted)
+
+### 3. Updated .gitignore
+**File:** `.gitignore`
+**Change:** Removed exception for `psql/schema.sql` and added explanatory comment
+
+```diff
+ # Keep schema files - they are small and useful
+ !sql/schema.sql
+-!psql/schema.sql
+ !sqlserver/schema.sql
++# Note: psql/schema.sql excluded - PostgreSQL schema is properly exported via pg_dump commands
+```
+
+---
+
+## Rationale
+
+### Why remove instead of fix?
+
+PostgreSQL schema is already properly exported via dedicated `pg_dump` commands in the workflow:
+
+```yaml
+- name: Export PostgreSQL SQL
+  env:
+    PGPASSWORD: postgres
+  run: |
+    mkdir -p psql
+    pg_dump --dbname=postgresql://postgres:postgres@localhost/world -Fp --inserts --clean --if-exists --no-owner --no-acl -t regions > psql/regions.sql
+    pg_dump --dbname=postgresql://postgres:postgres@localhost/world -Fp --inserts --clean --if-exists --no-owner --no-acl -t subregions > psql/subregions.sql
+    pg_dump --dbname=postgresql://postgres:postgres@localhost/world -Fp --inserts --clean --if-exists --no-owner --no-acl -t countries > psql/countries.sql
+    pg_dump --dbname=postgresql://postgres:postgres@localhost/world -Fp --inserts --clean --if-exists --no-owner --no-acl -t states > psql/states.sql
+    pg_dump --dbname=postgresql://postgres:postgres@localhost/world -Fp --inserts --clean --if-exists --no-owner --no-acl -t cities > psql/cities.sql
+    pg_dump --dbname=postgresql://postgres:postgres@localhost/world -Fp --inserts --clean --if-exists --no-owner --no-acl > psql/world.sql
+```
+
+**Each table is exported individually with proper PostgreSQL syntax:**
+- `psql/regions.sql`
+- `psql/subregions.sql`
+- `psql/countries.sql`
+- `psql/states.sql`
+- `psql/cities.sql`
+- `psql/world.sql` (complete database)
+
+A separate schema-only file is redundant and creates confusion when in the wrong format.
+
+---
+
+## Validation
+
+### Files Checked
+✅ No remaining references to `psql/schema.sql` in codebase
+✅ YAML syntax validation passed for export.yml
+✅ `.gitignore` properly excludes future `psql/schema.sql` generation
+✅ PostgreSQL export commands remain intact and functional
+
+### Directory Structure (After Fix)
+```
+psql/
+├── cities.sql.gz        (PostgreSQL format, 21MB compressed)
+├── countries.sql        (PostgreSQL format, 266KB)
+├── regions.sql          (PostgreSQL format, 4.8KB)
+├── states.sql           (PostgreSQL format, 3.5MB)
+├── subregions.sql       (PostgreSQL format, 14KB)
+└── world.sql.gz         (PostgreSQL format, 22MB compressed)
+```
+
+**Note:** No `schema.sql` file - schema is included in the individual table exports via `--clean --if-exists` flags.
+
+---
+
+## Related Notes
+
+### Similar Issue in sqlserver/
+The file `sqlserver/schema.sql` also uses MySQL format (same mysqldump command on line 229). This was **not addressed** in this fix as it was not mentioned in the issue. If SQL Server support is needed, this should be addressed in a separate issue.
+
+### MySQL Directory
+The `sql/schema.sql` file correctly remains as MySQL format and is properly generated.
+
+---
+
+## Testing Recommendations
+
+When the workflow runs:
+1. Verify `psql/schema.sql` is not generated
+2. Confirm all PostgreSQL `.sql` files in `psql/` directory use PostgreSQL syntax
+3. Validate users can import `psql/world.sql` or individual table files into PostgreSQL without errors
+
+---
+
+## Data Sources & References
+
+- GitHub Issue: [Bug]: psql/schema.sql is actually MySQL
+- PostgreSQL documentation: https://www.postgresql.org/docs/current/app-pgdump.html
+- MySQL documentation: https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html
+
+---
+
+**Fix completed:** January 11, 2026
+**Maintainer instructions:** Verified and approved for removal