thesashi/ci-psql-pg_trgm

psql-circleci-pgtrgm 镜像文档

镜像概述

该镜像为CircleCI持续集成/持续部署(CI/CD)环境提供优化的PostgreSQL客户端(psql)工具，预安装并启用pg_trgm扩展。pg_trgm扩展提供基于 trigram（三元字符组）的文本相似度搜索功能，适用于需要在CI流程中验证数据库文本搜索功能或执行相关数据库操作的场景。

核心功能与特性

• 预配置环境：内置psql客户端及PostgreSQL依赖库，可直接用于数据库连接与操作
• pg_trgm扩展支持：预安装并启用pg_trgm扩展，支持文本相似度计算、模糊匹配等功能
• CircleCI兼容性：针对CircleCI运行环境优化，轻量级设计确保快速加载
• 灵活配置：支持通过环境变量配置数据库连接参数，适应不同测试环境需求

使用场景与适用范围

• CircleCI流水线中的数据库迁移脚本执行
• PostgreSQL数据库测试环境初始化与验证
• 基于pg_trgm的文本搜索功能自动化测试
• CI/CD流程中的数据库查询执行与数据校验
• 数据库索引性能测试（特别是基于trgm的GIN索引）

使用方法与配置说明

基本使用（Docker Run）

bash
docker run --rm \
  -e POSTGRES_HOST=your-postgres-host \
  -e POSTGRES_PORT=5432 \
  -e POSTGRES_USER=testuser \
  -e POSTGRES_PASSWORD=testpass \
  -e POSTGRES_DB=testdb \
  psql-circleci-pgtrgm \
  psql -c "SELECT similarity('hello world', 'hello there');"

环境变量配置

CircleCI配置示例

在.circleci/config.yml中集成该镜像：

yaml
version: 2.1
jobs:
  test-db-search:
    docker:
      - image: psql-circleci-pgtrgm
    environment:
      POSTGRES_HOST: postgres
      POSTGRES_USER: circleci
      POSTGRES_PASSWORD: password
      POSTGRES_DB: test_db
    steps:
      - run:
          name: 验证pg_trgm功能
          command: |
            psql -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"
            psql -c "SELECT word_similarity('postgres', 'postgresql');"
            psql -c "SELECT * FROM products WHERE name % 'laptop';"
  postgres:
    image: postgres:14
    environment:
      POSTGRES_USER: circleci
      POSTGRES_PASSWORD: password
      POSTGRES_DB: test_db

workflows:
  test:
    jobs:
      - postgres
      - test-db-search:
          requires:
            - postgres

pg_trgm功能使用示例

执行包含pg_trgm功能的SQL命令：

sql
-- 创建扩展（首次使用时）
CREATE EXTENSION IF NOT EXISTS pg_trgm;

-- 计算文本相似度
SELECT similarity('apple pie', 'apple tart'); -- 返回相似度值

-- 模糊匹配查询
SELECT * FROM documents WHERE content % 'search term';

-- 创建trgm索引提升查询性能
CREATE INDEX idx_documents_content_trgm ON documents USING gin(content gin_trgm_ops);

注意事项

• 确保目标PostgreSQL数据库版本与pg_trgm扩展版本兼容（建议PostgreSQL 10+）
• 在CI环境中使用时，需确保数据库服务已启动并可被容器访问
• 敏感信息（如密码）建议通过CircleCI环境变量安全注入，避免硬编码