Bruce/PythonLearn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(数据库): 完善第四阶段SQLAlchemy课程与综合项目

Browse Source
This commit is contained in:
zhiye.sun
2026-08-20 15:45:21 +08:00
parent a28c3b3168
commit bf1f7042a9
18 changed files with 3039 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
04_数据库/4_1_PostgreSQL与Psycopg入门/README.md
+10 -6
View File
@@ -73,19 +73,23 @@ TOML（Tom's Obvious Minimal Language）是一种结构化配置格式。Python
## 六、安装 Psycopg 3
你当前使用 Conda 的 `base` 环境，可以直接安装 Psycopg：
安装前建议创建课程专用环境，不要默认向系统级`base`环境安装。本课程同时支持pip和Conda两种方式。下面的命令假设PowerShell已经进入本课目录，并且已经激活目标课程环境。
pip方式：
```powershell
conda install -n base -c conda-forge "psycopg>=3,<4" psycopg-c
python -m pip install -r .\requirements.txt
```
安装完成后验证：
Conda方式：
```powershell
python -c "import psycopg; print(psycopg.__version__)"
conda install -c conda-forge psycopg psycopg-c libpq
```
如果以后改用 Python 虚拟环境，也可以使用 `requirements.txt` 安装。无论使用哪种方式，导入时都写 `import psycopg`，不是 `import psycopg3`。
两种方式的环境创建、区别、镜像配置，以及`EnvironmentNotWritableError`、`no pq wrapper available`、PyCharm原生崩溃等问题，统一参见[附录：Psycopg安装、环境选择与常见问题排查](./附录_Psycopg安装与排错.md)。
无论采用哪种方式，导入时都写`import psycopg`，不是`import psycopg3`。
## 七、创建本地 TOML 配置
@@ -209,7 +213,7 @@ python .\04_数据库\4_1_PostgreSQL与Psycopg入门\connection_example.py
含义：当前 Python 环境没有安装 Psycopg。
处理：激活 `.venv`，再使用本课的 `requirements.txt` 安装依赖。可以运行 `python -m pip show psycopg` 检查安装位置。
处理：先激活实际使用的`.venv`或Conda课程环境，再使用本课的`requirements.txt`安装依赖。可以运行`python -c "import sys; print(sys.executable)"`确认解释器，并使用`python -m pip show psycopg`检查安装位置。完整排查流程参见安装附录。
### 11.2 未找到 `config.toml`
04_数据库/4_1_PostgreSQL与Psycopg入门/附录_Psycopg安装与排错.md
+494
View File
@@ -0,0 +1,494 @@
# 附录：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监听和账号权限属于连接问题，应与安装问题分开判断。