# 附录：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监听和账号权限属于连接问题，应与安装问题分开判断。