后端数据可视化数据库数据分析【免费下载链接】sqlpadWeb-based SQL editor项目地址https://gitcode.com/gh_mirrors/sq/sqlpad点击查看免费下载本指南面向希望在本地从源码构建 SQLPad、参与其前后端开发、运行其集成测试或为其构建本地 Docker 镜像的开发者。文章以仓库根目录的 DEVELOPER-GUIDE.md 为骨架结合server、client目录下的真实源码、配置与测试用例展开讲解阅读完成后你将掌握 SQLPad 的工程结构、一键构建脚本原理、双终端开发工作流、测试数据库生成机制、Mocha 集成测试运行方法以及本地 Docker 镜像的构建与跨架构验证方案。环境前置要求PrerequisitesSQLPad 的开发环境要求并不复杂但有几个关键点需要先确认Node.js v14.0.0 及以上。需要说明的是当前仓库根目录package.json声明packageManager为yarn1.22.19而 server/package.json 中engines字段已要求node 20因此在实际开发时建议使用 Node 20 或更高版本Docker 镜像也基于node:20-slim构建见 Dockerfile。Yarn 1classic yarn。SQLPad 是一个由根目录、client/、server/三个 Node 子项目组成的 monorepo 结构统一使用 classic yarn 管理依赖锁文件。部分依赖需要本地编译macOS 需要安装 Xcode Command Line ToolsUbuntu / Debian 系执行apt-get install build-essential即可获得编译所需的 gcc/g、make 等工具Windows 需要额外步骤参考node-gyp的官方安装说明。若你打算在 Docker 中启用 ODBC 支持构建阶段还需要unixodbc-dev见 Dockerfile。代码风格与静态检查Style GuideSQLPad 使用Prettier作为自动代码格式化工具、ESLint作为 lint 工具所有代码在提交前都应通过检查# 检查格式与 lint yarn run lint # 自动修复部分格式与 lint 问题 yarn run fixlint从根目录 package.json 可以看到lint与fixlint分别串联了client与server两个子项目的检查fixlint: npm run fixlint --prefix client npm run fixlint --prefix server prettier --write \**/*.js\, lint: npm run lint --prefix client npm run lint --prefix server prettier --check \**/*.js\后端server的 ESLint 配置在 server/.eslintrc基于airbnb-baseprettier并针对 Node/ES2022/Mocha 环境做了大量规则放宽如关闭no-plusplus、no-param-reassign等。前端client的配置在 client/.eslintrc基于typescript-eslintreact-hooksprettier因为前端已全面 TypeScript 化。如果你使用 Visual Studio Code可以安装 Prettier 和 ESLint 扩展在编写过程中即时发现并修复问题。另外仓库还通过huskylint-staged配置了 pre-commit 钩子见根目录 package.json会在提交时对暂存的*.{js,json,css}文件自动执行prettier --write。从源码构建 SQLPadGetting Started一键构建脚本克隆仓库后在仓库根目录执行scripts/build.sh该脚本做了目录存在性校验确保从项目根目录执行其核心步骤可以从 scripts/build.sh 源码中直接看到# 1. 安装根目录依赖以 yarn.lock 为准 yarn # 2. 安装前端依赖 (cd client yarn) # 3. 构建前端TypeScript 编译 Vite 打包 (cd client yarn build) # 4. 安装后端依赖 (cd server yarn) # 5. 将前端构建产物复制到 server/public rm -rf server/public mkdir server/public cp -r client/build/* server/public # 6. 生成测试用的 SQLite 数据库 fixture node server/generate-test-db-fixture.js注意脚本注释中提到的package-lock.json在当前仓库实际对应的是yarn.lock。前端构建命令yarn build对应 client/package.json 中的build: tsc vite build即先由 TypeScript 编译器做类型检查再由 Vite 产出client/build目录。以生产模式运行构建完成后即可用生产模式启动服务端cd server node server.js --config ./config.dev.envnode server.js的启动逻辑在 server/server.js它通过minimist解析 CLI 参数支持--help、--version、--migrate和--config四个核心用法见 server/server.js# 打印帮助 node server.js --help # 仅执行数据库迁移后退出 node server.js --migrate --config path/to/file.format # 使用配置文件启动 node server.js --config path/to/file.format当--config指向.env文件时server.js会先用dotenv将变量载入process.env再交给Config类统一解析。服务器启动前会依次完成校验配置getValidations()发现错误直接exit(1)→ 初始化数据库makeDb→ 执行迁移makeMigrator→ 初始化驱动initDrivers→ 确保管理员存在ensureAdmin→ 加载种子数据loadSeedData→ 创建 Express 应用makeApp。若配置了SQLPAD_HTTPS_KEY_PATH与SQLPAD_HTTPS_CERT_PATH则以 HTTPS 方式监听否则以 HTTP 方式监听并且端口被占用时detect-port会自动切换到可用端口见 server/server.js。仓库自带的 server/config.dev.env 是开发配置范本其中已经预置了一个通过环境变量声明的 SQLite 测试连接SQLPAD_PORT 3010 SQLPAD_BASE_URL /sqlpad SQLPAD_DB_PATH ../db SQLPAD_APP_LOG_LEVEL debug SQLPAD_WEB_LOG_LEVEL debug SQLPAD_SERVICE_TOKEN_SECRET secr3t SQLPAD_DEFAULT_CONNECTION_ID devdbdriverid123 SQLPAD_CONNECTIONS__devdbdriverid123__driver sqlite SQLPAD_CONNECTIONS__devdbdriverid123__name dev connection from config SQLPAD_CONNECTIONS__devdbdriverid123__filename ./test/fixtures/sales.sqlite其中SQLPAD_CONNECTIONS__id__field这类双下划线环境变量是 SQLPad 通过环境变量声明连接配置的约定解析逻辑在 server/lib/config/index.jsgetConnections()与config-utils.js的parseConnectionsFromEnv()中运行时从环境变量解析、不会 upsert 进后端数据库且自动标记editable false。从配置校验逻辑server/lib/config/index.js可以看到连接必须提供name与受支持的driver其余字段必须匹配对应驱动fields中声明的 key否则启动时直接报错。全局安装为 CLI如果你希望像npm install sqlpad -g一样在任意目录通过sqlpad命令启动可以基于本地文件做全局安装注意需先完成前端构建与复制cd server npm install -g # 之后在任意目录运行 cd ~ sqlpad --config ./config.dev.env全局安装依赖 server/package.json 中的bin: { sqlpad: server.js }声明。如果此前已通过 npm 全局安装过 sqlpad需先npm uninstall sqlpad -g避免冲突。前后端分离开发模式DevelopingSQLPad 的前端React TypeScript Vite与后端Express在开发期是两套独立的开发服务器需要在仓库根目录开两个终端# 终端 1后端开发模式node-dev 自动重启 pino-pretty 美化日志 cd server yarn start # 终端 2前端开发服务器 cd client yarn start对应的 npm script 定义后端server/package.json 中start: node-dev server.js -- --config \./config.dev.env\ | pino-pretty前端client/package.json 中start: vite。两个服务各自监听不同端口http://localhost:3000React 前端的 Vite 开发模式http://localhost:3010编译后的前端产物 SQLPad 服务端。开发体验上前端文件变更会触发 Vite 热更新页面自动刷新后端文件变更会触发node-dev自动重启。关于 3000 端口开发模式的一些已知限制原文的解释很关键在 3000 端口下部分功能可能无法正常工作如 CSV/XLSX 下载、Google 登录。原因有二端口差异导致的配置问题例如 Google OAuth 的回调地址只能绑定一个 URL/端口开发代理机制Vite 开发服务器是一个次要 Web 服务器会把自身不理解的请求代理到 3010 端口的 SQLPad 服务端。代理规则就定义在 client/vite.config.ts 中/api、/statement-results、/auth/saml、/login/callback、/auth/google、/auth/oidc等路由以及带/sqlpad前缀的对应路由都会被转发到http://127.0.0.1:3010const PROXY_ROUTES [ /api, /statement-results, /auth/saml, /login/callback, /auth/google, /auth/oidc, ]; const PROXY_URL http://127.0.0.1:3010;开发模式下 Vite 的base被固定为/sqlpad/而生产构建可通过VITE_SPA_BASE_URL_OVERRIDE环境变量覆盖见 client/vite.config.ts。在 Windows 上开发Windows 下无法直接执行build.sh这类 shell 脚本可以使用 cmder 之类的终端模拟器通过sh直接调用sh scripts/build.sh测试/开发用数据库连接Test/Dev Database Connection早期 SQLPad 依赖一个mock driver开启debug标志后解析 SQL 注释中的变量来生成假数据而现在被一个更实际的方案取代server/generate-test-db-fixture.js会生成一个 SQLite 测试数据库用于测试和本地开发。这个方案的价值在于你可以直接编写自己熟悉的 SQL而不用去记忆那些写在 SQL 注释里的 mock 变量。脚本会在server/test/fixtures/sales.sqlite生成数据库只需在 SQLPad 中新建一个 SQLite 连接、把 filename 设为./test/fixtures/sales.sqlite即可使用。从脚本源码可以看到这个数据库的内容设计regions表5 个销售区域Northeast / West / South / Midwest / East各带一个 revenue 乘数1.11.5products表16 条模拟商品记录覆盖 toy / tech / food 三类包含名称、类别、颜色、价格sales表100 批次 × 100 行 10,000 条销售记录cost与revenue由区域乘数、日期/周数/分钟/秒四个时间维度乘数叠加计算而来见 server/generate-test-db-fixture.jsvw_sales视图将 sales 关联 regions、products并拆出order_date、order_time、order_hour等便于做图表的时间维度字段500 张z_fake_table_products_*空表用于模拟大型 schema方便测试 Schema 侧边栏的加载与搜索场景。脚本生成的order_timestamp基于moment.utc(2020-01-01)加上固定的分钟/秒偏移rowId * 43分钟、rowId * 37秒因此数据是确定性的、可预测的数据本身语义上有点无厘头但这不是随机数据。如果你需要扩展这个数据库可以直接修改脚本重新生成。运行测试Running TestsSQLPad 的测试以 API 服务器为主绝大多数是集成测试穿插少量单元测试。测试代码集中在server/test目录下按 API 路由划分如api/queries.js、api/batches.js、api/connection-accesses.js、api/query-result-stores.js等使用mocha作为测试运行器。测试辅助类TestUtils在 server/test/utils.js它基于内存数据库 内存 session 构建出完整的 Express 应用并封装了get/post/put/del等方法配合supertest发起请求。前置步骤cd server # 1. 若依赖尚未安装build.sh 会自动安装 yarn # 2. 若测试数据库 fixture 尚未生成build.sh 会自动生成 node generate-test-db-fixture.js # 3. 按需启动后端服务-d 表示后台运行 docker-compose up -d redis docker-compose up -d ldapserver/docker-compose.yml 除了 redis6379与 ldap10389用于测试 LDAP 认证流程还定义了 mssql、postgres、mariadb、mysql 等服务用于驱动相关的集成测试。运行全部测试yarn test对应 server/package.json 中的test: mocha test --timeout 20000 --recursive --exit --bail--recursive递归收集test目录下的用例--bail遇到首个失败即停止--timeout 20000设定了 20 秒超时。部分用例依赖 redis若本地未启动 redis对应测试会通过TestUtils.redisAvailable()检测后自动 skip见 server/test/api/query-result-stores.js。运行单个测试用例npx mocha test/path/to/file.js --exit例如只运行连接 API 测试npx mocha test/api/connections.js --exit--exit用于测试结束后立即退出进程。此外仓库还提供了针对不同后端数据库的全套测试命令server/package.json可通过SQLPAD_BACKEND_DB_URI将后端元数据库切换到 mssql、mysql、mariadb 或 postgresnpm run testpostgres npm run testmysql npm run testmariadb npm run testmssql测试的运行路径示例以api/query-result-stores.js为例server/test/api/query-result-stores.js它验证了queryResultStore的 file / redis / database / memory 四种存储后端都能完成提交批次 → 轮询状态 → 拉取语句结果 → 删除结果的完整闭环let batch await utils.post(admin, /api/batches, { connectionId: connection.id, batchText: query1, // SELECT 1 AS id, blue AS color }); while (batch.status ! finished batch.status ! error) { await wait(25); batch await utils.get(admin, /api/batches/${batch.id}); }这也从侧面说明SQL 的执行被建模为batch批次→ statements语句→ results结果的三级资源结构对应 server/routes/batches.js、server/routes/statements.js 与 server/routes/statement-results.js 三组路由。构建本地 Docker 镜像Building local docker images仓库根目录的 Dockerfile 采用多阶段构建第一阶段基于node:20-slim完成依赖安装与前端构建第二阶段用全新的node:20-slim只拷贝server目录其中已含构建好的前端产物并将NODE_ENV设为 production、默认端口设为 3000。构建与运行# 在仓库根目录执行需先安装并启动 Docker docker build -t localsqlpad . # 构建其他架构时追加 --platform例如 amd64 docker build -t localsqlpad . --no-cachetrue --platformlinux/amd64 # 查看镜像列表 docker images # 运行本地镜像 docker run -p 3000:3000 -e SQLPAD_ADMINadminsqlpad.com -e SQLPAD_ADMIN_PASSWORDadmin localsqlpad # 浏览器访问 http://localhost:3000容器启动入口是 docker-entrypoint它会执行/etc/docker-entrypoint.d目录下所有.sh文件source方式加载允许脚本通过环境变量覆盖默认行为最后exec node /usr/app/server.js $启动服务端。镜像默认设置SQLPAD_DB_PATH/var/lib/sqlpad用于持久化数据卷。支持 ODBC 的镜像如果使用 ODBC 驱动如连接 SAP HANA、Oracle 等需要启用 ODBC 构建参数docker build -t sqlpad/sqlpad-odbc --build-arg ODBC_ENABLEDtrue .构建阶段会安装unixodbc-dev运行阶段会安装unixodbc libaio1 odbcinst libodbc1并创建/etc/odbcinst.ini见 Dockerfile。之后有两种方式补充具体驱动在 fork 中扩展这个 Dockerfile基于sqlpad/sqlpad-odbc编写自己的 DockerfileFROM sqlpad/sqlpad-odbc后安装所需驱动。注意目前该 ODBC 镜像并未发布到 Docker Hub需要先在本地用上面的构建命令产出。跨架构镜像验证当需要测试特定架构例如在 arm64 机器上跑一个 amd64 镜像时可以直接拉取基于特定 sha 的 Docker Hub 镜像docker run -p 3000:3000 -e SQLPAD_ADMINadminsqlpad.com -e SQLPAD_ADMIN_PASSWORDadmin \ sqlpad/sqlpadsha256:b80b4ab2af32ed07479d9233327bf3e5352fc71b41245d8e73b6403361be266a这也正是docker build --platformlinux/amd64本地构建的对照验证方式。进阶配置项速查与开发调试要点虽然 DEVELOPER-GUIDE.md 本身不逐项罗列配置但从 server/lib/config/config-items.js共 445 行、约 80 项配置中可以看到 SQLPad 完整的配置体系开发调试时最常用的几项配置 key环境变量默认值说明portSQLPAD_PORT80监听端口baseUrlSQLPAD_BASE_URL空应用挂载路径前缀dbPathSQLPAD_DB_PATH空数据/会话文件目录生产环境强烈建议设置sessionStoreSQLPAD_SESSION_STOREfile会话存储file/database/redis/memoryqueryResultStoreSQLPAD_QUERY_RESULT_STOREfile查询结果存储file/database/redis/memoryqueryResultMaxRowsSQLPAD_QUERY_RESULT_MAX_ROWS10000单个查询结果最大行数appLogLevelSQLPAD_APP_LOG_LEVELinfo应用日志级别webLogLevelSQLPAD_WEB_LOG_LEVELinfoWeb 请求日志级别backendDatabaseUriSQLPAD_BACKEND_DB_URI空后端元数据库连接串默认 SQLiteredisUriSQLPAD_REDIS_URI空Redis 连接串session / 结果存储用dbAutomigrateSQLPAD_DB_AUTOMIGRATEtrue启动时自动执行数据库迁移配置优先级为CLI 参数 环境变量 默认值见 server/lib/config/index.js字符串形式的true/false会被自动转换为布尔值。Config.getValidations()会在启动时报错session/结果存储必须属于允许列表、使用 redis 存储时必须设置SQLPAD_REDIS_URI、SQLPAD_前缀的未知环境变量会被警告、已移除的旧变量如SQLPAD_SMTP_HOST、SQLPAD_DEBUG、DISABLE_AUTH等完整清单见 server/lib/config/index.js会直接报错这能有效帮助你排查配置拼写问题。小结SQLPad 的开发者工作流可以概括为一条清晰的链路scripts/build.sh一键完成三个子项目的依赖安装与前端构建 → 双终端分别启动前后端开发服务器进行热开发 → 用generate-test-db-fixture.js生成确定性测试数据库 →yarn test/npx mocha file --exit运行集成测试 → 多阶段 Dockerfile 构建镜像并跨架构验证。配合yarn run lint/yarn run fixlint保持代码风格你就可以在本地完整地编译、运行、测试和打包 SQLPad 了。更深入的产品功能连接管理、查询执行、图表、认证与 Webhook 等可继续阅读 README.md 与 docs 目录下的官方文档。赞分享后端数据可视化数据库数据分析【免费下载链接】sqlpadWeb-based SQL editor项目地址https://gitcode.com/gh_mirrors/sq/sqlpad点击查看免费下载相关推荐revive 开发者指南从构建、规则开发到发布维护的完整实战手册revive 开发者指南从构建、规则开发到发布维护的完整实战手册 本篇指南以 revive 仓库的 DEVELOPING.md https://link.gi开发工具代码质量静态分析CLIFleet 开源贡献者指南从源码构建、本地开发到测试与调试的完整入门手册Fleet 开源贡献者指南从源码构建、本地开发到测试与调试的完整入门手册 Fleet 是一个开源设备管理平台Open device management后端前端企业应用运维网络安全OpenSearch 开发者指南从源码构建、测试到贡献代码的完整实践手册OpenSearch 开发者指南从源码构建、测试到贡献代码的完整实践手册 本文基于 OpenSearch 仓库根目录的 DEVELOPER_GUIDE.md搜索引擎全文检索可观测性数据分析上一篇蔚蓝档案鼠标指针3分钟让Windows光标变身动漫游戏角色下一篇从零读懂 React 源码Under-the-hood-ReactJS 的 Stack Reconciler 全景流程导览创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考