金宇澄第一次写这类入门教程是在不少朋友问过同一个问题之后：软件明明装好了，一打开DBeaver要连本地MySQL，填完root密码点“测试连接”，弹出满屏英文，什么“Public Key Retrieval is not allowed”，什么“Communications link failure”，看半天完全不知道从哪下手。更尴尬的是有人连MySQL服务都没启动，就以为DBeaver能自己把数据库“变”出来。
这篇我打算把整个链路串一遍：怎么装对MySQL、怎么让它在后台跑起来、DBeaver里连接参数怎么填、连接报错怎么排查，以及最后怎么真正创建出一张数据库表并往里插数据。文中所有操作都是我个人在Windows和Linux两种环境里实测过的步骤，也会把那些容易踩但不至于致命的小坑顺手标出来。这篇内容适合刚接触数据库、想把命令行的恐惧感放一放的新手，也适合那些以前都用Navicat，现在想换DBeaver却不知道从哪下手的同学。
1. 选型与定位：先弄明白DBeaver和MySQL分别扮演什么角色
1.1 DBeaver到底是什么级别的工具
DBeaver是一个图形化的数据库客户端，通过JDBC驱动连接各种数据库，官网定位是“Universal Database Tool”。所谓Universal，意思是它并不是MySQL专用客户端，PostgreSQL、SQLite、Oracle、SQL Server、MongoDB这些都能连。所以很多人电脑里只装一个DBeaver，就能对付工作和学习中的绝大部分数据库场景，这正是它越来越流行的原因。
和Navicat这类商业软件相比，DBeaver有一个非常明显的优势：社区版免费开源，且功能对日常开发完全够用。一般创建表、查询数据、导出导入、看执行计划这些都是基础能力，不需要付费。只有在需要NoSQL数据库图形化浏览、团队协同等更企业级功能时才需要企业版。对初学者来说，官网下载社区版（Community Edition）就够了，根本不用纠结授权问题。
另一个潜在优势是它的跨平台属性。Windows、macOS、Linux都有对应安装包，三个平台的操作逻辑几乎一样，不会出现换了系统就不会用的情况。这一点在团队协作里尤其省心，不管同事用什么系统，大家打开DBeaver看到的界面、按钮、快捷键都一样。
1.2 安装包和绿色版怎么取舍
到官网DBeaver Community下载页面，Windows用户常见两种格式：安装版（Installer）和免安装版（Zip Archive，俗称绿色版）。我的建议：新手首选安装版，双击一路Next即可，安装过程会自动关联文件类型、在开始菜单注册快捷方式，环境变量不用手动配置。
免安装版的好处是纯绿色，可以放U盘或移动硬盘里带着走，到哪台机器解压就能用。但它有几个隐藏成本——首次运行要在系统里找Java运行环境，如果机器没有JDK/JRE还得自己配；工作空间默认指向解压目录，如果哪天清理文件夹删掉了，连接配置全部丢光。我自己以前也喜欢用免安装版，但后来发现升级版本时需要保留工作空间和驱动目录，反而比安装版麻烦。所以除非你确实需要在多台电脑间移动使用，否则就选安装版。
还有一个容易忽略的点：DBeaver的“工作空间”概念。首次启动会问你把工作空间放在哪，默认是用户目录下的DBeaverData文件夹。所有数据库连接配置、驱动缓存、SQL脚本历史都存放在这里。记住这个位置，后面找驱动、备份连接配置都要用到。
1.3 客户端和服务端，先分清谁是“服务器”
DBeaver只是个客户端工具，它本身不提供数据库服务。MySQL是服务端，负责真正把数据存到磁盘、处理SQL请求。要连本地MySQL，前提是你的电脑里已经有一个正在运行的MySQL服务实例。很多新手第一次连接就报错，最大的原因不是DBeaver配置错了，而是MySQL服务压根没启动，或者MySQL根本没装成功。
打个比方：DBeaver是遥控器，MySQL是空调。遥控器做得再精致，空调没通电，按什么都没反应。后面的章节里我会一直围绕这个思路走：先确保MySQL服务端是好的，再用DBeaver来操作它。这个顺序千万别反了。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 本地MySQL安装与启动验证：装到能连上才算结束
2.1 下载安装包时别选“全家桶”
MySQL官网下载页面目前提供的是MySQL Installer for Windows和各个平台的独立安装包。Windows环境建议用MySQL Installer，它是个引导程序，可以选择安装哪些组件。很多新手图省事选Full（全部安装），结果装完一看，多了一堆MySQL Workbench、MySQL Shell、Visual Studio插件，未必都用得上，还占空间。
推荐选Server only。我们是配合DBeaver用的，DBeaver本身就充当了图形化客户端角色，MySQL Workbench不是必装的。装得越少，出问题的可能性越低。
另外一个需要关注的是MySQL版本。现在的MySQL 8.0系列是长期支持版本，稳定成熟；8.4又是新的LTS版。对学习和一般项目来说，8.0系列最不容易踩坑，网上资料也最多。不要为了追新安装最新的9.x Innovation版本，那些版本主要面向尝鲜，遇到问题能查到的文档都比较少。
2.2 端口、root密码和Windows服务，安装时就要定好
安装过程中有几个关键配置点，每一步都值得停下来想清楚：
- Port默认是3306。如果本机3306端口已经被其他程序占用，安装时会有提示，要改成3307之类的端口。改完之后请牢记，后面DBeaver连接时要填对应端口。
- Authentication Method一般选第一个，也就是Use Strong Password Encryption，这是MySQL 8默认的caching_sha2_password认证方式，安全级别高，后续通过DBeaver也能正常连。
- Root Password需要自己设置。本地开发环境建议设置一个稍微复杂但目前能记住的密码，大小写字母加数字即可。不要搞成生产环境那种随机字符串，否则第二天你就忘了。
- 配置Windows Service这一步，就是让MySQL以系统服务的方式运行。默认服务名是MySQL80，勾选“Start at System Startup”，开机自动启动。
安装完成后，任务管理器或服务管理里能看到MySQL服务在运行。如果没启动，在服务列表里找到MySQL服务，右键启动。
2.3 打开命令行验证：先证明MySQL自己是通的
很多人装完MySQL直接打开DBeaver，结果连不上，然后一直在DBeaver里面找问题，绕了一大圈。正确做法是先打开命令行，输入：
bash复制mysql -uroot -p
回车后输入刚才设置的root密码，如果能进入mysql>提示符，说明MySQL服务端正常。如果提示mysql不是内部或外部命令，说明MySQL的bin目录没加入系统PATH。Windows下需要：
- 找到MySQL安装目录，例如
C:\Program Files\MySQL\MySQL Server 8.0\bin； - 在系统环境变量PATH里追加这个路径；
- 重新打开CMD窗口再执行一次。
进入mysql命令行后，执行：
sql复制SELECT VERSION();
能看到类似8.0.36这样的结果，说明一切正常。这个时候再打开DBeaver，心里会踏实很多——至少知道问题不在MySQL那边。
Linux环境下的情况稍有不同。用apt安装的MySQL，可以通过systemctl status mysql查看状态服务，连接时偶尔会遇到ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock'，大概率是服务没启动，执行sudo systemctl start mysql即可。macOS用Homebrew装的话，brew services start mysql是常用的启动方式。
3. DBeaver新建本地MySQL连接：参数、驱动下载与高频报错排查
3.1 新建连接窗口里每个字段代表什么
打开DBeaver，点击工具栏左上角的“新建连接”图标（是一个带加号的插头图标），在数据库类型列表里选择MySQL。这里会看到MySQL和MySQL兼容类两个分支，选MySQL即可。
进入连接设置主界面后，需要关注的是：
- Host：localhost 或 127.0.0.1。既然是连本地，这两个写法等价。
- Port：3306。如果安装MySQL时改过端口，这里要改成一致。
- Username：root。
- Password：root密码，填写后可以勾选“保存密码”，省得每次连接都要输。
- Database：这里可以先不填。留空表示连接整个MySQL实例，登录后能看到所有数据库；填了某个数据库名，后面浏览时默认定位到该库，但前提是这个库已经存在。
最下方有一个“URL”字段，DBeaver会自动生成JDBC连接串。默认内容类似：
code复制jdbc:mysql://localhost:3306
这个URL是Java连接MySQL的标准格式，理解它有助于排查后面的问题。点击“测试连接”，如果配置正确，会弹出“Connection successful”的提示框。
3.2 第一次连接时必定遇到的驱动下载问题
第一次点击测试连接，很大概率会弹出一个对话框：需要下载MySQL驱动文件，是否继续？部分新手看到这个弹窗会犹豫，有的直接关了，然后发现连接一直失败。
这个驱动在Java世界里叫MySQL Connector/J，是MySQL官方提供的JDBC驱动。DBeaver本身是Java程序，它需要通过这个驱动和MySQL服务端通信。第一次连接时DBeaver会自动从Maven中央仓库下载对应的jar包。正常情况下耐心等下载完成即可。
但有一个现实问题：国内网络访问Maven仓库有时很慢或者直接超时。如果驱动下载失败，不要慌，走手动路线：
- 到MySQL官网或Maven中央仓库下载
mysql-connector-j的jar包； - 在DBeaver菜单栏里打开“数据库” -> “驱动管理器”；
- 找到MySQL驱动，选中后点击“编辑”；
- 在“库”标签页里，通过“添加文件”把本地jar引进来；
- 重启连接，一般就能解决。
有些教程会让你去网上找一堆乱七八糟的jar包，其实完全没必要。使用官方Connector/J版本即可，驱动版本和MySQL服务端版本不需要精确对应，选择较新的驱动兼容性通常都很好。
3.3 高频报错：不是每个错误都要重新安装软件
我见过不少人在群里提问，贴出报错截图就跟着一句“DBeaver坏了”或者“MySQL坏了”，但其实绝大多数连接问题并不复杂。下面几个是本地连接MySQL时出现频次最高的报错，附上我的排查思路。
| 报错信息 | 出现原因 | 处理方法 |
|---|---|---|
| Public Key Retrieval is not allowed | MySQL 8默认使用caching_sha2_password认证，JDBC驱动默认不允许通过网络获取公钥 | 连接设置里选择“驱动属性”，将allowPublicKeyRetrieval设为true，useSSL设为false |
| Communications link failure | MySQL服务未启动、端口错误、防火墙拦截 | 先确认MySQL服务在运行，再用telnet或ping测端口通不通 |
| Access denied for user 'root'@'localhost' | 用户名或密码错误 | 回命令行用root正确密码登录一次，确认密码没记错 |
| Connection refused | 服务没启动，或者Host填了不存在的地址 | 本地连接推荐localhost，检查3306监听状态 |
| Could not create connection to database server | 驱动版本过旧，或驱动与MySQL8的认证方式不兼容 | 升级Connector/J到8.0以上版本，再试一次 |
最经典的就是Public Key Retrieval is not allowed。这个报错我帮人排查过很多次，根源是MySQL 8换了默认认证插件，而旧版JDBC驱动默认不允许明文获取公钥。解决办法不一定需要改MySQL用户认证方式，更安全的方式是在DBeaver驱动属性里做如下修改：
在连接编辑界面，切到“驱动属性”标签页，找到allowPublicKeyRetrieval，把值从false改为true；再找到useSSL，把值设为false。改完点“测试连接”，基本就通了。
3.4 连接成功后的界面，先认识几个关键区域
连接成功后，左侧“数据库导航器”里会出现当前连接的层级树，顶层是连接名，下面是数据库列表。MySQL系统自带的information_schema、mysql、performance_schema等库都会显示出来，不要删，那是MySQL内部运行要用的。
展开某个数据库后，能看到“表”、“视图”、“存储过程”等分类节点。双击一张表可以在右侧打开数据浏览页，点“列”标签可以看表结构。这些后面建表时都会用到。
在导航器顶部有一排工具栏图标，尤其要记住“新建SQL编辑器”的按钮，形状是一张带铅笔的白纸。点开它，右侧会打开一个空白的SQL编辑窗口，之后写建表、查询SQL都在这里完成。
4. 创建数据库和数据表：会可视化操作，也要会写DDL
4.1 先建库：字符集是你未来三年要不要跟乱码搏斗的分水岭
在第一张表建立之前，先得有数据库。DBeaver里新建数据库有两条路：
路径一，可视化操作。在左侧导航器里，右键点击连接根节点或某个现有数据库，选择“新建数据库”。在弹出的窗口里填数据库名称，重点看“字符集”下拉框，选择utf8mb4，排序规则选utf8mb4_general_ci或utf8mb4_0900_ai_ci都行。
路径二，SQL语句。打开SQL编辑器，输入：
sql复制CREATE DATABASE IF NOT EXISTS study_db
DEFAULT CHARACTER SET utf8mb4
DEFAULT COLLATE utf8mb4_general_ci;
执行后，左侧导航器刷新一下，study_db就会出现在列表里。
为什么字符集要强调utf8mb4？这是很多人第一次建库时没注意、后来悔得肠子都青了的地方。MySQL里的utf8并不是真正的全量UTF-8，它最多只能存3字节的字符——这意味着很多生僻字和emoji表情根本存不进去。utf8mb4才是真正意义上兼容4字节UTF-8字符的编码。在项目里如果你想让用户昵称支持emoji，或者存一些带特殊符号的文本，utf8mb4是没得商量的选择。
4.2 建表前先想清楚的字段设计：用一个学生表当例子
假设我们要为业务建一张学生表，包含这些信息：学号、姓名、年龄、邮箱、注册时间。设计时需要考虑每个字段用什么MySQL数据类型，哪些字段不能为空，哪个字段做主键。
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | INT | 自增主键，数字学号 |
| name | VARCHAR(50) | 学生姓名，最长50个字符 |
| age | TINYINT UNSIGNED | 年龄范围在0-255之间，TINYINT足够 |
| VARCHAR(100) | 邮箱，可能为空 | |
| create_time | DATETIME | 注册时间，默认当前时间 |
id字段一定是主键，而且是自增主键，这是绝大多数表的标配。name用VARCHAR而不是CHAR，因为VARCHAR是变长存储，能省空间。age用TINYINT就够了，INT对于年龄来说是浪费。create_time设置默认值CURRENT_TIMESTAMP，插入数据时不用手动维护时间，数据库自动填。
4.3 可视化建表操作：右键、加列、保存
回到DBeaver，在study_db数据库下的“表”节点上右键，选择“新建表”。右侧会打开一个建表编辑器，最下面是一个可编辑的字段网格。点击“列”标签，然后逐行填字段名、类型：
- 第一行填
id，类型选INT，在下面属性里找到“自动增量”，勾选上；然后把“主键”也勾选上。这里的自动增量就是MySQL里的AUTO_INCREMENT，自增从1开始。 - 第二行填
name，类型VARCHAR，长度设50，“不允许为空”勾选上。 - 第三行填
age，类型TINYINT UNSIGNED，允许为空。 - 第四行填
email，类型VARCHAR，长度100。 - 第五行填
create_time，类型DATETIME，默认值设置为CURRENT_TIMESTAMP。
填完点击Ctrl+S保存，DBeaver会弹出一个SQL预览窗口，显示将要执行的建表语句，点击“执行”。左侧刷新后，右键新建的表，选“查看表结构”，能看到刚才设计的所有字段。
有个细节：在可视化编辑器里，字段别名、注释这些信息可能默认在“高级”或“注释”标签里，如果找不到不用着急，表结构建立后随时可以通过ALTER TABLE补注释。
4.4 为什么你一定要会用SQL写建表语句
可视化方式适合新手练手，但我不建议长期只靠图形界面。原因很简单：真实项目中建表脚本要进版本控制，同事之间要能通过一个SQL文件复现表结构，这些都是图形界面替代不了的。
打开SQL编辑器，输入下面这条完整的DDL语句：
sql复制CREATE TABLE `student` (
`id` INT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
`name` VARCHAR(50) NOT NULL COMMENT '姓名',
`age` TINYINT UNSIGNED DEFAULT NULL COMMENT '年龄',
`email` VARCHAR(100) DEFAULT NULL COMMENT '邮箱',
`create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '注册时间',
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='学生表';
逐段解释一下：
AUTO_INCREMENT表示自增列，插入数据时可不用给id值，数据库从1开始自动递增。NOT NULL和DEFAULT NULL控制字段约束。COMMENT是给字段加注释，数据库层面的字段说明，养成写注释的习惯对后续维护非常有用。PRIMARY KEY (id)指定主键是id列。ENGINE=InnoDB指定存储引擎，InnoDB支持事务和外键，8.0默认就是InnoDB，显式写出来更清晰。DEFAULT CHARSET=utf8mb4确保表级默认字符集是正确的，防止从MySQL全局变量继承到错误设置。
然后点击SQL编辑器工具栏的执行按钮，或者按Ctrl+Enter执行当前语句。执行成功后在左侧导航器右键“刷新”，student表就出来了。
执行多条语句时，我发现DBeaver的快捷键需要单独说一句：Ctrl+Enter是执行当前选中或光标所在的SQL语句，Alt+X是整个SQL脚本全部执行。如果你写了多条语句只想跑其中一条，千万别顺手按Alt+X。
4.5 通过ER图和表结构页快速检查设计
建完表，建议立刻用DBeaver自带的ER图检查一遍。右键表名，选择“查看关系图”，DBeaver会用图形方式展示当前表或整个库的表结构。刚开始可能只有一张表孤零零地显示，但后续表多了以后，通过这个视图能直观看到外键关系、字段依赖，比盯着SQL文本高效得多。
回顾表结构是否有问题还有一个办法：右键表，选择“生成SQL” -> “DDL”。DBeaver会把当前表的完整建表语句重新生成一遍。如果你发现生成的DDL里有自己没写进去的默认值或约束，说明可视化编辑时某个属性没设对，这是排查表结构问题非常好用的手段。
5. 表的日常操作：插数据、改结构、导出DDL，以及几个高频疑问
5.1 插两条数据试试，检查表能不能正常写入
建表成功只是第一步，往表里插点数据，确认整条链路真的通畅才放心。SQL编辑器里执行：
sql复制INSERT INTO student (name, age, email) VALUES ('张三', 20, 'zhangsan@example.com');
INSERT INTO student (name, age, email) VALUES ('李四', 21, 'lisi@example.com');
注意没有给id和create_time赋值，因为id自增，create_time有默认当前时间。执行完成后，双击左侧的student表，或者执行一句：
sql复制SELECT * FROM student;
能看到两行数据，id自动生成了1和2，create_time自动填充了插入时的时间。如果中文显示成乱码，优先检查连接URL中是否带了characterEncoding=UTF-8参数，以及表、库字符集是否为utf8mb4。绝大多数本地开发乱码问题都是这两个地方不一致导致的。
5.2 表结构设计有遗漏？ALTER TABLE帮你补
建完表、插了数据才发现漏了字段，这种情况太常见了。例如学生表里没存手机号，需要新增一列，执行：
sql复制ALTER TABLE student
ADD COLUMN phone VARCHAR(20) NULL COMMENT '手机号' AFTER email;
AFTER email意思是把phone字段加到email列后面。如果不指定位置，新列会被追加到表的最后，顺序上就不太好看了。
如果想把age字段的默认值从NULL改成18，可以执行：
sql复制ALTER TABLE student
MODIFY COLUMN age TINYINT UNSIGNED NOT NULL DEFAULT 18 COMMENT '年龄';
这类ALTER TABLE操作建议先确认表里已有数据不会因为类型修改而溢出或截断，再动手执行。比如原来VARCHAR(50)的字段要改成VARCHAR(10)，已有数据超过10个字符的话，执行会报错或截断，有数据丢失风险。
5.3 DBeaver里导出DDL的习惯，越早养成越好
我见过不少同学，都是直接在Navicat或DBeaver里把表建好后就不管了。等到换库、同步环境、给同事复现数据模型时，才想起来要“把数据库导出来”。DBeaver有很完善的导出能力，单表单库都能处理。
最简单的导出方式：在目标表上右键，选择“生成SQL” -> “DDL”。DBeaver会打开一个新的SQL编辑器，里面是完整的建表脚本。复制出来保存成student.sql文件，这就是这张表的表结构快照。
数据库整体导出可以用“工具”菜单里的“转储数据库”功能，选择要导出的库，DBeaver会生成包含建库、建表、插入数据在内的完整脚本。这个功能日常不常用，但熟悉它很有必要。
5.4 顺手回应几个频繁被问到的细节点
我注意到不少人会搜索“mysql中int+5”，其实这多半是在建表时看到了INT(5)这种写法。INT后面的数字不是限制存储范围，而是显示宽度，配合ZEROFILL属性时才有效果。比如INT(5)配合ZEROFILL，数字1会显示为00001。它不代表该列最多只能存5位数，普通场景直接写INT就行，不必纠结括号里的数字。
有人问存储过程怎么在DBeaver里跑。第一次写存储过程，直接在SQL编辑器里粘贴带BEGIN...END块的代码，再按Ctrl+Enter，有时候会很懵——它只执行了一部分就开始报错。原因是DBeaver默认把分号当成语句分隔符，而存储过程体内部也有分号。解决办法是在SQL编辑器工具栏中把语句分隔符从分号改成//，写完存储过程后再改回来。这个属于进阶操作，可以先记下来。
还有的人问数据库表迁移的问题。假如你要把MySQL里的表迁移到另一个数据库系统，最省事的路径之一，是在源库里把DDL和数据分别导出，然后到目标库里通过对应客户端执行。但要注意不同数据库的数据类型和语法存在差异，导出脚本不一定能原样跑通，字段类型对照、字符集调整这些大概率都要人工过一遍。DBeaver在这里能帮你做的是先看明白源表所有字段细节，别拿着一张残缺的表结构图去做迁移。
最后分享一个我个人的工作习惯：每次在DBeaver里创建完表或修改完表结构，我都会立刻把DDL导出，放到项目的sql/目录下统一管理。刚开始觉得这只是多此一举，直到有次同事把测试库表结构改乱了，我靠一份SQL文件十分钟就把表结构恢复原样。从那以后，这个习惯就一直保留下来了。如果你也是刚开始接触DBeaver和MySQL，建议从建第一张表起就顺手做这件事，后面会少踩很多坑。