如何使用opengemini-studio

(Updated: )
middleware
opengemini,

背景

OpenGemini 是一款云原生分布式时序数据库,它完全兼容 InfluxDB 生态系统。作为一个高性能的时序数据库,OpenGemini 在物联网、监控、金融等领域有着广泛的应用场景。

然而,当前生态下缺乏一个现代化的 GUI 客户端工具。虽然 OpenGemini 兼容 InfluxDB 协议,但现有的 InfluxDB 客户端要么功能有限,要么不够现代化,无法提供良好的用户体验。特别是在数据查询、可视化和数据库管理方面,缺少一个跨平台、易用且功能完善的桌面客户端。

因此,openGemini Studio 应运而生。它是一款专门为 OpenGemini 设计的现代化桌面客户端,使用 Wails、Vue 3 和 TypeScript 构建,提供原生的桌面体验,让开发者和数据库管理员能够更高效地管理和操作 OpenGemini 数据库。

功能

核心功能

1. 多连接管理

  • 支持同时连接多个 OpenGemini 实例
  • 支持 HTTP/HTTPS 协议
  • 灵活的连接配置,包括 TLS/SSL 支持
  • 连接测试功能,确保连接正常

2. SQL 查询编辑器

  • 高级 InfluxQL 查询编辑器
  • 语法高亮显示
  • 自动补全功能
  • 支持快捷键执行查询 (Ctrl+Enter / Cmd+Enter)

3. 查询执行与结果展示

  • 实时查询结果显示
  • 性能指标统计(执行时间)
  • 可定制的表格格式
  • 可调整列宽的数据表格

4. 查询历史

  • 持久化查询历史记录
  • 记录查询成功/失败状态
  • 显示执行时间
  • 一键重用历史查询

数据库操作

5. 数据库浏览器

  • 树形视图浏览数据库结构
  • 查看 Measurements(测量)
  • 查看 Retention Policies(保留策略)
  • 查看字段(Fields)信息

6. 元数据管理

  • 查看和管理数据库元数据
  • 管理保留策略
  • 查看数据库统计信息

7. 数据写入

  • 支持 INSERT 操作
  • 支持 Line Protocol 格式
  • 批量操作支持

用户体验

8. 跨平台支持

  • 原生桌面应用
  • 支持 Windows、macOS 和 Linux

9. 国际化

  • 内置中英文支持
  • 界面语言可切换

10. 主题支持

  • 亮色主题
  • 暗色主题
  • 跟随系统主题

11. 个性化设置

  • 自定义字体
  • 可配置历史记录数量(10-500条)
  • 可自定义数据目录
  • 调试模式支持

12. 安全特性

  • TLS/SSL 加密连接
  • 自定义 CA 证书
  • 客户端证书和密钥支持
  • 用户名/密码认证

使用介绍

1. 安装与启动

下载并安装

从 Releases 页面 下载适合你平台的版本:

  • Windows: openGemini-studio-windows-amd64.exe
  • macOS: openGemini-studio-darwin-universal
  • Linux: openGemini-studio-linux-amd64

启动应用

直接双击运行下载的可执行文件,无需安装其他依赖。

2. 创建数据库连接

步骤:

  1. 启动 openGemini Studio
  2. 点击侧边栏的"添加连接"按钮
  3. 填写连接信息:
    • 连接名称: 为连接起一个便于识别的名字
    • 地址: OpenGemini 服务器地址(例如: localhost:8086)
    • 协议: 选择 HTTP 或 HTTPS
    • 认证: 如果服务器需要认证,启用并提供用户名和密码
  4. 点击"测试连接"验证连接是否正常
  5. 点击"保存连接"以持久化保存

TLS/SSL 配置(可选):

如果使用 HTTPS 协议,可以配置:

  • CA 证书路径
  • 客户端证书
  • 客户端密钥
  • 跳过证书验证(仅用于开发测试)

3. 浏览数据库

步骤:

  1. 在左侧连接树中,展开已保存的连接
  2. 点击连接名称,查看该实例下的所有数据库
  3. 展开数据库,可以看到:
    • Measurements(测量/表)
    • Retention Policies(保留策略)
    • Fields(字段)

提示:

  • 双击数据库名称可以快速在编辑器中插入 USE <database> 语句
  • 右键点击可以查看更多操作选项

4. 执行查询

基本查询步骤:

  1. 在左侧树中选择一个数据库
  2. 在查询编辑器中输入 InfluxQL 查询语句,例如: 
    SELECT * FROM measurement_name LIMIT 10
  3. 执行查询(任选其一):
    • 点击"执行查询"按钮
    • 按快捷键: Ctrl+Enter (Windows/Linux) 或 Cmd+Enter (macOS)
  4. 在下方的表格中查看查询结果

查询示例:

-- 查询最近 10 条记录
SELECT * FROM cpu_usage ORDER BY time DESC LIMIT 10

-- 按时间范围查询
SELECT * FROM temperature WHERE time > now() - 1h

-- 聚合查询
SELECT MEAN(value) FROM sensor_data WHERE time > now() - 1d GROUP BY time(1h)

-- 使用特定数据库
USE my_database
SELECT * FROM my_measurement

查询结果:

  • 结果以表格形式展示
  • 显示执行时间
  • 支持列宽调整
  • 大数据集自动分页

5. 查看和重用查询历史

步骤:

  1. 点击工具栏的"查询历史"按钮
  2. 在历史面板中查看过去执行的查询
  3. 每条历史记录显示:
    • 查询语句
    • 执行时间
    • 成功/失败状态
    • 执行时间戳
  4. 点击某条历史记录,该查询会被添加到当前编辑器中
  5. 可以修改后重新执行

清理历史:

  • 点击"清空历史"按钮可以删除所有历史记录
  • 也可以在设置中配置历史记录的最大数量

6. 写入数据

使用 INSERT 语句:

-- 插入单条数据
INSERT cpu,host=server01 value=85.5

-- 插入带时间戳的数据
INSERT temperature,location=room1 value=23.5 1609459200000000000

使用 Line Protocol(推荐):

Line Protocol 是 InfluxDB/OpenGemini 的标准写入格式:

measurement,tag1=value1,tag2=value2 field1=value1,field2=value2 timestamp

例如:

cpu,host=server01,region=us-west value=85.5,cores=8 1609459200000000000

7. 管理数据库

创建数据库:

CREATE DATABASE my_database

创建保留策略:

CREATE RETENTION POLICY "one_week" ON "my_database" DURATION 7d REPLICATION 1 DEFAULT

查看数据库:

SHOW DATABASES

查看测量(表):

SHOW MEASUREMENTS

查看字段:

SHOW FIELD KEYS

查看标签:

SHOW TAG KEYS

8. 配置应用设置

访问设置:

点击右上角的齿轮图标(设置按钮)

可配置项:

语言设置

  • 中文 (简体)
  • English

主题设置

  • 亮色主题
  • 暗色主题
  • 跟随系统

自定义字体

  • 输入字体名称(例如: Consolas, Monaco, JetBrains Mono)
  • 字体会应用到查询编辑器和结果表格

历史记录设置

  • 最大历史数量: 10-500 条
  • 超过限制后,旧的记录会被自动删除

调试模式

  • 启用后会输出详细的日志信息
  • 用于问题排查和性能分析

数据目录

  • 查看和配置数据存储路径
  • 存储连接配置和查询历史

9. 快捷键

  • 执行查询: Ctrl+Enter (Windows/Linux) 或 Cmd+Enter (macOS)
  • 更多快捷键可以在应用内查看

10. 故障排查

连接失败

  1. 检查 OpenGemini 服务是否正常运行
  2. 确认地址和端口是否正确
  3. 检查防火墙设置
  4. 如果使用 HTTPS,确认证书配置是否正确

查询错误

  1. 检查查询语法是否符合 InfluxQL 规范
  2. 确认数据库和测量名称是否存在
  3. 查看查询历史中的错误信息

性能问题

  1. 启用调试模式查看详细日志
  2. 减小查询结果集大小(使用 LIMIT)
  3. 优化查询语句(添加时间范围)

下载链接

最新版本下载

访问 GitHub Releases 页面下载最新版本:

https://github.com/openGemini/openGemini-studio/releases

平台支持

平台 下载文件 备注
Windows openGemini-studio-windows-amd64.exe 支持 Windows 10+
macOS openGemini-studio-darwin-universal 通用二进制文件,支持 Intel 和 Apple Silicon
Linux openGemini-studio-linux-amd64 支持大多数 Linux 发行版

从源码构建

如果你想从源码构建,可以参考以下步骤:

# 克隆仓库
git clone https://github.com/openGemini/openGemini-studio.git
cd openGemini-studio

# 安装 Wails CLI
go install github.com/wailsapp/wails/v2/cmd/wails@latest

# 构建应用
wails build

# 构建产物在 build/bin/ 目录下

系统要求

  • Windows: Windows 10 或更高版本
  • macOS: macOS 10.15 (Catalina) 或更高版本
  • Linux: 主流发行版,需要 glibc 2.27+

更新日志

查看每个版本的更新内容: https://github.com/openGemini/openGemini-studio/releases

反馈与支持

如果在使用过程中遇到问题或有功能建议,欢迎通过以下方式反馈: