phpstorm如何配置MariaDB连接环境（数据库兼容性）

PHPStorm 连接 MariaDB 需使用 mariadb-ja va-client 驱动（org.mariadb.jdbc.Driver）而非 MySQL 驱动；认证失败时应升级驱动至 3.0+ 并添加 allowPublicKeyRetrieval=true 等参数；URL 须含数据库名且用户需有 INFORMATION_SCHEMA.SELECT 权限。

PHPStorm 连接 MariaDB 时提示 “Driver not found” 或 “No database selected”

很多开发者第一次尝试时都会踩这个坑：PHPStorm 默认并不内置 MariaDB 驱动，它预装的是 MySQL 的 JDBC 驱动（mysql-connector-ja va）。问题在于，MariaDB 官方明确推荐使用自家的 mariadb-ja va-client。为什么？因为后者对 MariaDB 的独有特性——比如 SEQUENCE、CONNECT 引擎，以及高版本里的认证插件如 unix_socket 或 ed25519——支持得更加完整。直接套用 MySQL 驱动去连接 MariaDB 8.0 及以上版本，失败几乎是必然的。

那么，具体该怎么操作呢？

• 首先，在数据库工具窗口点击 “+” → “Data Source → MariaDB”。注意，这里一定要选“MariaDB”，而不是“MySQL”。如果下拉列表里压根没有 MariaDB 这个选项，那就说明驱动根本没加载上，需要手动添加。
• 接下来，通常会看到右下角有个 Download missing driver files 的按钮。这里有个细节：从 PHPStorm 2022.3 版本开始，这个自动下载功能默认抓取的是 MySQL 驱动。所以，稳妥起见，最好关掉自动下载，改用手动方式。
• 手动方式就是去 MariaDB 官网，下载最新的 mariadb-ja va-client-x.x.x.jar 文件。然后回到数据源配置页面，找到添加驱动的地方，通过 Driver Files → + → Custom JARs 的路径，把这个 JAR 文件添加进去。
• 最后，在 Driver class 一栏，正确填写 org.mariadb.jdbc.Driver。千万别填成 MySQL 的那个。

连接 MariaDB 10.6+ 报错 “Client does not support authentication protocol requested by server”

这个报错太经典了，本质上就是认证插件不兼容。MariaDB 从 10.4 版本开始，默认启用了更安全的认证方式，比如本地的 unix_socket 或者远程的 ed25519。而老版本的 JDBC 驱动根本不认识这些新协议，结果就是即使用户名密码百分百正确，连接请求也会被服务器无情拒绝。

解决思路可以分两步走：

立即学习“PHP免费学习笔记（深入）”；

• 先确认用户的认证方式：在数据库服务器上执行这条 SQL：

  SELECT User, Host, plugin FROM mysql.user WHERE User = 'your_user';

  如果查出来的 plugin 字段显示是 ed25519 或 unix_socket，那就别指望用默认驱动直接连上了。
• 临时解决方案（适合开发环境）：如果你有 root 权限，可以登录 MariaDB，将这个用户的认证插件改回旧的 mysql_native_password：

  ALTER USER 'your_user'@'%' IDENTIFIED VIA mysql_native_password USING PASSWORD('your_pass');

• 长期推荐的方案：保持服务器端先进的认证插件不变，而是在 PHPStorm 的连接 URL 后面追加几个关键参数。完整的 URL 看起来应该是这样：jdbc:mariadb://your_host:3306/your_db?allowPublicKeyRetrieval=true&useSSL=false&serverTimezone=UTC。同时，务必确保你使用的驱动是 mariadb-ja va-client 3.0+ 版本，因为它已经原生支持 ed25519 认证了。

测试连接成功但看不到表 / schema 列表为空

这种情况最让人头疼：明明测试连接显示“成功”，但左侧的数据库面板却空空如也。这通常不是连接本身的问题，而是权限不足或者连接参数有遗漏。PHPStorm 的数据库面板需要查询 INFORMATION_SCHEMA 来获取元数据，而 MariaDB 默认会对普通用户的这类访问做限制。

遇到这个问题，请按顺序检查以下几点：

• URL 里必须明确指定数据库名：这是一个非常常见的疏忽。URL 应该是 jdbc:mariadb://localhost:3306/your_db_name?useSSL=false 这样的格式。如果只写到端口号，像 jdbc:mariadb://localhost:3306/，连接虽然能建立，但因为没有指定默认库，PHPStorm 自然不知道去显示哪个库的表。
• 检查用户权限：连接用户至少需要对目标数据库有 SELECT 权限。更重要的是，从 MariaDB 10.5 开始，普通用户默认无法访问 INFORMATION_SCHEMA 视图。你需要显式授权：

  GRANT SELECT ON INFORMATION_SCHEMA.* TO 'your_user'@'%';

• 暂时关闭 SSL 选项：在 PHPStorm 的设置里，如果勾选了 Use SSL，但服务器端并没有正确配置证书，连接可能会以一种“静默失败”的方式通过，但无法获取数据。建议在排查问题时，先关掉 SSL，等基础连接和列表显示都正常后，再回来配置安全连接参数。

PHPStorm 中执行 SQL 提示 “Unknown system variable ‘sql_mode’”

这个错误提示是个明确的信号：驱动和 MariaDB 服务器之间的协议协商失败了。最常见的原因，要么是错误地使用了 MySQL 驱动来连接 MariaDB，要么就是驱动版本实在太老了（比如还在用 mysql-connector-ja va 5.1）。MariaDB 并不完全支持 MySQL 的所有系统变量别名，而一些旧的驱动却硬编码了这些查询语句。

验证和修复的步骤很清晰：

• 先确认数据库版本：在 PHPStorm 的数据库控制台里执行 SELECT VERSION();。确认返回的是类似 10.x.x-MariaDB 的字符串，而不是 8.0.x（MySQL）。
• 彻底重建数据源：最干脆的办法是删掉当前有问题的数据源配置，从头新建一个。这次，严格使用 mariadb-ja va-client 驱动，并确保驱动版本足够新。
• 避免驱动混用：不要在同一个 PHPStorm 项目里，让 MySQL 和 MariaDB 的数据源配置共享同一份驱动 JAR 文件，这很容易引起冲突。
• 升级 IDE：如果上述步骤都做了问题依旧，可以考虑将 PHPStorm 升级到 2023.2 或更高版本，这些版本对 mariadb-ja va-client 3.1 及以上的支持更加完善。

说到底，连接 MariaDB 时最棘手的往往不是连不上，而是连上了之后，却读不到表结构，或者执行 DDL 语句时报一些奇怪的语法错误。这时候，十有八九是驱动层在“张冠李戴”，把 MariaDB 的语句（比如定义表时的 ENGINE=InnoDB）当成 MySQL 的语法来解析了。所以，盯紧驱动的来源和版本，往往比反复调整 URL 参数里的那些“小开关”要重要得多。