Firelands DB Explorer

Terminal application (C++) for exploring the firelands-next database (WoW emulator).

Overview

Firelands DB Explorer is a terminal-based database exploration tool built with C++ and the FTXUI library. It provides an interactive interface for browsing, searching, and modifying data in a World of Warcraft emulator database (specifically for the Firelands expansion).

Features

• Interactive terminal UI with sidebar navigation
• Database connection management
• Table browsing with pagination
• Data filtering and searching
• Record editing, insertion, and deletion
• SQL query execution with preview
• Entity-specific editors for common WoW database tables (items, creatures, game objects, quests, etc.)
• Unified search functionality
• Logging capabilities

Dependencies

The build script automatically handles most dependencies. However, the following are required:

• CMake - Build configuration
• Ninja - Build system (faster builds)
• Python 3 - For running build scripts
• firelands-next - Must be built first (provides MariaDB, FTXUI, spdlog, yaml-cpp static libs)

System-specific

Platform	Required Packages
macOS	openssl@3, zlib, bzip2, boost (via Homebrew)
Linux	libssl-dev, zlib1g-dev, libbz2-dev, libboost-all-dev
Windows	vcpkg or MSYS2 recommended

Build Instructions

Quick Start (Recommended)

Use the cross-platform build script:

cd firelands-db-explorer
python3 scripts/build.py

This script will:

1. Check for required dependencies
2. Copy static libraries from firelands-next
3. Copy required system libraries (OpenSSL, Boost, etc.)
4. Build the application

Manual Build

# Configure the build
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug

# Build the application
ninja -C build

Prerequisites

All Platforms

• firelands-next must be cloned and built at ../firelands-next
• CMake 3.10+
• Ninja build system
• C++17 compatible compiler

macOS

# Install Homebrew dependencies
brew install cmake ninja openssl@3 zlib bzip2 boost

Linux (Debian/Ubuntu)

sudo apt update
sudo apt install cmake ninja-build libssl-dev zlib1g-dev libbz2-dev libboost-all-dev

Linux (Fedora)

sudo dnf install cmake ninja-build openssl-devel zlib-devel bzip2-devel boost-devel

Windows

Windows requires either:

• MSYS2 with MinGW: pacman -S mingw-w64-x86_64-make mingw-w64-x86_64-boost
• Or use vcpkg for dependency management

Build Output

After building:

• Executable: build/bin/FirelandsDbExplorer
• Static libs: libs/ (can be distributed with the executable)

Usage

After building the application:

./build/bin/FirelandsDbExplorer

Configuration

Create an explorer.yaml file to configure database connection:

Database:
  User: "firelands"
  Password: "firelands"
  URI: "jdbc:mariadb://localhost:3306/firelands_auth"

The config file is searched in:

1. Current working directory
2. Next to executable
3. Environment variable FIRELANDS_EXPLORER_CONFIG

Navigation

• Use arrow keys to navigate the sidebar menu
• Press Enter to select a menu item
• Use Tab to switch between sidebar and main content areas
• In table views:
  • Arrow keys to navigate cells
  • Enter to start editing a cell
  • Ctrl+S to save changes
  • Escape to cancel editing
  • Insert key to add a new row
  • Delete key to remove selected row
  • F key to apply filters
  • C key to clear filters
• In forms:
  • Tab to navigate between fields
  • Enter to save form
  • Escape to cancel form

Database Connection

The application will attempt to connect to the database using configuration from the firelands-next project. Ensure that:

1. The firelands-next project is built and its dependencies are available
2. Database credentials are properly configured in the firelands-next project
3. The MySQL server is running and accessible

Project Structure

firelands-db-explorer/
├── scripts/
│   └── build.py            # Cross-platform build script
├── libs/                    # Static libraries (auto-generated)
├── build/
│   └── bin/
│       └── FirelandsDbExplorer  # Compiled executable
├── src/
│   ├── main.cpp                # Application entry point
│   ├── infrastructure/         # Database connectivity layer
│   │   ├── DatabaseManager.h   # Database manager interface
│   │   ├── DatabaseManager.cpp # Database manager implementation
│   │   ├── MySqlConnection.h   # MySQL connection wrapper
│   │   └── MySqlConnection.cpp # MySQL connection implementation
│   ├── shared/                 # Shared utilities
│   │   ├── Logger.h            # Logging functionality
│   │   ├── Logger.cpp          # Logging implementation
│   │   ├── Banner.h            # Application banner
│   │   └── Common.h            # Common definitions
│   └── ui/                     # User interface components
│       ├── ExplorerFtxui.h     # Main application class
│       ├── ExplorerFtxui.cpp   # Main application implementation
│       ├── components/         # Reusable UI components
│       │   └── TextField.*     # Text input component
│       └── views/              # Different view types
│           ├── DataTableView.*     # Table data viewer/editor
│           ├── FormEditorView.*    # Form-based editor for entities
│           └── ...               # Other specialized views
├── CMakeLists.txt              # Build configuration
├── README.md                   # This file
└── .gitignore

Technology Stack

• Language: C++17
• Build System: CMake with Ninja
• UI Library: FTXUI (Terminal-based UI)
• Database: MariaDB Connector/C++
• Logging: Custom logging implementation

Development

This project follows the same development practices as the firelands-next project:

• Test-Driven Development (TDD) for business logic
• Consistent code style and conventions
• English-only code, comments, and documentation
• Modular architecture with separation of concerns

License

Please refer to the firelands-next project for licensing information, as this tool is designed to work specifically with that codebase.

Troubleshooting

Build Errors

1. "firelands-next not found"

   • Ensure firelands-next is cloned at ../firelands-next
   • Run: cd ../firelands-next && ./scripts/build.py

2. "firelands-next not built"

   • Build firelands-next first: cd ../firelands-next && python3 scripts/build.py

3. Missing library errors

   • Run the build script which handles dependency copying automatically
   • Or install missing packages manually (see Prerequisites section)

Runtime Errors

1. Database connection failed

   • Verify MySQL/MariaDB server is running
   • Check credentials in firelands-next configuration

2. Application won't start

   • Try running from a proper terminal (not VS Code terminal on Windows)
   • Check that your terminal supports ANSI escape codes

Contributing

Feel free to submit issues or pull requests to improve this tool. Please follow the existing code conventions and maintain the modular architecture.