第 01 章连接

连接就是「一个数据库账号 + 一套访问参数」的存档。你可以存很多个连接， 同时打开好几个，用工具栏最左边的下拉在它们之间切换。

启动界面：连接列表

App 启动后，如果上次退出时没有留下需要恢复的现场，就会显示这个列表。 列表里每一项都是一个存好的连接。

连接列表界面 TableLite TableLite macOS 原生 MySQL / MariaDB 客户端 🔍 搜索连接… 本地开发 root@127.0.0.1:3306/app_dev › 预发布 app@10.0.1.5:3306/app_staging（经 bastion.example.com） › 🔒 生产 app@10.0.2.5:3306/app_prod · 只读 › + 新建连接 双击连接项进入工作区 · 右键有编辑、复制、删除等操作 1 2 3 4 5
图 1-1　连接列表。带锁的「生产」是只读连接。
#控件作用
1搜索框 按名称和下面那行摘要做模糊过滤。输入 prod 能同时匹配到名字里带 prod 和主机路径里带 prod 的连接。找不到任何连接时列表区显示「没有匹配的连接」。
2连接项 一行一个连接。双击进入工作区；单击只是选中；右键有四项菜单：编辑…、复制为新连接、删除、在 Finder 中显示配置文件。
3状态圆点 显示这个连接当前的状态，四种含义见下方表格。这个圆点在整套界面里含义一致，工具栏的连接下拉里也是它。
4新建连接 打开连接配置表单，从空白开始填。快捷键 ⌘N。
5锁图标与摘要 名称前的 🔒 表示这个连接是只读模式（见第 9 章）。名称下面一行是 用户@主机:端口/数据库；走 SSH 隧道的连接会追加 （经 跳板机）。

四种连接状态

连接状态的四种显示 未连接 保存着但当前没连 连接中 正在建隧道或连库 已连接 一切正常 异常 断开或隧道挂了
图 1-2　连接状态的四种显示。异常状态时，内容区会盖一层灰色遮罩并给出「重新连接」按钮。

连接配置表单

新建或编辑连接时打开的表单。字段按用途分成三块， 从上到下依次填：这块连接叫什么、怎么连 MySQL、要不要走 SSH 隧道。

连接配置表单 编辑连接 基本信息 名称 本地开发 颜色 绿 ▾ 只读 禁止一切写操作，详见第 9 章 MySQL 主机 127.0.0.1 端口 3306 用户 root 密码 •••••••••• 保存到钥匙串 数据库 app_dev （可以留空） 字符集 utf8mb4 ▾ 使用 SSL 跳过证书校验 服务器用自签证书时才勾 连接超时 10 秒 查询超时 300 秒 保持连接活跃（每 30 秒发送心跳） SSH 隧道 通过 SSH 连接 勾上以后下面这些字段才可用 SSH 主机 bastion.example.com 端口 22 SSH 用户 deploy 认证方式 使用 ~/.ssh/config 与 ssh-agent （推荐，平时怎么连就怎么连） 使用私钥 ~/.ssh/id_ed25519 选择… 使用密码 （密码保存在系统钥匙串里） 使用 ssh config 别名 跳板机 user@proxy:22 测试连接 取消 保存 1 2 3 4 5 6
图 1-3　连接配置表单。三块卡片从上到下是「基本信息 → MySQL → SSH 隧道」。
#区域说明
1基本信息 名称是列表里显示的名字（必填）。颜色会影响主窗口那条颜色带，建议生产库配红色。只读勾上后这个连接不能做任何写操作。
2MySQL 主机、端口、用户必填。「数据库」可以留空，那样连上以后会自动选中第一个能访问的库。勾了「保存到钥匙串」密码才会持久化，否则只在本次运行期间记住。
3SSH 隧道 勾上「通过 SSH 连接」后，数据库会被当成在跳板机的内网里，TableLite 会在本机开一个临时端口把流量转发过去。详细行为见第 10 章。
4认证方式 三选一。默认「使用 ssh config 与 ssh-agent」，此时主机、端口、用户、密钥全部由你的 ~/.ssh/config 决定，和在终端里敲 ssh 别名 完全一致。
5测试连接 用当前表单里的配置做一次完整探测，结果分步显示（见下一节）。测试通过才会保存密码，失败不保存。
6保存 写入配置文件并返回。表单里任何一项校验不通过时，这个按钮是灰的，红色提示会直接标在出问题的字段下方。

各项字段的默认值与约束

字段必填默认值说明
名称是—连接列表里显示的名字
颜色否无色用于颜色带，仅作视觉区分
只读否关见 第 9 章
主机 / 端口是— / 3306端口必须是 1–65535 的整数
用户是—
密码否空可以空着，首次连接时再输入
保存到钥匙串否勾选不勾则密码只在本次运行期间有效
数据库否空留空时连上后默认选中第一个可访问的库
字符集否utf8mb4影响中文与 emoji 的读写
使用 SSL否勾选服务器使用自签证书时再搭配下一项
跳过证书校验否不勾仅在服务器使用自签证书时打开
连接超时否10 秒建立 TCP 连接的最长等待时间
查询超时否300 秒超时后自动中止查询
保持连接活跃否勾选定期发心跳，避免被服务器单方面断开
心跳间隔否30 秒仅在上项勾选时生效

测试连接

点「测试连接」后，TableLite 会按顺序做三件事，每做完一步就在面板里打一个勾。 哪一步失败就停在哪儿，并且把底层错误原样贴出来。

测试连接的结果面板 测试连接 SSH 隧道建立成功 本地转发端口 127.0.0.1:53142 MySQL 连接成功 读取到服务器信息 MySQL 8.0.36 · utf8mb4 关闭 保存并连接 测试连接 SSH 隧道建立成功 MySQL 连接失败 错误 1045：Access denied for user 'root'@'localhost' (using password: YES) SQLSTATE 28000 查看详细输出 关闭
图 1-4　左边是全部通过，右边是 MySQL 那一步失败。失败的原始错误文本不做翻译、不截断。
测试连接的两条规矩
  • 不检查数据库是否存在。库名写错不算连接失败——能连上服务器就算通过。否则你会因为一个拼写错误以为整个连接配置有问题。
  • 测试用的连接用完立刻关掉。不会在服务器上挂着一堆空闲会话，也不会覆盖你当前正在用的那个连接。

建立与断开连接

连上的时候发生了什么

双击连接后，状态栏依次显示三条进度：

  1. 正在建立 SSH 隧道… —— 没启用 SSH 时这一步跳过
  2. 正在连接 MySQL…
  3. 正在读取服务器信息… —— 库列表、版本、字符集

失败时停在第几步就是哪一步出问题，已经建好的资源（比如 SSH 隧道）会保留， 等你关掉对话框再一起清理。

断开

自动断开

一个连接空闲超过 5 分钟，并且没有任何标签在用它，TableLite 会自动断开它， 把服务器上的连接数还回去。可以在偏好里关掉这个行为。

心跳失败不会自动重连

保活心跳失败时，TableLite 只把连接标成红点并提示你，不会擅自重连。 重连可能让你以为还在原来的会话里（比如临时表、事务都没了），所以这件事交给你决定。

重新连接

同时连多个数据库

删除连接

删除会同时清掉保存在系统钥匙串里的 MySQL 密码和 SSH 凭据，所以需要确认：

删除连接确认弹窗 确定要删除连接「生产」吗？ 同时会删除保存在系统钥匙串里的密码。 此操作不可撤销。 取消 删除
图 1-5　删除连接的确认弹窗。按钮措辞要具体，不用「确定 / 取消」。

首次启动

一个连接都没有的时候，启动界面会显示一段简短说明加一个「新建连接」按钮， 不做多步向导，也没有教学演示。填完第一个连接、测试通过、点「保存并连接」就进入工作区。

不做的事
  • 没有连接分组
  • 没有连接的导入 / 导出文件
  • 没有命令行 deeplink（tablelite://connect/xxx 这类）

连接都在配置文件里，需要迁移时直接拷那个文件。