Summary

Lando's ecosystem is experiencing a systemic compatibility issue between MariaDB and MySQL CLI tools. Historically, Lando has relied on the fact that MariaDB's mysql client worked seamlessly with MySQL servers, and the PHP plugin ships service images with mariadb-client symlinked as mysql. However, recent versions of MariaDB and MySQL have diverged significantly, breaking this assumption across multiple plugins.

The Root Problem

1. PHP service images use mariadb-client with symlinks (mysql → mariadb, mysqldump → mariadb-dump)
2. MariaDB 10.11+ is diverging from MySQL compatibility:
   • SSL/TLS is now enforced by default
   • The mysql command name is deprecated (will be removed in future releases)
   • Dump file formats have changed
3. MySQL 8.4+ has breaking changes:
   • default_authentication_plugin=mysql_native_password is deprecated/removed
   • New authentication requirements

How This Manifests

SSL/TLS Errors

When connecting to servers that don't support SSL:

ERROR: SSL is required but the server doesn't support it

Deprecated Command Warnings

mysql: Deprecated program name. It will be removed in a future release, use '/usr/bin/mariadb' instead

Version Mismatch Issues

Appserver client version doesn't match database server version, causing:

• Dump file incompatibility
• Unknown variable errors
• Feature mismatches

MySQL 8.4 Failures

ERROR [MY-000067]: unknown variable 'default_authentication_plugin=mysql_native_password'

Related Issues Across the Ecosystem

Proposed Approaches

Approach 1: Database-Aware Client Installation

Concept: Detect the database service type/version and install the matching native client in the appserver.

Implementation:

1. Add a hook that detects when a project uses mysql or mariadb services
2. During appserver build, install the appropriate client:
   • For MySQL databases → install mysql-client from MySQL APT repo
   • For MariaDB databases → install mariadb-client from MariaDB repo
3. Match the major version of the database server

Pros:

• Clean separation between MySQL and MariaDB
• Version matching eliminates compatibility issues
• Future-proof as the two diverge further

Cons:

• Increased build time
• Requires maintaining version detection logic
• More complex implementation

Approach 2: Dual Client Installation

Concept: Install both MySQL and MariaDB clients, with smart command routing.

Implementation:

1. Install both mysql-client and mariadb-client in PHP images
2. Create wrapper scripts that detect the target server type and use appropriate binary
3. Default to native client based on detected server

Pros:

• Works with both database types without rebuilds
• Fallback options available

Cons:

• Larger image size
• Complex routing logic
• Potential for confusion

Approach 3: User-Configurable Client Selection

Concept: Add a new configuration option for users to specify their preferred database client.

Implementation:

config:
  database: mysql:8.4
  database_client: mysql  # or 'mariadb' - defaults based on database type

Pros:

• User control
• Simple to implement
• Backward compatible

Cons:

• Requires user awareness of the issue
• Doesn't solve the problem automatically

Approach 4: SSL Compatibility Layer

Concept: Address the immediate SSL issues while maintaining current architecture.

Implementation:

1. Add --skip-ssl or --ssl-mode=DISABLED flags to relevant commands
2. Create a .cnf file with SSL settings in the appserver
3. Update helper scripts to handle SSL gracefully

Pros:

• Quick fix for immediate pain
• Minimal changes required

Cons:

• Doesn't address version mismatch
• Doesn't address deprecated command warnings
• Band-aid solution

Approach 5: Dedicated Database Tooling Service

Concept: Create a sidecar service specifically for database operations.

Implementation:

1. Spin up a lightweight container with matching database client tools
2. Route lando db-import, lando db-export, etc. through this service
3. Container version matches the database service version

Pros:

• Perfect version matching
• Doesn't bloat appserver image
• Clean separation of concerns

Cons:

• Additional container overhead
• Complexity in routing commands
• May not solve appserver-initiated DB operations (e.g., Drush)

Action Items

• Audit all helper scripts for hardcoded mysql/mysqldump commands
• Create a utility function to detect database type and version
• Implement database-client matching in @lando/php or @lando/core
• Update recipes to handle MySQL 8.4+ authentication changes
• Document workarounds for affected users
• Consider adding this to the FAQ/troubleshooting docs

References

• MariaDB 10.11 Release Notes - SSL changes
• MySQL 8.4 Release Notes - Authentication plugin deprecation
• MariaDB Deprecation of mysql command

Note: This issue consolidates reports from across the Lando plugin ecosystem. Please reference this meta issue when working on fixes in individual plugins to ensure coordination.