文档首页/ 云数据库 GaussDB/ 开发指南（分布式_V2.0-10.x）/ 应用程序开发教程/ 基于Psycopg开发/ 开发步骤/ 环境准备
更新时间：2026-07-28 GMT+08:00
查看PDF
分享

环境准备

获取驱动包

下载表1中的驱动包和驱动包校验包。

表1 驱动包下载列表

版本

下载地址

V2.0-10.x

驱动包

驱动包校验包
为了防止软件包在传递过程或存储期间被恶意篡改，下载软件包时需下载对应的校验包对软件包进行校验，校验方法如下：
  • Linux操作系统软件包完整性校验：
    1. 上传软件包和软件包校验包到虚拟机的同一目录下。
    2. 执行如下命令，校验软件包完整性。 
      F=$(echo DBS-GaussDB-driver*.tar.gz);echo "$(awk '{print $1}' "$F.sha256")  $F" | sha256sum -c -

      如果回显OK，则校验通过。例如：

      DBS-GaussDB-driver_507.0_20260629130806.133858239.tar.gz: OK
  • Windows操作系统软件包完整性校验：
    1. 使用快捷键“Win+R”打开“运行”窗口。 在“打开”栏，输入“cmd”，按“Enter”回车，打开命令行页面。
    2. 执行以下命令，获取驱动包的Hash值。

      certutil -hashfile {驱动包本地目录}\{驱动包名} sha256

      • {驱动包本地目录}：请根据实际下载目录进行替换。例如：C:\Users
      • {驱动包名}：请根据实际下载的驱动包名进行替换。例如：DBS-GaussDB-driver_507.0_20260629130806.133858239.tar.gz

      示例：certutil -hashfile C:\Users\DBS-GaussDB-driver_507.0_20260629130806.133858239.tar.gz sha256

    3. 将2获取到的Hash值和表1中获取到的驱动包校验包的Hash值进行比较。
      • 若一致则通过校验。
      • 若不一致，请重新下载驱动包，重复1~3进行校验。

获取Python驱动包

以下介绍了获取Python驱动包的步骤：

  1. 解压获取到的驱动包。该包包含多种不同的驱动包，可根据后续步骤确定所需驱动包的文件路径。驱动包的文件层级关系参考以下结构。

    DBS-GaussDB-driver_*/数据库部署形态/驱动类型/操作系统架构/发布包/驱动包

  2. 选择数据库部署形态。

    分布式部署形态选择Distributed。

  3. 选择驱动类型。

    选择python_driver.tar.gz，并解压。

  4. 选择操作系统架构。

    用户需根据客户端所在机器操作系统来选择对应操作系统架构的驱动包。

  5. 选择Python发布包。
  6. 解压Python发布包，则可获取两种格式的驱动包，分别为tar.gz格式和whl格式。这两种格式的驱动包功能相同，用户根据自身业务需求选择对应的驱动包。

    • 非透明多写驱动包格式如下：

      GaussDB-Kernel_数据库版本号_Python_CPU架构_Python版本_Distributed.tar.gz

      > GaussDB-Kernel_数据库版本号_操作系统信息_64bit_Python.tar.gz

      > GaussDB_Kernel_数据库版本号-psycopg2版本号-Python版本-abiTag-支持的平台.whl

      示例：

      GaussDB-Kernel_507.0.0.B071_Python_X86_Py3.11_Distributed.tar.gz
> GaussDB-Kernel_507.0.0_Euler_64bit_Python.tar.gz
> GaussDB_Kernel_507_0_0-2.9.10-py311-none-linux_x86_64.whl
    • tar.gz格式驱动包，对其进行解压后包含两个文件夹：
      • psycopg2：表示python驱动的源码文件。
      • lib：表示python驱动的依赖库。
    • whl格式驱动包安装完成后，在对应python环境的site-packages目录中生成以下两个文件夹：
      • psycopg2：表示python驱动的源码文件。
      • gaussdb_psycopg2.lib：表示python驱动的依赖库。
    • whl格式驱动包命名规则说明：
      • abiTag：表示{abi tag}的信息，标记应用程序二进制接口（ABI）的标签（如：cp311或none）。
      • 支持的平台：表示{platform tag}的信息，标记支持的平台（如：linux_x86_64表示在Linux x86_64位系统上，any表示平台无关）。
    • whl格式驱动包使用约束：安装whl格式python驱动包时，需保证环境上的python版本与whl格式驱动包名中的“Python版本”保持一致。
    • 目前python驱动包仅支持python3.11版本。

安装前检查

安装psycopg2 Python驱动前，需检查环境上是否已安装开源psycopg2 Python驱动，如果已安装开源psycopg2 Python驱动则需要进行清理操作，否则会影响Python驱动的使用。请按以下步骤进行检查操作：

  1. 切换至root用户，执行以下命令检查环境中是否已安装psycopg2 Python驱动。 

    ll $(python3 -c 'import site; print(site.getsitepackages()[0])') | grep psycopg2

    如果存在输出对应的目录，则执行下一步，否则结束检查。

  2. 执行以下命令，清理已经安装的Psycopg2驱动文件。 

    rm -rf $(python3 -c 'import site; print(site.getsitepackages()[0])')/psycopg2*

导入tar.gz格式驱动包并配置环境变量

  1. 将“GaussDB-Kernel_数据库版本号_操作系统信息_64bit_Python.tar.gz”驱动包导入到环境root根目录。
  2. 解压驱动包。 

    tar zxvf xxxx_Python.tar.gz

  3. 切换至root用户，将psycopg2驱动源码文件复制到python安装目录下的site-packages文件夹下。 

    su root
cp psycopg2 $(python3 -c 'import site; print(site.getsitepackages()[0])') -r

    $(python3 -c 'import site; print(site.getsitepackages()[0])')命令的作用是获取python用于安装第三方包的site-packages目录主路径。当出现目录不存在的报错时，可通过python3 -c "import site; print(site.getsitepackages())"命令获取python site-packages目录的路径列表，从中找一个有效路径替代。

  4. 修改psycopg2目录权限为755。 

    chmod 755 $(python3 -c 'import site; print(site.getsitepackages()[0])')/psycopg2 -R

  5. 将psycopg2目录配置到环境变量PYTHONPATH中，并使之生效。 

    export PYTHONPATH=$(python3 -c 'import site; print(site.getsitepackages()[0])'):$PYTHONPATH

  6. 对于非数据库用户，需要将解压后的lib目录的绝对路径[path-to-lib]配置到环境变量LD_LIBRARY_PATH。 

    export LD_LIBRARY_PATH=[path-to-lib]:$LD_LIBRARY_PATH

    对于数据库用户，则无需手动配置LD_LIBRARY_PATH。

导入whl格式驱动包并配置环境变量

安装whl格式驱动包时，如果数据库已安装过“GaussDB_Kernel_数据库版本号-psycopg2版本号-Python版本-abiTag-支持的平台.whl”驱动包且未通过“pip3 uninstall”或“python3 -m pip uninstall”命令卸载驱动包， 建议先通过“pip3 uninstall”或“python3 -m pip uninstall”命令卸载对应的驱动包。具体操作请参见方式二。

  1. 将“GaussDB_Kernel_数据库版本号-psycopg2版本号-Python版本-abiTag-支持的平台.whl”驱动包导入到环境root根目录。
  2. 切换至root用户，安装whl格式驱动包。 

    su root
    环境支持pip命令时，执行如下命令： 
    pip3 install GaussDB_Kernel_数据库版本号-psycopg2版本号-Python版本-abiTag-支持的平台.whl

    环境不支持pip命令时，执行如下命令：

    python3 -m pip install GaussDB_Kernel_数据库版本号-psycopg2版本号-Python版本-abiTag-支持的平台.whl

  3. （可选）执行如下命令为非root用户赋予使用python驱动的权限。 

    chmod 755 $(python3 -c 'import site; print(site.getsitepackages()[0])')/psycopg2 -R

    $(python3 -c 'import site; print(site.getsitepackages()[0])')命令的作用是获取python用于安装第三方包的site-packages目录主路径。当出现目录不存在的报错时，可通过python3 -c "import site; print(site.getsitepackages())"命令获取python site-packages目录的路径列表，从中找一个有效路径替代。

  4. 配置环境变量。

    • 对于非数据库用户，需要将安装whl格式驱动包后的lib目录配置到环境变量LD_LIBRARY_PATH中。 
      lib_path=$(python3 -c 'import site; print(site.getsitepackages()[0]+"/gaussdb_psycopg2.lib")')
export LD_LIBRARY_PATH=$lib_path:$LD_LIBRARY_PATH
    • 对于安装数据库用户，无需手动配置环境变量LD_LIBRARY_PATH。

（可选）卸载驱动包

  1. 切换至root用户。 

    su root

  2. 执行如下命令卸载python驱动。

    • 方式一：推荐通过tar.gz格式驱动包安装python驱动方式时使用，通过whl格式驱动包安装python驱动也可使用，但推荐使用方式二。 
      site_package_path=$(python3 -c 'import site; print(site.getsitepackages()[0])')
rm -rf $site_package_path/psycopg2

      site_package_path=$(python3 -c 'import site; print(site.getsitepackages()[0])')命令的作用是获取python用于安装第三方包的site-packages目录主路径。当出现目录不存在的报错时，可通过python3 -c "import site; print(site.getsitepackages())"命令获取python site-packages目录的路径列表，从中找一个有效路径替代。

      • 卸载whl格式驱动包时执行以下命令： 
        rm -rf $site_package_path/gaussdb_psycopg2.lib $site_package_path/GaussDB_Kernel_*.dist-info
      • 卸载tar.gz格式驱动包时执行以下命令： 
        rm -rf [path-to-lib]

        其中，[path-to-lib]表示安装tar.gz格式驱动包时，用户存放lib目录的位置。

    • 方式二：仅适用于通过whl格式驱动包安装python驱动的方式时使用。
      • 若通过pip install方式安装whl格式驱动包时，建议执行如下命令： 
        pip3 uninstall GaussDB_Kernel_数据库版本号-psycopg2版本号-Python版本-abiTag-支持的平台.whl
      • 若通过python3 -m pip install方式安装whl格式驱动包时，建议执行如下命令： 
        python3 -m pip uninstall GaussDB_Kernel_数据库版本号-psycopg2版本号-Python版本-abiTag-支持的平台.whl

父主题： 开发步骤

相关文档