feat(tools.func): use distro packages for MariaDB by default (#11049)

- Changed setup_mariadb() to use Debian/Ubuntu distribution packages by default
- Official MariaDB repository only used when specific version is requested
- Added cleanup logic for old/orphaned repository files with apt update
- Added version comparison to prevent downgrades (keeps higher version installed)
- Added automatic fallback to distro packages if repo installation fails
- Extracted _setup_mariadb_runtime_dir() helper function
- Updated all related documentation

This change improves reliability by avoiding MariaDB mirror issues
(HTTPS->HTTP redirects, geographic availability problems) for standard
installations while still allowing specific versions when needed.

docs/install/DETAILED_GUIDE.md

@@ -544,7 +544,8 @@ network_check
 update_os
 
 PHP_VERSION="8.4" PHP_MODULE="bcmath,curl,pdo_mysql" setup_php
-MARIADB_VERSION="11.4" setup_mariadb
+setup_mariadb  # Uses distribution packages (recommended)
+# Or for specific version: MARIADB_VERSION="11.4" setup_mariadb
 
 # Database setup
 DB_PASS=$(openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | head -c13)

docs/install/README.md

@@ -85,7 +85,8 @@ pkg_install curl wget git
 ```bash
 setup_nodejs "20"
 setup_php "8.3"
-setup_mariadb "11"
+setup_mariadb  # Uses distribution packages (recommended)
+# MARIADB_VERSION="11.4" setup_mariadb  # For specific version
 ```
 
 ### Phase 4: Application Download

docs/misc/tools.func/README.md

@@ -75,7 +75,8 @@ Complete reference of environment variables and configuration options.
 ```bash
 setup_nodejs "20"     # Install Node.js v20
 setup_php "8.2"       # Install PHP 8.2
-setup_mariadb "11"    # Install MariaDB 11
+setup_mariadb         # Install MariaDB (distribution packages)
+# MARIADB_VERSION="11.4" setup_mariadb  # Specific version from official repo
 ```
 
 ### Safe Package Operations

docs/misc/tools.func/TOOLS_FUNC_FUNCTIONS_REFERENCE.md

@@ -24,7 +24,7 @@ Complete alphabetical reference of all functions in tools.func with parameters,
 - `setup_golang(VERSION)` - Install Go programming language
 
 **Databases**:
-- `setup_mariadb(VERSION)` - Install MariaDB server
+- `setup_mariadb()` - Install MariaDB server (distro packages by default)
 - `setup_postgresql(VERSION)` - Install PostgreSQL
 - `setup_mongodb(VERSION)` - Install MongoDB
 - `setup_redis(VERSION)` - Install Redis cache
@@ -238,17 +238,20 @@ setup_php "8.3"
 
 ---
 
-### setup_mariadb(VERSION)
+### setup_mariadb()
 
 Install MariaDB server and client utilities.
 
 **Signature**:
 ```bash
-setup_mariadb VERSION
+setup_mariadb                         # Uses distribution packages (recommended)
+MARIADB_VERSION="11.4" setup_mariadb  # Uses official MariaDB repository
 ```
 
-**Parameters**:
+**Variables**:
-- `VERSION` - MariaDB version (e.g., "10.6", "11.0")
+- `MARIADB_VERSION` - (optional) Specific MariaDB version
+  - Not set or `"latest"`: Uses distribution packages (most reliable, avoids mirror issues)
+  - Specific version (e.g., `"11.4"`, `"12.2"`): Uses official MariaDB repository
 
 **Returns**:
 - `0` - Installation successful
@@ -259,7 +262,11 @@ setup_mariadb VERSION
 
 **Example**:
 ```bash
-setup_mariadb "11.0"
+# Recommended: Use distribution packages (stable, no mirror issues)
+setup_mariadb
+
+# Specific version from official repository
+MARIADB_VERSION="11.4" setup_mariadb
 ```
 
 ---
@@ -441,7 +448,7 @@ source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
 
 pkg_update                    # Update package lists
 setup_nodejs "20"             # Install Node.js
-setup_mariadb "11"            # Install MariaDB
+setup_mariadb                 # Install MariaDB (distribution packages)
 
 # ... application installation ...
 
@@ -460,7 +467,7 @@ source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
 pkg_update
 setup_nginx
 setup_php "8.3"
-setup_mariadb "11"
+setup_mariadb  # Uses distribution packages
 setup_composer
 ```
 

docs/misc/tools.func/TOOLS_FUNC_USAGE_EXAMPLES.md

@@ -65,7 +65,7 @@ pkg_update
 
 setup_nginx
 setup_php "8.3"
-setup_mariadb "11"
+setup_mariadb  # Uses distribution packages (recommended)
 setup_composer
 
 msg_ok "Web stack installed"
@@ -388,7 +388,7 @@ pkg_install package-name
 # Chain multiple tools together
 setup_nodejs "20"
 setup_php "8.3"
-setup_mariadb "11"
+setup_mariadb  # Distribution packages (recommended)
 
 # Check command success
 if ! setup_docker; then

misc/tools.func

@@ -3601,57 +3601,37 @@ EOF
 }
 
 # ------------------------------------------------------------------------------
-# Installs or updates MariaDB from official repo.
+# Installs or updates MariaDB.
 #
 # Description:
+#   - Uses Debian/Ubuntu distribution packages by default (most reliable)
+#   - Only uses official MariaDB repository when a specific version is requested
 #   - Detects current MariaDB version and replaces it if necessary
 #   - Preserves existing database data
-#   - Dynamically determines latest GA version if "latest" is given
 #
 # Variables:
-#   MARIADB_VERSION - MariaDB version to install (e.g. 10.11, latest) (default: latest)
+#   MARIADB_VERSION - MariaDB version to install (optional)
+#                     - Not set or "latest": Uses distribution packages (recommended)
+#                     - Specific version (e.g. "11.4", "12.2"): Uses MariaDB official repo
 # ------------------------------------------------------------------------------
 
 setup_mariadb() {
   local MARIADB_VERSION="${MARIADB_VERSION:-latest}"
+  local USE_DISTRO_PACKAGES=false
 
   # Ensure non-interactive mode for all apt operations
   export DEBIAN_FRONTEND=noninteractive
   export NEEDRESTART_MODE=a
   export NEEDRESTART_SUSPEND=1
 
-  # Resolve "latest" to actual version
+  # Determine installation method:
-  if [[ "$MARIADB_VERSION" == "latest" ]]; then
+  # - "latest" or empty: Use distribution packages (avoids mirror issues)
-    if ! curl -fsI --max-time 10 http://mirror.mariadb.org/repo/ >/dev/null 2>&1; then
+  # - Specific version: Use MariaDB official repository
-      msg_warn "MariaDB mirror not reachable - trying mariadb_repo_setup fallback"
+  if [[ "$MARIADB_VERSION" == "latest" || -z "$MARIADB_VERSION" ]]; then
-      # Try using official mariadb_repo_setup script as fallback
+    USE_DISTRO_PACKAGES=true
-      if curl -fsSL --max-time 15 https://r.mariadb.com/downloads/mariadb_repo_setup 2>/dev/null | bash -s -- --skip-verify >/dev/null 2>&1; then
+    msg_info "Setup MariaDB (distribution packages)"
-        msg_ok "MariaDB repository configured via mariadb_repo_setup"
+  else
-        # Extract version from configured repo
+    msg_info "Setup MariaDB $MARIADB_VERSION (official repository)"
-        MARIADB_VERSION=$(grep -oP 'repo/\K[0-9]+\.[0-9]+\.[0-9]+' /etc/apt/sources.list.d/mariadb.list 2>/dev/null | head -n1 || echo "12.2")
-      else
-        msg_warn "mariadb_repo_setup failed - using hardcoded fallback version"
-        MARIADB_VERSION="12.2"
-      fi
-    else
-      MARIADB_VERSION=$(curl -fsSL --max-time 15 http://mirror.mariadb.org/repo/ 2>/dev/null |
-        grep -Eo '[0-9]+\.[0-9]+\.[0-9]+/' |
-        grep -vE 'rc/|rolling/' |
-        sed 's|/||' |
-        sort -Vr |
-        head -n1 || echo "")
-
-      if [[ -z "$MARIADB_VERSION" ]]; then
-        msg_warn "Could not parse latest GA MariaDB version from mirror - trying mariadb_repo_setup"
-        if curl -fsSL --max-time 15 https://r.mariadb.com/downloads/mariadb_repo_setup 2>/dev/null | bash -s -- --skip-verify >/dev/null 2>&1; then
-          msg_ok "MariaDB repository configured via mariadb_repo_setup"
-          MARIADB_VERSION=$(grep -oP 'repo/\K[0-9]+\.[0-9]+\.[0-9]+' /etc/apt/sources.list.d/mariadb.list 2>/dev/null | head -n1 || echo "12.2")
-        else
-          msg_warn "mariadb_repo_setup failed - using hardcoded fallback version"
-          MARIADB_VERSION="12.2"
-        fi
-      fi
-    fi
   fi
 
   # Get currently installed version
@@ -3659,17 +3639,105 @@ setup_mariadb() {
   CURRENT_VERSION=$(is_tool_installed "mariadb" 2>/dev/null) || true
 
   # Pre-configure debconf to prevent any interactive prompts during install/upgrade
-  local MARIADB_MAJOR_MINOR
+  debconf-set-selections <<EOF
-  MARIADB_MAJOR_MINOR=$(echo "$MARIADB_VERSION" | awk -F. '{print $1"."$2}')
-  if [[ -n "$MARIADB_MAJOR_MINOR" ]]; then
-    debconf-set-selections <<EOF
-mariadb-server-$MARIADB_MAJOR_MINOR mariadb-server/feedback boolean false
-mariadb-server-$MARIADB_MAJOR_MINOR mariadb-server/root_password password
-mariadb-server-$MARIADB_MAJOR_MINOR mariadb-server/root_password_again password
 mariadb-server mariadb-server/feedback boolean false
 mariadb-server mariadb-server/root_password password
 mariadb-server mariadb-server/root_password_again password
 EOF
+
+  # If specific version requested, also configure version-specific debconf
+  if [[ "$USE_DISTRO_PACKAGES" == "false" ]]; then
+    local MARIADB_MAJOR_MINOR
+    MARIADB_MAJOR_MINOR=$(echo "$MARIADB_VERSION" | awk -F. '{print $1"."$2}')
+    if [[ -n "$MARIADB_MAJOR_MINOR" ]]; then
+      debconf-set-selections <<EOF
+mariadb-server-$MARIADB_MAJOR_MINOR mariadb-server/feedback boolean false
+mariadb-server-$MARIADB_MAJOR_MINOR mariadb-server/root_password password
+mariadb-server-$MARIADB_MAJOR_MINOR mariadb-server/root_password_again password
+EOF
+    fi
+  fi
+
+  # ============================================================================
+  # DISTRIBUTION PACKAGES PATH (default, most reliable)
+  # ============================================================================
+  if [[ "$USE_DISTRO_PACKAGES" == "true" ]]; then
+    # Check if MariaDB was previously installed from official repo
+    local HAD_MARIADB_REPO=false
+    if [[ -f /etc/apt/sources.list.d/mariadb.sources ]] || [[ -f /etc/apt/sources.list.d/mariadb.list ]]; then
+      HAD_MARIADB_REPO=true
+      msg_info "Removing MariaDB official repository (switching to distribution packages)"
+    fi
+
+    # Clean up any existing MariaDB repository files to avoid conflicts
+    cleanup_old_repo_files "mariadb"
+
+    # If we had a repo, we need to refresh APT cache
+    if [[ "$HAD_MARIADB_REPO" == "true" ]]; then
+      $STD apt update || msg_warn "APT update had issues, continuing..."
+    fi
+
+    # Ensure APT is working
+    ensure_apt_working || return 1
+
+    # Check if installed version is from official repo and higher than distro version
+    # In this case, we keep the existing installation to avoid data issues
+    if [[ -n "$CURRENT_VERSION" ]]; then
+      # Get available distro version
+      local DISTRO_VERSION=""
+      DISTRO_VERSION=$(apt-cache policy mariadb-server 2>/dev/null | grep -E "Candidate:" | awk '{print $2}' | grep -oP '^\d+:\K\d+\.\d+\.\d+' || echo "")
+
+      if [[ -n "$DISTRO_VERSION" ]]; then
+        # Compare versions - if current is higher, keep it
+        local CURRENT_MAJOR DISTRO_MAJOR
+        CURRENT_MAJOR=$(echo "$CURRENT_VERSION" | awk -F. '{print $1}')
+        DISTRO_MAJOR=$(echo "$DISTRO_VERSION" | awk -F. '{print $1}')
+
+        if [[ "$CURRENT_MAJOR" -gt "$DISTRO_MAJOR" ]]; then
+          msg_warn "MariaDB $CURRENT_VERSION is already installed (higher than distro $DISTRO_VERSION)"
+          msg_warn "Keeping existing installation to preserve data integrity"
+          msg_warn "To use distribution packages, manually remove MariaDB first"
+          _setup_mariadb_runtime_dir
+          cache_installed_version "mariadb" "$CURRENT_VERSION"
+          msg_ok "Setup MariaDB $CURRENT_VERSION (existing installation kept)"
+          return 0
+        fi
+      fi
+    fi
+
+    # Install or upgrade MariaDB from distribution packages
+    if ! install_packages_with_retry "mariadb-server" "mariadb-client"; then
+      msg_error "Failed to install MariaDB packages from distribution"
+      return 1
+    fi
+
+    # Get installed version for caching
+    local INSTALLED_VERSION=""
+    INSTALLED_VERSION=$(mariadb --version 2>/dev/null | grep -oP '\d+\.\d+\.\d+' | head -n1 || echo "distro")
+
+    # Configure runtime directory and finish
+    _setup_mariadb_runtime_dir
+    cache_installed_version "mariadb" "$INSTALLED_VERSION"
+    msg_ok "Setup MariaDB $INSTALLED_VERSION (distribution packages)"
+    return 0
+  fi
+
+  # ============================================================================
+  # OFFICIAL REPOSITORY PATH (only when specific version requested)
+  # ============================================================================
+
+  # First, check if there's an old/broken repository that needs cleanup
+  if [[ -f /etc/apt/sources.list.d/mariadb.sources ]] || [[ -f /etc/apt/sources.list.d/mariadb.list ]]; then
+    local OLD_REPO_VERSION=""
+    OLD_REPO_VERSION=$(grep -oP 'repo/\K[0-9]+\.[0-9]+(\.[0-9]+)?' /etc/apt/sources.list.d/mariadb.sources 2>/dev/null || \
+                       grep -oP 'repo/\K[0-9]+\.[0-9]+(\.[0-9]+)?' /etc/apt/sources.list.d/mariadb.list 2>/dev/null || echo "")
+
+    # Check if old repo points to a different version
+    if [[ -n "$OLD_REPO_VERSION" ]] && [[ "${OLD_REPO_VERSION%.*}" != "${MARIADB_VERSION%.*}" ]]; then
+      msg_info "Cleaning up old MariaDB repository (was: $OLD_REPO_VERSION, requested: $MARIADB_VERSION)"
+      cleanup_old_repo_files "mariadb"
+      $STD apt update || msg_warn "APT update had issues, continuing..."
+    fi
   fi
 
   # Scenario 1: Already installed at target version - just update packages
@@ -3710,9 +3778,7 @@ EOF
     remove_old_tool_version "mariadb"
   fi
 
-  # Scenario 3: Fresh install or version change
+  # Scenario 3: Fresh install or version change with specific version
-  msg_info "Setup MariaDB $MARIADB_VERSION"
-
   # Prepare repository (cleanup + validation)
   prepare_repository_setup "mariadb" || {
     msg_error "Failed to prepare MariaDB repository"
@@ -3740,21 +3806,37 @@ EOF
 
   # Install packages with retry logic
   if ! install_packages_with_retry "mariadb-server" "mariadb-client"; then
-    # Fallback: try without specific version
+    # Fallback: try distribution packages
-    msg_warn "Failed to install MariaDB packages from upstream repo, trying distro fallback..."
+    msg_warn "Failed to install MariaDB $MARIADB_VERSION from official repo, falling back to distribution packages..."
     cleanup_old_repo_files "mariadb"
     $STD apt update || {
       msg_warn "APT update also failed, continuing with cache"
     }
-    install_packages_with_retry "mariadb-server" "mariadb-client" || {
+    if install_packages_with_retry "mariadb-server" "mariadb-client"; then
-      msg_error "Failed to install MariaDB packages (both upstream and distro)"
+      local FALLBACK_VERSION=""
+      FALLBACK_VERSION=$(mariadb --version 2>/dev/null | grep -oP '\d+\.\d+\.\d+' | head -n1 || echo "distro")
+      msg_warn "Installed MariaDB $FALLBACK_VERSION from distribution instead of requested $MARIADB_VERSION"
+      _setup_mariadb_runtime_dir
+      cache_installed_version "mariadb" "$FALLBACK_VERSION"
+      msg_ok "Setup MariaDB $FALLBACK_VERSION (fallback to distribution packages)"
+      return 0
+    else
+      msg_error "Failed to install MariaDB packages (both official repo and distribution)"
       return 1
-    }
+    fi
   fi
 
+  _setup_mariadb_runtime_dir
+  cache_installed_version "mariadb" "$MARIADB_VERSION"
+  msg_ok "Setup MariaDB $MARIADB_VERSION"
+}
+
+# ------------------------------------------------------------------------------
+# Helper function: Configure MariaDB runtime directory persistence
+# ------------------------------------------------------------------------------
+_setup_mariadb_runtime_dir() {
   # Configure tmpfiles.d to ensure /run/mysqld directory is created on boot
   # This fixes the issue where MariaDB fails to start after container reboot
-  msg_info "Configuring MariaDB runtime directory persistence"
 
   # Create tmpfiles.d configuration with error handling
   if ! printf '# Ensure /run/mysqld directory exists with correct permissions for MariaDB\nd /run/mysqld 0755 mysql mysql -\n' >/etc/tmpfiles.d/mariadb.conf; then
@@ -3774,11 +3856,6 @@ EOF
       msg_warn "mysql user not found - directory created with correct permissions but ownership not set"
     fi
   fi
-
-  msg_ok "Configured MariaDB runtime directory persistence"
-
-  cache_installed_version "mariadb" "$MARIADB_VERSION"
-  msg_ok "Setup MariaDB $MARIADB_VERSION"
 }
 
 # ------------------------------------------------------------------------------