yottadb/octo

YottaDB Octo Docker镜像文档

1. 镜像概述和主要用途

YottaDB Octo Docker镜像是YottaDB数据库管理系统的官方SQL插件镜像，提供了一个SQL数据库引擎，通过SQL接口与YottaDB数据存储交互。该镜像封装了Octo的最新版本，旨在为YottaDB用户提供便捷的SQL访问能力，允许通过标准SQL语法查询、插入、更新和删除YottaDB中的数据，实现SQL与YottaDB高性能键值存储的无缝集成。

2. 核心功能和特性

• SQL标准支持：兼容核心SQL-92标准，支持常用SQL操作（SELECT、INSERT、UPDATE、DELETE等）及函数。
• YottaDB无缝集成：直接与YottaDB数据存储交互，无需数据迁移，保留YottaDB的ACID特性和高性能。
• 高性能查询处理：优化的查询执行引擎，适配YottaDB的存储结构，减少查询延迟。
• 多客户端支持：兼容PostgreSQL客户端协议，可使用psql、DBeaver等标准SQL工具连接。
• 轻量级部署：基于Docker容器化，简化安装和配置流程，支持快速启停和环境一致性。

3. 使用场景和适用范围

• YottaDB SQL接口需求：现有YottaDB用户需要通过SQL访问数据，避免重构现有SQL应用。
• 数据集成与分析：需将YottaDB数据接入SQL生态工具（如BI平台、报表工具、ETL流程）。
• 应用开发：开发新的SQL应用，同时利用YottaDB的高并发、低延迟存储能力。
• 测试与原型验证：快速搭建SQL+YottaDB环境，验证数据模型或查询逻辑。

4. 使用方法和配置说明

4.1 前提条件

• 已安装Docker Engine（20.10+）或Docker Desktop。
• （可选）YottaDB数据库实例（本地目录或容器，需通过挂载或网络访问）。

4.2 环境变量配置

Octo镜像通过环境变量调整运行参数，常用变量如下：

4.3 数据持久化

通过Docker卷挂载YottaDB数据目录，确保数据持久化：

• YottaDB实例路径：需挂载宿主机目录（如/path/to/local/ydb）到容器内YDB_PATH（默认/ydb）。

4.4 启动命令示例

4.4.1 基础启动（使用默认配置）

bash
docker run -d \
  --name octo \
  -p 5432:5432 \
  -v /path/to/local/ydb:/ydb \  # 挂载YottaDB数据目录
  -e OCTO_PASSWORD="mysecret" \  # 设置用户密码
  yottadb/octo:latest

4.4.2 自定义端口和日志级别

bash
docker run -d \
  --name octo-custom \
  -p 5433:5432 \  # 宿主机端口5433映射到容器5432
  -v /local/ydb:/ydb \
  -e YDB_PATH="/ydb/custom" \  # 自定义YottaDB路径
  -e OCTO_PORT=5432 \
  -e OCTO_LOG_LEVEL="DEBUG" \
  yottadb/octo:latest

4.5 Docker Compose配置

创建docker-compose.yml实现多容器协作（如Octo+YottaDB）：

yaml
version: "3.8"
services:
  octo:
    image: yottadb/octo:latest
    container_name: octo
    ports:
      - "5432:5432"
    environment:
      - YDB_PATH=/ydb
      - OCTO_PASSWORD=octo123
      - OCTO_LOG_LEVEL=INFO
    volumes:
      - ydb_data:/ydb  # 使用命名卷持久化YottaDB数据
    depends_on:
      - yottadb  # （可选）若依赖独立YottaDB容器

  # （可选）YottaDB独立容器（若不使用宿主机实例）
  yottadb:
    image: yottadb/yottadb:latest
    container_name: yottadb
    volumes:
      - ydb_data:/ydb
    command: ["-r", "utf8"]  # 设置YottaDB字符集

volumes:
  ydb_data:  # 命名卷，自动创建并持久化

启动命令：docker-compose up -d

4.6 客户端连接

使用PostgreSQL兼容客户端连接Octo服务：

bash
psql -h localhost -p 5432 -U octo -d octo

（连接时输入环境变量OCTO_PASSWORD设置的密码）

4.7 初始化SQL脚本

通过挂载初始化脚本目录，自动执行SQL建表或数据导入：

bash
docker run -d \
  --name octo-init \
  -p 5432:5432 \
  -v /local/ydb:/ydb \
  -v /local/init-scripts:/docker-entrypoint-initdb.d \  # 挂载初始化脚本目录
  yottadb/octo:latest

容器启动时会自动执行/docker-entrypoint-initdb.d目录下的.sql脚本。

5. 故障排查

• 连接失败：检查OCTO_PORT映射是否正确，YDB_PATH目录权限是否允许容器访问。
• 日志查看：通过docker logs octo查看运行日志，调整OCTO_LOG_LEVEL=DEBUG获取详细信息。
• 数据不一致：确认YDB_PATH挂载的目录与YottaDB实例路径一致，避免数据路径冲突。

6. 参考文档

完整使用说明请参见官方文档：
Octo Docker镜像使用指南