clickhouse/dotnet-client

ClickHouse.NET客户端集成测试镜像

镜像概述

本镜像提供预配置的ClickHouse.NET客户端环境，旨在简化基于.NET的ClickHouse数据库集成测试流程。通过Docker容器化确保测试环境的一致性和隔离性，消除本地开发与测试环境的依赖冲突，帮助开发和测试人员高效验证应用程序与ClickHouse的交互功能。

核心功能与特性

• 完整客户端工具链：集成ClickHouse.NET客户端库，支持标准ClickHouse操作（查询执行、数据插入、连接管理等核心功能）。
• 环境一致性：容器化部署确保不同环境（开发、测试、CI/CD）使用相同的客户端版本和配置，避免"在我机器上能运行"问题。
• 轻量级设计：基于精简.NET运行时镜像构建，启动速度快，资源占用低，适合高频集成测试场景。
• 灵活配置：支持通过环境变量或配置文件自定义ClickHouse连接参数，适配多种测试场景需求。

使用场景与适用范围

适用场景

• 集成测试验证：在单元测试或集成测试中验证应用程序与ClickHouse的交互逻辑（如查询结果正确性、数据写入性能、异常处理机制等）。
• CI/CD流水线集成：嵌入自动化测试环节，在代码提交或构建过程中自动执行ClickHouse集成测试，确保代码变更不破坏数据库交互功能。
• 本地开发调试：开发人员快速启动客户端环境，本地调试ClickHouse交互代码，无需手动配置本地客户端依赖。

适用范围

• .NET技术栈项目（支持.NET Framework/.NET Core/.NET 5+）
• 依赖ClickHouse数据库的应用程序测试流程
• 需要自动化验证数据库交互功能的开发团队

使用方法与配置说明

基本使用流程

1. 确保本地已安装Docker环境
2. 拉取或构建镜像
3. 配置ClickHouse连接参数（环境变量或配置文件）
4. 挂载测试项目并执行测试命令

Docker部署示例

1. 基础运行命令

bash
docker run --rm \
  -e CLICKHOUSE_HOST=clickhouse-server \  # ClickHouse服务主机地址
  -e CLICKHOUSE_PORT=8123 \               # ClickHouse HTTP端口
  -e CLICKHOUSE_USER=default \            # ClickHouse用户名
  -e CLICKHOUSE_PASSWORD= \               # ClickHouse密码（默认空）
  -v $(pwd)/test-project:/app/test-project \  # 挂载本地测试项目目录
  clickhouse-net-client:latest \          # 镜像名称及标签
  dotnet test /app/test-project           # 执行测试命令

2. CI/CD流水线集成（GitHub Actions示例）

yaml
jobs:
  clickhouse-test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Start ClickHouse server
        run: docker run -d --name clickhouse -p 8123:8123 clickhouse/clickhouse-server:latest
      
      - name: Run integration tests
        run: |
          docker run --rm \
            -e CLICKHOUSE_HOST=host.docker.internal \
            -e CLICKHOUSE_PORT=8123 \
            -v $(pwd)/tests:/app/tests \
            clickhouse-net-client:latest \
            dotnet test /app/tests --logger "console;verbosity=detailed"

配置参数说明

环境变量

卷挂载说明

• 测试项目目录：建议将本地测试项目代码挂载至容器内/app目录（如-v $(pwd)/tests:/app/tests），确保容器可访问测试代码并执行测试命令。
• 配置文件（可选）：如需自定义客户端高级配置（如连接超时、重试策略等），可挂载配置文件至/app/config目录，客户端将优先读取该目录下的配置。

注意事项

• 确保ClickHouse服务与客户端容器网络互通（可通过--network参数加入同一网络，或使用host.docker.internal访问宿主机服务）。
• 测试项目需与容器的.NET版本兼容，建议在项目文件中明确指定目标框架（如<TargetFramework>net6.0</TargetFramework>）。
• 本镜像仅用于测试场景，不建议直接用于生产环境的ClickHouse客户端部署。