AzerothCore-RealmMaster/docs/AZEROTHCORE_MODULE_SQL_ANALYSIS.md

AzerothCore Module SQL Integration - Official Documentation Analysis

Date: 2025-11-16 Purpose: Compare official AzerothCore module documentation with our implementation

---

Official AzerothCore Module Installation Process

According to https://www.azerothcore.org/wiki/installing-a-module

Standard Installation Steps:

1. Find Module - Browse AzerothCore Catalogue
2. Clone/Download - Add module to /modules/ directory
   • ⚠️ Critical: Remove -master suffix from directory name
3. Reconfigure CMake - Regenerate build files
   • Verify module appears in CMake logs under "Modules configuration (static)"
4. Recompile Core - Build with module included
5. Automatic SQL Processing - "Your Worldserver will automatically run any SQL Queries provided by the Modules"
6. Check README - Review for manual configuration steps

---

SQL Directory Structure Standards

Official Structure (from AzerothCore core)

data/sql/
├── create/      # Database create/drop files
├── base/        # Latest squashed update files
├── updates/     # Incremental update files
│   ├── db_world/
│   ├── db_characters/
│   └── db_auth/
└── custom/      # Custom user modifications

Module SQL Structure

According to documentation:

• Modules "can create base, updates and custom sql that will be automatically loaded in our db_assembler"
• Status: Documentation marked as "work in progress..."
• Reference: Check skeleton-module template for examples

---

Directory Naming Conventions

Research Findings

From GitHub PR #16157 (closed without merge):

Two competing conventions exist:

1. data/sql/db-world - Official standard (hyphen naming)

   • Used by: skeleton-module (recommended template)
   • AzerothCore core uses: data/sql/updates/db_world (underscore in core, hyphen in modules)

2. sql/world - Legacy convention (no db- prefix)

   • Used by: mod-eluna, mod-ah-bot, many older modules
   • Not officially supported - PR to support this was closed

Community Decision: Favor standardization on data/sql/db-world over backward compatibility

---

DBUpdater Behavior

Automatic Updates

Configuration: worldserver.conf

AC_UPDATES_ENABLE_DATABASES = 7  # Enable all database autoupdates

How it works:

1. Each database (auth, characters, world) has version_db_xxxx table
2. Tracks last applied update in format YYYY_MM_DD_XX
3. Worldserver scans for new updates on startup
4. Automatically applies SQL files in chronological order

File Naming Convention

Required format: YYYY_MM_DD_XX.sql

Examples:

• 2025_11_16_00.sql
• 2025_11_16_01_module_name_description.sql

---

Critical Discovery: Module SQL Scanning

From our testing and official docs research:

AzerothCore's DBUpdater DOES NOT scan module directories automatically!

What Official Docs Say	Reality
"Worldserver will automatically run any SQL Queries provided by the Modules"	✅ TRUE - but only from CORE updates directory
SQL files in modules are "automatically loaded"	❌ FALSE - modules must stage SQL to core directory

The Truth:

• DBUpdater scans: /azerothcore/data/sql/updates/db_world/ (core directory)
• DBUpdater does NOT scan: /azerothcore/modules/*/data/sql/ (module directories)
• Modules compiled into the core have their SQL "baked in" during build
• Pre-built images require runtime staging (our discovery!)

---

Our Implementation vs. Official Process

Official Process (Build from Source)

1. Clone module to /modules/
2. Run CMake (detects module)
3. Compile core (module SQL gets integrated into build)
4. Deploy compiled binary
5. DBUpdater processes SQL from core updates directory

Result: Module SQL files get copied into core directory structure during build

Our Process (Pre-built Docker Images)

1. Download pre-built image (modules already compiled in)
2. Mount module repositories at runtime
3. ❌ Module SQL NOT in core updates directory
4. ✅ Runtime staging copies SQL to core updates directory
5. DBUpdater processes SQL from core updates directory

Result: Runtime staging replicates what build-time would have done

---

Gap Analysis

What We're Missing (vs. Standard Installation)

Feature	Official Process	Our Implementation	Status
Module C++ code	Compiled into binary	✅ Pre-compiled in image	✅ COMPLETE
Module SQL discovery	CMake build process	✅ Runtime scanning	✅ COMPLETE
SQL file validation	Build warnings	✅ Empty + security checks	✅ ENHANCED
SQL naming format	Developer responsibility	✅ Automatic timestamping	✅ ENHANCED
SQL to core directory	Build-time copy	✅ Runtime staging	✅ COMPLETE
DBUpdater processing	Worldserver autoupdate	✅ Worldserver autoupdate	✅ COMPLETE
README instructions	Manual review needed	⚠️ Not automated	⚠️ GAP
Module .conf files	Manual deployment	✅ Automated sync	✅ COMPLETE

Identified Gaps

1. README Processing

Official: "Always check the README file of the module to see if any manual steps are needed" Our Status: Manual - users must check README themselves Impact: LOW - Most modules don't require manual steps beyond SQL Recommendation: Document in user guide

2. Module Verification Command

Official: "Use .server debug command to verify all loaded modules" Our Status: Not documented in deployment Impact: LOW - Informational only Recommendation: Add to post-deployment checklist

3. CMake Module Detection

Official: Check CMake logs for "Modules configuration (static)" Our Status: Not applicable - using pre-built images Impact: NONE - Only relevant for custom builds Recommendation: N/A

---

SQL Directory Scanning - Current vs. Potential

What We Currently Scan

for db_type in db-world db-characters db-auth; do
  # Scans: /azerothcore/modules/*/data/sql/db-world/*.sql
  # Direct directory only
done

Coverage:

• ✅ Standard location: data/sql/db-world/
• ✅ Hyphen naming convention
• ❌ Underscore variant: data/sql/db_world/
• ❌ Legacy locations: sql/world/
• ❌ Subdirectories: data/sql/base/, data/sql/updates/
• ❌ Custom directory: data/sql/custom/

Should We Expand?

Arguments FOR expanding scan:

• Some modules use legacy sql/world/ structure
• Some modules organize SQL in base/ and updates/ subdirectories
• Better compatibility with diverse module authors

Arguments AGAINST expanding:

• Official AzerothCore rejected multi-path support (PR #16157 closed)
• Community prefers standardization over compatibility
• Adds complexity for edge cases
• May encourage non-standard module structure

Recommendation: Stay with current implementation

• Official standard is data/sql/db-world/
• Non-compliant modules should be updated by authors
• Our implementation matches official recommendation
• Document expected structure in user guide

---

Module Configuration Files

Standard Module Configuration

Modules can include:

• Source: conf/*.conf.dist files
• Deployment: Copied to worldserver config directory
• Our Implementation: ✅ manage-modules.sh handles this

---

Comparison with db_assembler

What is db_assembler?

Official tool for database setup during installation

• Runs during initial setup
• Processes base/ and updates/ directories
• Creates fresh database structure

Our Runtime Staging vs. db_assembler

Feature	db_assembler	Our Runtime Staging
When runs	Installation time	Every deployment
Purpose	Initial DB setup	Module SQL updates
Processes	base/ + updates/	Direct SQL files
Target	Fresh databases	Existing databases
Module awareness	Build-time	Runtime

Key Difference: We handle the "module SQL updates" part that db_assembler doesn't cover for pre-built images

---

Validation Against Official Standards

✅ What We Do Correctly

1. SQL File Naming: Automatic timestamp prefixing matches AzerothCore format
2. Directory Structure: Scanning data/sql/db-world/ matches official standard
3. Database Types: Support db-world, db-characters, db-auth (official set)
4. Autoupdate Integration: Files staged to location DBUpdater expects
5. Module Prefix: Adding MODULE_ prefix prevents conflicts with core updates

✅ What We Do Better Than Standard

1. SQL Validation: Empty file check + security scanning (not in standard process)
2. Error Reporting: Detailed success/skip/fail counts
3. Automatic Timestamping: No manual naming required
4. Conflict Prevention: MODULE_ prefix ensures safe identification

⚠️ Potential Concerns

1. Multiple Deployments: Issue: Re-running deployment could create duplicate SQL files Mitigation: DBUpdater tracks applied updates in version_db_xxxx table Result: Duplicates are harmless - already-applied updates skipped

2. Manual SQL Files: Issue: If user manually adds SQL to module directory Behavior: Will be staged on next deployment Result: Expected behavior - matches official "custom SQL" workflow

3. Module Updates: Issue: Git pull adds new SQL to module Behavior: New files staged on next deployment Result: Expected behavior - updates applied automatically

---

Missing Official Features

Not Implemented (Intentional)

1. db_assembler integration - Not needed for pre-built images
2. CMake module detection - Not applicable to Docker deployment
3. Build-time SQL staging - Replaced by runtime staging
4. Manual SQL execution - Replaced by DBUpdater autoupdate

Not Implemented (Gaps)

1. README parsing - Manual review still required
2. Module dependency checking - Not validated automatically
3. SQL rollback support - No automatic downgrade path
4. Version conflict detection - Relies on DBUpdater

---

Recommendations

Keep As-Is ✅

1. Current directory scanning - Matches official standard
2. Runtime staging approach - Necessary for pre-built images
3. SQL validation - Better than standard
4. Automatic timestamping - Convenience improvement

Document for Users 📝

1. Expected module structure - Explain data/sql/db-world/ requirement
2. Deployment behavior - Clarify when SQL is staged and applied
3. README review - Remind users to check module documentation
4. Verification steps - Add .server debug command to post-deploy checklist

Future Enhancements (Optional) 🔮

1. README scanner - Parse common instruction formats
2. SQL dependency detection - Warn about missing prerequisites
3. Module health check - Verify SQL was applied successfully
4. Staging log - Persistent record of staged files

---

Conclusion

Our Implementation is Sound ✅

Alignment with Official Process:

• ✅ Matches official SQL directory structure
• ✅ Integrates with official DBUpdater
• ✅ Follows official naming conventions
• ✅ Supports official database types

Advantages Over Standard Build Process:

• ✅ Works with pre-built Docker images
• ✅ Better SQL validation and security
• ✅ Automatic file naming
• ✅ Clear error reporting

No Critical Gaps Identified:

• All essential functionality present
• Missing features are either:
  • Not applicable to Docker deployment
  • Manual steps (README review)
  • Nice-to-have enhancements

Validation Complete

Our runtime SQL staging implementation successfully replicates what the official build process does, while adding improvements for Docker-based deployments. No changes required to match official standards.

---

References

1. Installing a Module - Official Docs
2. Create a Module - Official Docs
3. SQL Directory Structure
4. Database Updates
5. Skeleton Module Template
6. PR #16157 - SQL Path Support
7. Issue #2592 - db_assembler Auto-discovery