简介这是一套面向Python初学者与数据库入门开发者的学习型GUI工具源码聚焦PyQt5界面开发与SQLite轻量级数据库交互实践解决本地数据可视化管理与CRUD操作的教学落地问题。资源共171个文件含19个核心Python脚本含DatabaseManager类封装、连接/查询/增删改函数、10个.ui设计文件对应主窗口、表单、弹窗等界面、4个.bat批处理用于UI编译与环境初始化以及1个.db3示例数据库和百余张界面图标bmp/jpg整体压缩包12.48MB结构清晰便于按模块理解MVC逻辑与信号槽机制。已有118人学习下载提供完整可运行工程含异常捕获、事务控制、操作反馈提示等生产级细节适合边调试边掌握PyQt5事件驱动编程与sqlite3嵌入式数据库协同开发的关键路径。1. 这不是又一个“Hello World”窗口一个能连 MySQL/SQLite、带事务回滚、支持 SQL 高亮与历史记录的 PyQt5 数据库小工具专治「写完 INSERT 就忘改 WHERE」的深夜翻车现场你有没有过这种经历凌晨两点调试一个数据清洗脚本手抖少打了一个WHERE条件UPDATE users SET status1直接跑全表——等反应过来时生产库已静默变灰。或者更日常的临时查个订单状态得切到命令行敲mysql -u... -p... -e SELECT * FROM orders WHERE id12345输错密码三次后放弃再打开 Navicat发现试用期昨天刚过。这个基于 PyQt5 实现的数据库操作小工具就是为这类「轻量但高频、需可控但不重」的场景而生它不替代 DBeaver也不对标 DataGrip而是把「连接 → 写 SQL → 执行 → 看结果 → 撤回 → 保存语句」压缩进一个 800×600 的窗口里所有操作在 GUI 中闭环完成且源码完全开放、无任何隐藏逻辑或远程调用。它默认支持 SQLite免配置和 MySQL需 pymysql内置事务开关、SQL 语法高亮、执行历史滚动缓存、结果表格双击编辑回写甚至带一个极简的建表向导——不是玩具是我在本地开发环境里连续三年每天打开超过 7 次的「数据库后悔药」。适合 Python 初学者练手 GUIDB 交互更适合后端/测试/数据分析岗工程师作为轻量级 DB 辅助终端。2. 从零启动PyQt5 环境准备、源码结构拆解与核心模块职责划分2.1 环境依赖为什么必须用 Python 3.7pymysql 和 PyQt5 的版本兼容性血泪经验这个工具对 Python 版本有明确要求最低 Python 3.7推荐 3.8–3.11。原因很实际——PyQt5 官方从 5.15.0 开始停止对 Python 3.6 的 wheel 支持而 pymysql 在 1.0.2 版本中移除了对旧版 MySQL 协议的兼容逻辑若你用 Python 3.6 PyMySQL 1.1.0连接 MySQL 8.0 会直接报Authentication plugin caching_sha2_password cannot be loaded。这不是 bug是协议演进的硬性门槛。安装命令必须按顺序执行顺序错会导致 Qt 平台插件加载失败# 先装 PyQt5注意不要用 pip install pyqt5-dev-tools它会额外拉一堆 dev 依赖 pip install PyQt55.15.9 # 再装数据库驱动SQLite 无需额外包但 MySQL 必须 pip install pymysql1.1.0 # 可选如需连接 PostgreSQL加装 psycopg2-binaryOracle 用 cx_Oracle需 Oracle Client # pip install psycopg2-binary2.9.7提示PyQt55.15.9是经过实测最稳定的组合。5.15.10 存在 macOS 下 QWebEngineView 渲染异常问题6.x 系列PyQt6虽新但此项目未做迁移——因为其信号槽语法变更、QFileDialog API 调整、以及对旧版 Designer.ui文件的兼容性断裂会直接导致主窗口无法加载。这不是保守是避免把「调试数据库工具」变成「调试 PyQt 版本兼容性」。2.2 源码包结构5 个文件讲清全部逻辑每个文件承担什么不可替代的职责解压后你会看到如下结构共 5 个核心文件无子目录文件名类型核心职责是否可删main.py启动入口初始化 QApplication、创建 MainWindow 实例、设置全局字体与样式❌ 绝对不可删db_manager.py模块封装数据库连接池、SQL 执行、事务控制、结果集转换含 pandas DataFrame 支持❌ 核心逻辑中枢ui_mainwindow.py自动生成由designer.ui编译而来纯界面定义QWidget QTabWidget QTextEdit QTableView⚠️ 可重生成但删了就无界面designer.uiQt Designer 源文件可视化拖拽设计稿含连接配置区、SQL 编辑器、结果表格、状态栏✅ 可删但失去自定义 UI 能力sample.dbSQLite 示例库内置users,orders,products三张表含 20 条测试数据用于首次启动演示✅ 可删不影响功能特别说明ui_mainwindow.py不是手写代码而是通过以下命令从designer.ui编译生成你后续修改 UI 后需重新执行# Windows / Linux / macOS 均可用 pyside2-uic designer.ui -o ui_mainwindow.py # 注意此处用的是 pyside2-uic而非 pyuic5 —— 因为 PyQt5 官方推荐用 pyside2 工具链编译 .ui兼容性更稳2.3 主窗口四大功能区它们如何协同完成一次「安全查询」启动main.py后你会看到一个清晰的四分区布局左上连接配置面板包含数据库类型下拉SQLite / MySQL、主机/IPMySQL 专用、端口默认 3306、数据库名、用户名/密码。SQLite 仅需填「数据库路径」支持相对路径如./data/app.db或绝对路径。点击「连接」后状态栏显示Connected to SQLite: ./sample.db或Connected to MySQL: localhost:3306/testdb。左下SQL 编辑器QTextEdit支持 CtrlEnter 执行当前语句非全文、Ctrl/ 注释/取消注释、自动缩进、关键词高亮SELECT,INSERT,BEGIN,COMMIT等。关键细节它不是简单text()获取字符串而是调用self.editor.toPlainText().strip()并预处理——自动过滤空行、合并多行语句为单条以分号结尾避免SELECT * FROM users; UPDATE orders SET status2;被当一条语句执行。右半区结果表格QTableView使用QSqlQueryModel非QStandardItemModel直连查询结果支持列宽自适应、右键复制整行、双击单元格进入编辑模式修改后按 Enter 提交Esc 取消。注意编辑仅限SELECT查询结果且仅当该列非主键、非NOT NULL且无触发器时才允许——这是db_manager.py中is_editable_column()方法的硬性校验。底部状态栏显示执行耗时ms、影响行数Rows affected: 3、最后错误信息红色字体、当前连接状态图标。玄学细节当执行SELECT时显示Fetched 12 rows执行INSERT/UPDATE/DELETE时显示Affected 5 rows执行BEGIN后状态栏右侧出现黄色TXN标签COMMIT或ROLLBACK后消失。3. 连接与执行从建立连接到安全执行 SQL 的完整链路解析3.1 连接管理器为什么不用sqlite3.connect()而要封装 ConnectionPool直接调用sqlite3.connect()看似简单但在 GUI 应用中会引发两个致命问题线程阻塞connect()是同步阻塞调用若数据库文件被其他进程占用如另一程序正在写入GUI 主线程会卡死 30 秒整个窗口无响应连接泄漏每次查询都新建连接频繁CREATE TABLE或大量INSERT后Linux 下可能触发Too many open files错误ulimit 默认 1024。因此db_manager.py中实现了轻量级连接池# db_manager.py 片段 class ConnectionPool: def __init__(self, db_type: str, **kwargs): self.db_type db_type self.kwargs kwargs self._pool queue.Queue(maxsize5) # 最大 5 个空闲连接 self._create_initial_connections() def get_connection(self): try: return self._pool.get_nowait() # 非阻塞获取 except queue.Empty: return self._create_new_connection() # 池空则新建 def return_connection(self, conn): if self._pool.full(): conn.close() # 池满则关闭不归还 else: self._pool.put(conn)SQLite 连接池复用同一Connection对象因 SQLite 是文件锁机制多线程需序列化MySQL 连接池则为每个连接维护独立pymysql.Connection实例并在归还时执行conn.ping(reconnectTrue)确保存活。参数说明maxsize5是实测平衡值——小于 3 时高并发查询易等待大于 10 时内存占用陡增且无性能收益。3.2 SQL 执行引擎如何区分 DML、DDL、事务控制语句并施加不同策略工具对 SQL 语句类型进行严格分类执行策略完全不同语句类型示例执行策略是否启用事务结果返回形式SELECTSELECT name FROM users WHERE id 10直接执行结果转为QSqlQueryModel否只读表格视图INSERT/UPDATE/DELETEUPDATE products SET price99 WHERE id5强制开启事务即使未显式BEGIN是自动BEGIN状态栏提示行数CREATE/DROP/ALTERCREATE TABLE logs (id INTEGER PRIMARY KEY, msg TEXT)禁用事务DDL 在 MySQL 中隐式提交否纯文本提示BEGIN/COMMIT/ROLLBACKBEGIN; UPDATE ...; ROLLBACK;透传执行不包装由用户控制状态栏更新 TXN 状态关键实现位于db_manager.execute_sql()def execute_sql(self, sql: str) - Tuple[bool, Union[str, List[dict]], Optional[str]]: sql_clean self._normalize_sql(sql) # 去空行、分号分割 stmt_type self._classify_statement(sql_clean) # 返回 SELECT, DML, DDL, TXN if stmt_type SELECT: return True, self._fetch_all(sql_clean), None elif stmt_type in [INSERT, UPDATE, DELETE]: return self._execute_dml_in_transaction(sql_clean) # 内部调用 BEGIN/COMMIT/ROLLBACK elif stmt_type DDL: return self._execute_ddl(sql_clean) # 直接 execute不套事务 else: # TXN return self._execute_txn_control(sql_clean)注意_execute_dml_in_transaction()中即使用户没写BEGIN也会在执行前自动cursor.execute(BEGIN)并在成功后COMMIT若出错则ROLLBACK并抛出异常。这是防止「忘记加 WHERE」的第二道保险。3.3 结果渲染QTableView 如何实现「双击编辑→回写数据库」的闭环双击编辑功能不是简单setFlags(Qt.ItemIsEditable)而是重载了QSqlQueryModel的setData()方法并加入强校验# ui_mainwindow.py 中重写的 model 类 class EditableQueryModel(QSqlQueryModel): def setData(self, index, value, roleQt.EditRole): if role ! Qt.EditRole: return False if not self._is_column_editable(index.column()): # 校验列是否可编辑 return False # 获取原始字段名与表名 field_name self.record().field(index.column()).name() table_name self.query().lastQuery().split()[3] # 粗略提取实际用正则更准 pk_value self.data(self.index(index.row(), 0), Qt.DisplayRole) # 假设第 0 列为主键 # 构造安全 UPDATE 语句防注入 update_sql fUPDATE {table_name} SET {field_name} %s WHERE rowid %s try: self._db_manager.execute_update(update_sql, (value, pk_value)) self.refresh() # 重新查询 return True except Exception as e: QMessageBox.critical(None, 更新失败, str(e)) return False参数说明%s占位符由pymysql自动转义杜绝 SQL 注入rowid是 SQLite 隐式主键MySQL 则需提前获取真实主键名通过PRAGMA table_info(table)查询refresh()触发query().exec_()重新拉取数据保证视图实时性。4. 避坑指南那些让你重启三次才找到原因的 5 个典型问题4.1 现象点击「连接」按钮无反应状态栏始终显示Disconnected日志窗口空白原因PyQt5 的事件循环未启动或main.py中app.exec_()被意外注释/跳过。常见于从 Jupyter Notebook 直接%run main.py——Notebook 的 IPython 内核与 PyQt 的 Qt 事件循环冲突。解决必须在终端中执行python main.py若需在 IDE 中调试确保 Run Configuration 设置为「Run with Python interpreter」而非「IPython console」。4.2 现象MySQL 连接成功但执行SELECT * FROM users报错pymysql.err.InternalError: Packet sequence number wrong原因MySQL 服务端启用了wait_timeout默认 28800 秒空闲连接超时后被服务端主动断开但客户端连接池未检测到仍尝试复用失效连接。解决在db_manager.py的ConnectionPool._create_new_connection()中为 MySQL 连接添加autocommitTrue和ping_on_connectTrue参数# 修改前 conn pymysql.connect(**self.kwargs) # 修改后 conn pymysql.connect( autocommitTrue, ping_on_connectTrue, # 连接时自动 ping **self.kwargs )4.3 现象SQL 编辑器中输入中文执行后结果表格显示?????乱码原因MySQL 连接未指定字符集服务端默认latin1而客户端发送 UTF-8 字节流。解决在连接配置中MySQL 的「高级参数」区域需手动在main.py中扩展添加charsetutf8mb4SQLite 无此问题内部统一 UTF-8。4.4 现象双击结果表格单元格进入编辑修改后按 Enter 无反应也无错误提示原因该列对应数据库字段设置了NOT NULL且无默认值但用户输入为空字符串触发了数据库层约束拒绝。解决在EditableQueryModel.setData()中增加空值校验if value and not self._column_allows_null(index.column()): QMessageBox.warning(None, 禁止空值, f字段 {field_name} 不允许为空) return False4.5 现象执行CREATE TABLE test (id INT PRIMARY KEY, name VARCHAR(50))后刷新表列表看不到新表原因SQLite 的CREATE TABLE成功后QSqlQueryModel未监听 schema 变更事件需手动触发元数据刷新。解决在db_manager.execute_ddl()执行后调用self._refresh_table_list()方法内部执行PRAGMA table_list并更新 UI 下拉框。5. 进阶技巧定制化你的数据库工作流——从自动备份到跨库比对5.1 一键导出当前结果为 Excel用 openpyxl 替代 pandas规避依赖爆炸很多人想导出表格为 Excel第一反应是pandas.DataFrame.to_excel()。但pandas依赖numpyopenpyxlxlrd安装包体积超 30MB且xlrd2.0 已弃用.xls支持易引发版本冲突。更轻量的做法是直接用openpyxl写入# 在 main.py 中添加导出按钮绑定 def export_to_excel(self): model self.result_view.model() if not model or model.rowCount() 0: return wb Workbook() ws wb.active ws.title Query_Result # 写入表头 for col in range(model.columnCount()): ws.cell(row1, columncol1, valuemodel.headerData(col, Qt.Horizontal)) # 写入数据 for row in range(model.rowCount()): for col in range(model.columnCount()): val model.data(model.index(row, col), Qt.DisplayRole) ws.cell(rowrow2, columncol1, valuestr(val) if val is not None else ) filepath, _ QFileDialog.getSaveFileName(self, 保存 Excel, , Excel Files (*.xlsx)) if filepath: wb.save(filepath) QMessageBox.information(self, 导出成功, f已保存至 {filepath})注意str(val)强转是必要的——openpyxl不接受None、QDateTime或自定义对象必须转为字符串。日期类型会丢失格式但满足「快速导出查看」需求已足够。5.2 跨数据库比对用 Python 实现 SQLite 与 MySQL 表结构一致性校验当你需要将 SQLite 开发库迁移到 MySQL 生产环境时常遇到字段类型不一致如INTEGERvsINT、主键缺失等问题。工具内置一个schema_diff.py脚本不在主程序中但源码包附带# schema_diff.py def compare_schemas(sqlite_path: str, mysql_config: dict) - List[str]: sqlite_con sqlite3.connect(sqlite_path) mysql_con pymysql.connect(**mysql_config) issues [] sqlite_tables [row[0] for row in sqlite_con.execute(SELECT name FROM sqlite_master WHERE typetable).fetchall()] for table in sqlite_tables: # 获取 SQLite 表结构 sqlite_cols sqlite_con.execute(fPRAGMA table_info({table})).fetchall() # 获取 MySQL 表结构 mysql_cols mysql_con.cursor().execute(fDESCRIBE {table}).fetchall() # 比较字段名、类型、是否主键 for s_col in sqlite_cols: found False for m_col in mysql_cols: if s_col[1] m_col[0]: # 字段名匹配 # 类型映射INTEGER→INT, TEXT→VARCHAR(255), REAL→DOUBLE if _map_sqlite_type(s_col[2]) ! m_col[1]: issues.append(f表 {table} 字段 {s_col[1]} 类型不一致SQLite{s_col[2]}, MySQL{m_col[1]}) found True break if not found: issues.append(f表 {table} 缺失字段 {s_col[1]}) return issues运行方式python schema_diff.py ./dev.db {host:127.0.0.1,user:root,password:123,database:prod}输出差异列表。这比肉眼对比SHOW CREATE TABLE快 10 倍。5.3 自动备份策略每天凌晨 2 点备份 SQLite 文件保留最近 7 天SQLite 备份不能靠mysqldump而是文件级拷贝。在main.py启动时加入后台线程from datetime import datetime, timedelta import threading import shutil def auto_backup_sqlite(db_path: str, backup_dir: str ./backups): os.makedirs(backup_dir, exist_okTrue) while True: now datetime.now() if now.hour 2 and now.minute 0: # 每天 2:00 执行 backup_name f{os.path.basename(db_path).split(.)[0]}_{now.strftime(%Y%m%d)}.db shutil.copy2(db_path, os.path.join(backup_dir, backup_name)) # 清理 7 天前备份 cutoff now - timedelta(days7) for f in os.listdir(backup_dir): if f.endswith(.db) and _ in f: date_str f.split(_)[-1].split(.)[0] try: f_date datetime.strptime(date_str, %Y%m%d) if f_date cutoff: os.remove(os.path.join(backup_dir, f)) except ValueError: continue time.sleep(60) # 每分钟检查一次 # 在 main() 函数中启动 if __name__ __main__: app QApplication(sys.argv) window MainWindow() # 启动备份线程守护线程主程序退出时自动结束 backup_thread threading.Thread(targetauto_backup_sqlite, args(./sample.db,), daemonTrue) backup_thread.start() window.show() sys.exit(app.exec_())从那以后我每次部署新环境都强制走一遍schema_diff.pyauto_backup_sqlite()启用检查哪怕只是本地测试库——因为 90% 的线上事故源头都在「以为一样其实不一样」的那张表里。希望帮到你。本文还有配套的精品资源点击获取