495 lines
13 KiB
Markdown
495 lines
13 KiB
Markdown
# 附录：Psycopg安装、环境选择与常见问题排查
|
||
|
||
## 一、附录用途
|
||
|
||
本附录集中说明Windows环境下安装Psycopg 3时容易混淆的问题，并整理本课程实际遇到的错误。正文只保留数据库编程主线；安装失败、解释器不一致或原生库异常时，再查阅本附录。
|
||
|
||
本附录覆盖两种安装方式：
|
||
|
||
1. 使用pip安装；
|
||
2. 使用Conda安装。
|
||
|
||
无论选择哪一种，都应先创建课程专用环境，不建议把课程依赖继续安装到系统级`base`环境。
|
||
|
||
## 二、先分清Psycopg 2和Psycopg 3
|
||
|
||
以下名称非常相似，但不是同一个版本：
|
||
|
||
| 安装包 | Python导入语句 | 说明 |
|
||
|---|---|---|
|
||
| `psycopg` | `import psycopg` | Psycopg 3主体包 |
|
||
| `psycopg-binary` | 仍然使用`import psycopg` | Psycopg 3预编译二进制实现 |
|
||
| `psycopg-c` | 仍然使用`import psycopg` | Psycopg 3本地C扩展实现 |
|
||
| `psycopg2` | `import psycopg2` | Psycopg 2源码/本地库方案 |
|
||
| `psycopg2-binary` | `import psycopg2` | Psycopg 2预编译方案 |
|
||
|
||
不存在以下正确导入方式：
|
||
|
||
```python
|
||
import psycopg3
|
||
import psycopg_binary
|
||
import psycopg2_binary
|
||
```
|
||
|
||
本课程使用Psycopg 3，因此代码统一写：
|
||
|
||
```python
|
||
import psycopg
|
||
```
|
||
|
||
如果编辑器只能找到`psycopg2`，通常表示安装的是Psycopg 2，或者编辑器选用了另一个Python解释器。
|
||
|
||
## 三、Psycopg 3的三种底层实现
|
||
|
||
Psycopg 3主体包会选择一种底层`libpq`包装实现。`libpq`是PostgreSQL官方客户端库，负责底层数据库通信。
|
||
|
||
| 实现 | 常见安装方式 | 特点 | 额外要求 |
|
||
|---|---|---|---|
|
||
| `python` | `pip install psycopg` | 纯Python包装，适合调试和小型任务 | 系统中必须能找到`libpq` |
|
||
| `c` | `pip install "psycopg[c]"`或Conda的`psycopg-c` | C扩展，性能较好 | 本地`libpq`；pip源码构建还需要编译工具 |
|
||
| `binary` | `pip install "psycopg[binary]"` | 预编译并自带客户端库，安装最省事 | 需要当前Python和平台存在可用二进制包 |
|
||
|
||
查看当前实际使用的实现：
|
||
|
||
```powershell
|
||
python -c "import psycopg, psycopg.pq; print(psycopg.__version__); print(psycopg.pq.__impl__); print(psycopg.pq.version())"
|
||
```
|
||
|
||
可能输出：
|
||
|
||
```text
|
||
3.3.4
|
||
binary
|
||
180004
|
||
```
|
||
|
||
其中：
|
||
|
||
- 第一行是Psycopg版本；
|
||
- 第二行是`python`、`c`或`binary`实现；
|
||
- 第三行是实际加载的`libpq`版本号。
|
||
|
||
## 四、安装前先确认当前环境
|
||
|
||
### 4.1 查看Conda环境
|
||
|
||
```powershell
|
||
conda env list
|
||
```
|
||
|
||
当前激活环境前会显示`*`。
|
||
|
||
### 4.2 查看Python解释器
|
||
|
||
```powershell
|
||
python -c "import sys; print(sys.executable); print(sys.version)"
|
||
```
|
||
|
||
如果课程环境名为`python-test`，路径应类似：
|
||
|
||
```text
|
||
C:\Users\你的用户名\.conda\envs\python-test\python.exe
|
||
```
|
||
|
||
如果仍然显示：
|
||
|
||
```text
|
||
C:\ProgramData\miniconda3\python.exe
|
||
```
|
||
|
||
说明当前使用的还是系统级`base`解释器。
|
||
|
||
### 4.3 为什么不推荐系统级base
|
||
|
||
系统级Miniconda可能安装在：
|
||
|
||
```text
|
||
C:\ProgramData\miniconda3
|
||
```
|
||
|
||
普通用户通常没有写权限，安装时会出现：
|
||
|
||
```text
|
||
EnvironmentNotWritableError
|
||
```
|
||
|
||
独立环境还可以避免数据库课程依赖污染其他Python项目，也便于删除和重建。
|
||
|
||
## 五、方式一：使用pip安装
|
||
|
||
### 5.1 创建并激活Conda环境
|
||
|
||
可以让Conda只负责环境和Python，再让pip安装Psycopg：
|
||
|
||
```powershell
|
||
conda create -n python-test python=3.13 pip
|
||
conda activate python-test
|
||
```
|
||
|
||
### 5.2 推荐安装命令
|
||
|
||
本地学习优先使用预编译二进制实现：
|
||
|
||
```powershell
|
||
python -m pip install "psycopg[binary]>=3,<4"
|
||
```
|
||
|
||
也可以使用本课的依赖文件：
|
||
|
||
```powershell
|
||
python -m pip install -r requirements.txt
|
||
```
|
||
|
||
`requirements.txt`中的：
|
||
|
||
```text
|
||
psycopg[binary]>=3,<4
|
||
```
|
||
|
||
表示：
|
||
|
||
- 安装Psycopg 3；
|
||
- 同时安装`binary`额外依赖；
|
||
- 版本不低于3且低于4。
|
||
|
||
### 5.3 为什么使用`python -m pip`
|
||
|
||
不要优先直接执行：
|
||
|
||
```powershell
|
||
pip install ...
|
||
```
|
||
|
||
直接运行`pip.exe`时，可能遇到访问被拒绝，或者调用了其他环境中的pip。下面的写法明确表示“使用当前Python解释器对应的pip”：
|
||
|
||
```powershell
|
||
python -m pip install ...
|
||
```
|
||
|
||
这能降低“包安装成功，但程序使用另一个Python”的概率。
|
||
|
||
### 5.4 pip国内镜像临时用法
|
||
|
||
如果访问PyPI失败，可以只为当前命令指定镜像：
|
||
|
||
```powershell
|
||
python -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "psycopg[binary]>=3,<4"
|
||
```
|
||
|
||
临时指定不会永久修改系统或用户配置。
|
||
|
||
### 5.5 pip安装后的确认
|
||
|
||
```powershell
|
||
python -m pip show psycopg psycopg-binary
|
||
python -c "import sys, psycopg, psycopg.pq; print(sys.executable); print(psycopg.__version__); print(psycopg.pq.__impl__)"
|
||
```
|
||
|
||
预期底层实现通常是：
|
||
|
||
```text
|
||
binary
|
||
```
|
||
|
||
## 六、方式二：使用Conda安装
|
||
|
||
### 6.1 创建独立环境并一次安装
|
||
|
||
推荐让核心包全部来自`conda-forge`，减少Python、OpenSSL和`libpq`混用不同频道的风险：
|
||
|
||
```powershell
|
||
conda create -n python-db --override-channels -c conda-forge python=3.13 psycopg psycopg-c libpq openssl
|
||
conda activate python-db
|
||
```
|
||
|
||
如果已经创建了`python-test`：
|
||
|
||
```powershell
|
||
conda activate python-test
|
||
conda install -c conda-forge psycopg psycopg-c libpq
|
||
```
|
||
|
||
不要在激活`python-test`后仍然写：
|
||
|
||
```powershell
|
||
conda install -n base ...
|
||
```
|
||
|
||
`-n base`会明确要求安装到`base`，不会因为当前激活了`python-test`而自动改用当前环境。
|
||
|
||
### 6.2 Conda不能使用pip的`-r`
|
||
|
||
下面的命令是错误的：
|
||
|
||
```powershell
|
||
conda install -r requirements.txt
|
||
```
|
||
|
||
`-r requirements.txt`是pip的参数，不是Conda的通用安装方式。对应写法是：
|
||
|
||
```powershell
|
||
python -m pip install -r requirements.txt
|
||
```
|
||
|
||
使用Conda时则应直接写包名：
|
||
|
||
```powershell
|
||
conda install -c conda-forge psycopg psycopg-c libpq
|
||
```
|
||
|
||
### 6.3 配置清华Conda镜像
|
||
|
||
访问官方`conda-forge`失败时，可以把`conda-forge`映射到清华镜像：
|
||
|
||
```powershell
|
||
conda config --set show_channel_urls yes
|
||
conda config --set custom_channels.conda-forge https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
|
||
conda clean --index-cache
|
||
```
|
||
|
||
查看最终配置来源：
|
||
|
||
```powershell
|
||
conda config --show-sources
|
||
conda config --show custom_channels
|
||
```
|
||
|
||
Windows用户级配置通常位于：
|
||
|
||
```text
|
||
C:\Users\你的用户名\.condarc
|
||
```
|
||
|
||
然后重新安装：
|
||
|
||
```powershell
|
||
conda activate python-test
|
||
conda install -c conda-forge psycopg psycopg-c libpq
|
||
```
|
||
|
||
### 6.4 Conda安装后的确认
|
||
|
||
```powershell
|
||
conda list | Select-String "python|psycopg|libpq|openssl"
|
||
python -c "import sys, psycopg, psycopg.pq; print(sys.executable); print(psycopg.__version__); print(psycopg.pq.__impl__); print(psycopg.pq.version())"
|
||
```
|
||
|
||
使用`psycopg-c`时，底层实现应为：
|
||
|
||
```text
|
||
c
|
||
```
|
||
|
||
## 七、pip和Conda的区别
|
||
|
||
| 对比项 | pip | Conda |
|
||
|---|---|---|
|
||
| 主要管理对象 | Python包 | Python包、解释器和原生库 |
|
||
| 默认软件仓库 | PyPI | defaults或conda-forge等频道 |
|
||
| 环境创建 | 通常配合`venv`或Conda | 原生支持`conda create` |
|
||
| `libpq`、OpenSSL等原生依赖 | binary包可自带；否则依赖系统 | 可以作为Conda包统一安装 |
|
||
| 安装速度与包可用性 | PyPI新版本通常更及时 | 取决于频道是否已构建对应平台包 |
|
||
| 依赖解析范围 | 主要关注Python包 | 同时解析Python和原生库依赖 |
|
||
| 本课推荐场景 | 希望安装简单、使用`binary`实现 | 希望统一管理Python、C扩展和`libpq` |
|
||
|
||
### 7.1 pip方案的优势
|
||
|
||
- 命令与大多数Python项目的`requirements.txt`一致；
|
||
- `psycopg[binary]`通常安装最直接；
|
||
- 预编译包自带所需客户端库，受本机DLL路径影响较小；
|
||
- PyPI上的版本通常更新较快。
|
||
|
||
### 7.2 Conda方案的优势
|
||
|
||
- 可以同时管理Python、`psycopg-c`、`libpq`和OpenSSL；
|
||
- 不需要手工准备Visual Studio C++编译环境；
|
||
- 适合已经使用Conda管理数据分析或科学计算环境的项目。
|
||
|
||
### 7.3 不建议随意混装
|
||
|
||
同一个环境中可以混合使用Conda和pip，但顺序和边界必须清楚。推荐：
|
||
|
||
1. 先用Conda安装Python及能够满足的原生依赖；
|
||
2. 再用当前环境的`python -m pip`安装Conda没有的Python包；
|
||
3. pip安装后不要再让Conda大范围重算并替换同一批核心依赖；
|
||
4. 出现原生崩溃时，检查Python、Psycopg、`libpq`和OpenSSL是否来自相互兼容的来源。
|
||
|
||
本课程选择一种方案成功后即可，不需要同时安装`psycopg-c`和`psycopg-binary`。
|
||
|
||
## 八、实际遇到的问题与原因
|
||
|
||
### 8.1 `conda install -r requirements.txt`报参数错误
|
||
|
||
错误原因：把pip参数用于Conda。
|
||
|
||
正确处理：
|
||
|
||
```powershell
|
||
python -m pip install -r requirements.txt
|
||
```
|
||
|
||
或者使用Conda包名安装。
|
||
|
||
### 8.2 直接运行`pip.exe`显示`Access is denied`
|
||
|
||
可能原因包括`pip.exe`权限、命令解析或环境路径异常。
|
||
|
||
优先改为：
|
||
|
||
```powershell
|
||
python -m pip install -r requirements.txt
|
||
```
|
||
|
||
同时用`sys.executable`确认当前Python。
|
||
|
||
### 8.3 `EnvironmentNotWritableError`
|
||
|
||
典型信息：
|
||
|
||
```text
|
||
environment location: C:\ProgramData\miniconda3
|
||
```
|
||
|
||
原因：普通用户没有系统级`base`环境写权限。
|
||
|
||
推荐处理：创建用户自己的独立环境，不要修改系统目录权限：
|
||
|
||
```powershell
|
||
conda create -n python-test python=3.13 pip
|
||
conda activate python-test
|
||
```
|
||
|
||
### 8.4 激活新环境后仍然安装到base
|
||
|
||
错误命令：
|
||
|
||
```powershell
|
||
conda activate python-test
|
||
conda install -n base -c conda-forge psycopg
|
||
```
|
||
|
||
`-n base`覆盖了当前环境选择。正确写法：
|
||
|
||
```powershell
|
||
conda install -c conda-forge psycopg
|
||
```
|
||
|
||
或明确指定：
|
||
|
||
```powershell
|
||
conda install -n python-test -c conda-forge psycopg
|
||
```
|
||
|
||
### 8.5 CondaHTTPError访问`conda-forge`失败
|
||
|
||
先检查：
|
||
|
||
```powershell
|
||
conda config --show-sources
|
||
conda config --show channels
|
||
conda config --show proxy_servers
|
||
```
|
||
|
||
配置没有错误时，可能是网络、代理或官方源可达性问题。可以使用前面的清华镜像配置后清理索引缓存重试。
|
||
|
||
### 8.6 只能导入`psycopg2`
|
||
|
||
原因通常是安装了`psycopg2-binary`，而不是Psycopg 3。
|
||
|
||
确认命令：
|
||
|
||
```powershell
|
||
python -c "import importlib.util; print(importlib.util.find_spec('psycopg')); print(importlib.util.find_spec('psycopg2'))"
|
||
python -m pip show psycopg psycopg-binary psycopg2-binary
|
||
```
|
||
|
||
本课程需要`psycopg`能够被找到。
|
||
|
||
### 8.7 `no pq wrapper available`
|
||
|
||
典型信息：
|
||
|
||
```text
|
||
- couldn't import psycopg 'c' implementation
|
||
- couldn't import psycopg 'binary' implementation
|
||
- couldn't import psycopg 'python' implementation: libpq library not found
|
||
```
|
||
|
||
含义：
|
||
|
||
- 没有`psycopg-c`；
|
||
- 没有`psycopg-binary`；
|
||
- 纯Python实现又找不到`libpq`。
|
||
|
||
解决方式任选其一：
|
||
|
||
```powershell
|
||
python -m pip install psycopg-binary
|
||
```
|
||
|
||
或者通过Conda安装完整本地库：
|
||
|
||
```powershell
|
||
conda install -c conda-forge psycopg psycopg-c libpq
|
||
```
|
||
|
||
### 8.8 PyCharm退出代码`0xC0000005`
|
||
|
||
`0xC0000005`是Windows原生访问冲突，不是普通Python异常，`try...except`无法捕获。它曾发生在`psycopg.connect()`进入C扩展或客户端DLL后。
|
||
|
||
排查步骤：
|
||
|
||
1. 在终端使用同一个解释器运行同一文件；
|
||
2. 输出`sys.executable`确认解释器一致；
|
||
3. 输出`psycopg.pq.__impl__`确认底层实现；
|
||
4. 检查环境是否混用了不同频道的Python、`psycopg-c`、`libpq`和OpenSSL；
|
||
5. 优先重建核心包来源一致的环境；
|
||
6. 本地学习也可以改用`psycopg-binary`降低DLL路径差异。
|
||
|
||
Conda的Windows原生库通常位于：
|
||
|
||
```text
|
||
C:\Users\你的用户名\.conda\envs\环境名\Library\bin
|
||
```
|
||
|
||
PyCharm必须选择正确的Conda解释器。必要时检查其运行配置是否能找到该目录中的DLL。
|
||
|
||
## 九、编辑器解释器检查
|
||
|
||
在PyCharm中选择的解释器必须与终端验证成功的解释器一致。例如：
|
||
|
||
```text
|
||
C:\Users\你的用户名\.conda\envs\python-test\python.exe
|
||
```
|
||
|
||
可以在程序中临时确认：
|
||
|
||
```python
|
||
import sys
|
||
|
||
print(sys.executable)
|
||
```
|
||
|
||
如果终端能够导入、PyCharm不能导入，通常不是代码问题，而是编辑器解释器或原生库搜索路径不同。
|
||
|
||
## 十、最终安装验收清单
|
||
|
||
依次执行：
|
||
|
||
```powershell
|
||
conda env list
|
||
python -c "import sys; print(sys.executable); print(sys.version)"
|
||
python -c "import psycopg, psycopg.pq; print(psycopg.__version__); print(psycopg.__file__); print(psycopg.pq.__impl__); print(psycopg.pq.version())"
|
||
```
|
||
|
||
验收标准：
|
||
|
||
- Python路径指向预期的课程环境；
|
||
- `import psycopg`成功；
|
||
- Psycopg主版本为3；
|
||
- 底层实现是预期的`binary`、`c`或`python`；
|
||
- PyCharm与PowerShell使用同一个解释器；
|
||
- 实际运行第一课连接示例时不出现导入错误或原生崩溃。
|
||
|
||
安装只解决客户端依赖。数据库地址、端口、防火墙、代理、PostgreSQL监听和账号权限属于连接问题，应与安装问题分开判断。
|