Delphi 13.1 安装 HeidiSQL 控件包：资源编译与异步查询

简介面向使用Delphi 13.1进行Windows桌面应用开发的程序员这份控件包将HeidiSQL的数据库管理能力集成到Delphi IDE中省去手工拼接SQL语句和切换外部工具的繁琐。资源共751个文件以234个pas源文件、44个dfm窗体定义为核心辅以35个dll运行库、大量png图标及界面素材压缩包大小29.8MB目录结构清晰便于按需引用对应模块。已有49人浏览学习。控件全面支持MySQL、MariaDB、PostgreSQL及SQL Server除基础的连接、查询、更新、删除外还提供多线程数据处理、异步数据库操作、数据同步、备份与恢复等高级功能能显著缩短大数据量场景下的响应时间直接拖拽组件即可完成数据库交互适合需要快速构建数据库管理界面或提升数据层开发效率的中高级开发者。包内同时包含编译脚本与安装配置实际使用时可先运行批处理完成IDE集成再逐步部署控件结合现有数据库管理场景可显著提高项目交付效率。1. Delphi 13.1 下的 HeidiSQL 控件包先搞懂 D123 到底是什么做 Delphi 开发的人迟早会撞上同一个尴尬写业务逻辑很快一到数据库操作就卡住不是 ADO 连接串配不明白就是想做个批量导入得自己拼半天的 SQL。这份 Delphi 13.1 控件之 HeidiSQL-12.12-D123.zip本质上是把 HeidiSQL 这个开源数据库管理工具的核心库封装成了能在 Delphi 13.1 IDE 里直接安装的 VCL 控件集。装上之后MySQL、MariaDB、PostgreSQL、SQL Server 这四类数据库都能在一个组件里统一连接和操作不需要再为每种数据库单独引第三方驱动。适合谁两类人最值一类是写桌面数据库工具、管理后台的 Delphi 业务开发者另一类是嫌 ODBC 配置麻烦、想直接用组件拖拽完成连接查询的工程实施人员。后面章节会把这包里的 bat 脚本、dpk 安装流程和异步查询用法逐个拆开。2. 控件包内部结构从文件清单反推它的编译逻辑2.1 D123 包的文件组成与各自职责拿到 zip 解压后第一眼看到的文件基本决定了这个包的安装方式。我在 Delphi 里装过几十个第三方控件包像这种带多个 bat 脚本的通常不是那种“双击安装即可”的成品组件而是源码包加构建脚本的组合。这包的根部文件包括 Clean.bat、build-res.bat、CompileResources_zip.bat、CompileResources.bat还有一堆 bmp 文件。这些 bmp 文件不是给用户看的图片资源而是安装到 IDE 后组件栏里显示的图标。installer-logo.bmp、installer-small-logo.bmp、donatebutton.bmp 这类是安装程序界面用的素材Page.bmp 和 VT XP.bmp 是向导页的背景图。真正跟编译相关的是那四个 bat它们分工很明确脚本名职责Clean.bat清除上一次编译产生的 dcuh、dcpil、dcu 等临时文件还原干净的源码树CompileResources.bat把 bmp、ico 等资源文件编译链接进组件包CompileResources_zip.bat与上一个脚本类似但输出打包好的 zip 资源文件build-res.bat构建资源文件的辅助入口通常被上面两个脚本调用多数人第一次装这个包最容易犯的错就是跳过 Clean.bat 直接跑编译脚本。结果就是 IDE 提示找不到某个 dcuh 文件或者安装完组件图标是空的。原因很简单上一轮编译残留的目标文件跟当前 Delphi 版本不匹配资源没重新生成。2.2 为什么资源编译这一步不能跳过Delphi 的 VCL 组件包安装时很多人关注的是 dpk 文件能不能编译通过却忽略资源文件bmp 图标的作用。资源文件不生成组件能装上但组件栏里是一排空白图标鼠标悬停也看不到名字。这还不是最严重的有些组件在构造函数里会加载资源资源缺失直接报 EResNotFound 错误。CompileResources.bat 做的事情就是把 Installer 相关的 bmp 图标编译进资源单元。bat 内部通常是调用了 brcc32.exe这是 Delphi 自带的资源编译器把 bmp 文件转成 .res 文件。我一般会先检查这个脚本里有没有硬编码的 Delphi 安装路径比如C:\Program Files (x86)\Embarcadero\Studio\23.0\bin\brcc32.exe如果本机 Delphi 13.1 安装路径不同就手动改一下再执行。提示跑 CompileResources.bat 前先确认执行环境。直接在资源管理器双击 bat 会闪退正确的做法是打开“RAD Studio 命令提示符”后再运行否则可能因为缺少环境变量报找不到 brcc32。2.3 包内控件支持的四类数据库与多线程特性HeidiSQL 控件区别于 Delphi 自带 dbGo 组件的地方在于它对多数据库的支持是内置的不是靠 ODBC 驱动桥接。D123 包在 Delphi 13.1 环境下支持的数据库类型包括 MySQL、MariaDB、PostgreSQL 和 Microsoft SQL Server。从摘要描述里能看到它还支持多线程数据处理和异步数据库操作。这两个特性在实践里意味着什么意味着一个耗时查询不会把 UI 线程卡死。老式做法是开一个 TThread在 Execute 里创建连接、执行 SQL、再通过 Synchronize 回传结果代码绕且容易出线程访问冲突。HeidiSQL 控件把异步操作封装在组件内部直接调用异步查询方法绑定事件拿返回结果即可。后面第 4 章会有具体写法。3. 编译安装全流程从源码包到 IDE 组件栏3.1 第一步用 Clean.bat 清掉历史编译残留安装任何 Delphi 源码包我建议把“先清理再编译”变成肌肉记忆。D123 包里解压出来的源码如果被别人编译过残留的 dcuh 文件很可能是在不同 Delphi 版本下生成的直接复用的结果千奇百怪。最常见的报错是F2589 Unit xxx was compiled with a different version of SysUtils。Clean.bat 做的事就是删掉当前目录下的*.dcu、*.dcpil、*.dcuh、*.bpl、*.res等构建产物。执行前瞄一眼 bat 内容确认删除范围没有包含源码 .pas 文件这属于基本风险排查。我碰到过某个控件包的 Clean.bat 写得不严谨把源码也删了从那以后我每跑一次清理脚本都会先打开看一遍。在 RAD Studio 命令提示符里执行cd /d D:\delphi\HeidiSQL-12.12-D123 Clean.bat执行后检查目录里应该只剩 .pas、.dpk、.bmp 和 bat 文件没有 .dcu。如果还有旧的 .dcu说明 Clean.bat 的清理范围不全手动执行del /s *.dcu *.dcpil *.dcuh兜底一次。3.2 第二步跑 CompileResources 编译资源文件清理干净后先编译资源再编译代码顺序不要反。资源文件是组件包的一部分先编 .res 再编 .dpk能避免安装组件时报资源找不到的错。ComplieResources.bat 和 CompileResources_zip.bat 的区别从名字上理解一个直接输出 .res 文件另一个输出 zip 格式的资源包。HeidiSQL 控件包里这两种都保留具体用哪个看它的主资源单元引用的是哪种格式。我的经验是优先跑不带 _zip 的那个如果编译 d sk 时报资源文件名不匹配再换另一个跑一次。CompileResources.bat跑完确认当前目录下新生成了 .res 文件比如 D123.res。如果没生成八成是 bat 里的路径不对。检查 bat 里 brcc32.exe 的绝对路径是否指向 Delphi 13.1 的 bin 目录不对就改。3.3 第三步安装 dpk 到 Delphi 13.1 IDE资源文件就绪后找到 .dpk 文件。Delphi 13.1 下一般会区分设计期包和运行期包D123 这种控件包通常是一个 dpk 同时包含 design-time 和 runtime 代码。在 IDE 里选择 File → Open定位到 dpk 文件打开然后在 Project Manager 里右键点击 dpk 节点选择 Install。安装成功的标志是组件面板里出现新的控件页名字取决于 dpk 里注册的 unit 名称。我习惯在安装前先确认 dpk 底部有没有 requires 引用其他第三方包如果有得先把那些依赖包装上否则编译直接失败报找不到某某 .dcu。注意安装控件包时Delphi 13.1 的默认编译目标是 Win32。如果你的项目是 Win64安装完控件后第一次调用可能提示目标平台不一致。此时在 Project Manager 里给 dpk 添加 Win64 平台再重新编译一次否则切换到 64 位编译时控件会找不到。4. 代码接入连接、查询与异步操作的最小可用写法4.1 放置控件并配置数据库连接参数安装完成后从组件面板找到 HeidiSQL 相关控件拖到 Form 上。连接配置关键就三个属性数据库类型、主机地址、认证信息。在代码里初始化连接procedure TMainForm.FormCreate(Sender: TObject); begin HeidiSQLConn1.ServerType : stMySQL; // 可选 stMariaDB / stPostgreSQL / stMSSQL HeidiSQLConn1.Hostname : 127.0.0.1; HeidiSQLConn1.Port : 3306; HeidiSQLConn1.DatabaseName : app_db; HeidiSQLConn1.Username : root; HeidiSQLConn1.Password : your_password; HeidiSQLConn1.Connect; end;这里 ServerType 决定底层走哪套驱动协议不同数据库的默认端口不一样——MySQL 是 3306PostgreSQL 是 5432SQL Server 是 1433。Hostname 在跨机器调试时别写 localhost填 IP 或主机名避免本地连接串误导排查方向。4.2 执行一条查询并取回结果连接建立后查询可以直接挂在控件上执行procedure TMainForm.QueryButtonClick(Sender: TObject); var i: Integer; begin HeidiSQLQuery1.SQL.Text : SELECT id, name, created_at FROM orders WHERE status :st; HeidiSQLQuery1.ParamByName(st).AsString : paid; HeidiSQLQuery1.Open; for i : 0 to HeidiSQLQuery1.RecordCount - 1 do begin Memo1.Lines.Add(HeidiSQLQuery1.FieldByName(name).AsString); HeidiSQLQuery1.Next; end; end;这段代码里的:st是参数化查询写法不建议直接拼字符串。参数化有两个直接好处一是防注入二是让 SQL 缓存命中率更高。RecordCount 在返回大结果集时可能不准因为默认数据集不是一次性全部加载的。4.3 异步查询不卡 UI 的正确写法Delphi 老手都知道查询放主线程等于自杀。HeidiSQL 控件的异步操作模式值得专门提一下procedure TMainForm.AsyncQueryButtonClick(Sender: TObject); begin HeidiSQLQuery1.Async : True; // 开启异步模式 HeidiSQLQuery1.SQL.Text : SELECT COUNT(*) FROM big_table; HeidiSQLQuery1.ExecuteAsync( procedure begin Label1.Caption : HeidiSQLQuery1.Fields[0].AsString; end ); end;Async 属性设为 True 后ExecuteAsync 方法把查询甩到内部线程池执行完成后的匿名过程回到主线程更新 UI。这个写法替代了传统 TThread 加 Synchronize 的繁琐流程而且避开了手动管理线程生命周期这个最容易翻车的环节。要注意的是异步回调里不要再执行同步查询连同一个控件实例会冲突要查就再开一个控件实例。5. 避坑实录D123 包安装与使用中的几类典型问题5.1 编译报错找不到 brcc32.exe现象双击运行 CompileResources.bat命令行窗口一闪而过没有任何 .res 文件生成。 原因bat 里硬编码的 brcc32.exe 路径与当前机器 Delphi 安装目录不一致或者根本没有在 RAD Studio 命令提示符里执行。 解决用记事本打开 bat检查并修改其中的路径为C:\Program Files (x86)\Embarcadero\Studio\你的版本号\bin\brcc32.exe然后重新在 RAD Studio 命令提示符中执行。5.2 安装成功但组件栏图标空白现象dpk 编译安装过程无报错但组件面板上该控件页里的图标显示为空白占位。 原因CompileResources.bat 未执行或执行后 .res 文件未成功链接进包。Delphi 在加载包时找不到图标资源默认显示空白。 解决回到第 3.2 节重新执行资源编译确认 .res 文件生成然后右键组件包选择 Uninstall再重新 Install。图标资源加载发生在包加载阶段只重编译不重装不会生效。5.3 查询中文数据乱码现象通过控件查询 SQL Server 或 MySQL 里的中文字段返回结果是乱码。 原因多为字符集属性未设置。MySQL 5.7 以上默认 utf8mb4但控件连接串里可能仍按旧版 latin1 协商字符集。 解决连接初始化时显式设置字符集HeidiSQLConn1.Properties.Add(charsetutf8mb4);这里加的是连接级属性MySQL 和 MariaDB 都认 charset 参数。PostgreSQL 则是 client_encoding写法略有不同但原理一致——客户端和服务端的字符集必须显式对齐。5.4 64 位目标编译报错“平台不支持”现象项目切换 Win64 编译后报找不到控件单元或链接失败。 原因控件包只编译了 Win32 平台Win64 目标平台下 IDE 找不到对应 dcuh。 解决在 Project Manager 里选中 dpk 文件右键 Platform 列表勾选 Win64重新编译安装。第三方包经常有人只装 32 位切 64 位时翻车这个操作完一次后面都会记得。5.5 异步查询结果集被提前释放现象异步查询回调里访问 Field 值偶发报“无效的字段访问”或访问冲突。 原因数据集在回调执行前被其他代码关闭或释放了回调里操作了一个已销毁的控件实例。 解决在异步回调开头检查控件状态同时保证在数据集关闭前不触发回调if Assigned(HeidiSQLQuery1) and HeidiSQLQuery1.Active then begin Label1.Caption : HeidiSQLQuery1.Fields[0].AsString; end;这个检查看起来多余但在异步模式下是必要的防线。Delphi 的匿名过程捕获了 Self 引用如果控件被释放了回调执行时就是访问已释放内存这种问题最难查。6. 数据同步、备份恢复与性能验证把控件包的底榨干净D123 包除了常规 CRUD还带了几个对生产环境更有价值的功能数据同步、备份恢复。这两个功能在 HeidiSQL 原生客户端里是图形化界面操作的封装成 Delphi 控件后变成了方法调用。像数据同步常见场景是 Dev 库往 Test 库同步表结构或数据手动写脚本需要挨个表对比用控件直接调同步方法指定源连接和目标连接内部自动跑表结构比对加数据增量同步。备份的完整写法是这样的HeidiSQLBackup1.Source : HeidiSQLConn1; HeidiSQLBackup1.BackupPath : D:\backup\app_ FormatDateTime(yyyymmdd_hhnnss, Now) .sql; HeidiSQLBackup1.Execute;这个备份生成的 SQL 文件可以直接在另一个库用同一控件的 Restore 方法回放。如果需要对备份的 SQL 做二次处理比如过滤掉某张表的 INSERT可以在 Execute 前设置排除表清单比手工解析 SQL 文本稳得多。装上这个控件包后我习惯把每个新项目的数据库初始化脚本直接走一遍备份-恢复-比对校验确认生成的 SQL 文件在空白库里能完整重建表结构。这个习惯帮我拦住过三次线上事故——都是开发库的表结构跟发布脚本不一致导致的迁移失败。从那以后凡是经手这个控件的新项目我都强制走一遍“备份→恢复→比对表结构”三步验证确认拿到手的数据库交付物没有暗坑才敢往测试库推。做数据库相关开发的同行这套流程值得照抄一遍希望帮到你。本文还有配套的精品资源点击获取