做Python开发的人，迟早会碰到python连接数据库这件事。不管是写个脚本批量处理数据、给后端接口配个存储层，还是分析报表时临时查一下线上库，第一关永远是先把程序和数据源之间的这条链路打通。市面上的教程零散，有的只讲pymysql一个库，有的只给一段能跑的代码但完全不说参数为什么这么填，真遇到连不上、乱码、性能不行的时候，还是两眼一抹黑。

这篇文章我按自己实际做项目的经验，把Python连接数据库这件事从头到尾梳理一遍：驱动怎么选、参数怎么填、连接池为什么必须有、常见的坑怎么排，以及安全性上必须做的几件事。内容覆盖 SQLite、MySQL、PostgreSQL 三种最常用的库，同时会提到 ORM 的接入方式。无论你是刚学Python的菜鸟，还是写过一阵子但没系统研究过连接层的开发，都能从这里拿到可以直接用的方案。

1. 一个老生常谈但绕不开的话题：连接数据库到底在做什么

很多人第一次写pymysql.connect()的时候，以为这就是“打开一个文件”的数据库版，其实完全不是一回事。搞清楚连接的原理，后面很多问题根本不会出现。

1.1 连接的本质不是“打开一个文件”，而是一次网络/进程间握手

数据库服务通常是一个独立运行的进程，可能在本机，也可能在机房另一台服务器上。你的Python程序要访问它，本质上是在两个进程之间建立起一条数据通道：客户端发起请求，服务端验证身份和权限，然后双方协商通信参数，最后才能执行SQL、传输结果。这个过程类似你进一家公司办事：先到前台（TCP握手），然后出示工牌（身份认证），前台确认你有权限进入哪个楼层（权限校验），之后你才能去对应办公室办事（执行SQL）。

这也就解释了为什么连数据库比读文件慢得多，也解释了为什么频繁建立连接会成为性能瓶颈。数据库驱动（driver）要做的事情，就是把这套复杂的握手、认证、协议转换过程封装成几个函数，让你不用手动去拼网络报文。你调用connect()时，驱动实际上完成了一次完整的网络握手和认证流程。

1.2 为什么连接方式有那么多：驱动、DB-API、ORM

“Python连接数据库”看起来是个单一问题，但实际选型道路上有三层完全不同的东西：

• 驱动层：最底层的库，比如pymysql、psycopg2、python-mysql-connector。它们负责实现数据库的通信协议，让你能用Python函数发SQL、收结果。
• DB-API层：Python官方定义了一套数据库接口规范（PEP 249），所有主流驱动都遵循这套规范。所以你会发现无论是连MySQL还是PostgreSQL，代码长得都很像：connection = xx.connect()，cursor = connection.cursor()，然后cursor.execute()。
• ORM层：SQLAlchemy、Django ORM这类框架把数据库表映射成Python类，写代码时操作对象，而不是直接拼SQL字符串。ORM底层还是要依赖某个驱动来建立实际连接。

这三层不是互斥关系，而是层层递进。搞清楚你现在处于哪一层，遇到问题就知道去哪儿找答案——比如查询结果格式不对，大概率是驱动或SQL的问题；但如果你改了表结构，代码里的类却报错，那就要去查ORM映射了。

2. 连接库与参数：选对驱动，看懂参数背后的逻辑

选驱动是第一步，这里有坑。很多人直接搜“Python连接数据库用什么库”，结果装错库、用错API，白折腾半天。

2.1 常见驱动的适配场景

先说结论，然后解释为什么：

我重点说两个最常见的误区。

第一，MySQLdb曾经是Python连MySQL的主流库，但它年久失修，在Python 3环境下的安装依赖一堆编译工具，源码编译经常报错。PyMySQL是纯Python实现的驱动，直接用pip install pymysql装完就能跑，没有编译问题。性能上虽然比C扩展驱动慢一点，但对绝大多数Web应用和数据处理任务来说，差距根本不明显。

第二，PostgreSQL 这边我用psycopg2-binary，不推荐手动源码编译的psycopg2。binary 版自带编译好的二进制文件，pip安装时不会触发本地编译环境检查，省去一堆麻烦。如果部署的服务器是主流Linux发行版，psycopg2-binary基本都是开箱即用。

至于sqlite3，它是Python标准库自带的模块，什么都不用装。SQLite 是一个文件型数据库，整个数据库就是磁盘上的一个文件，连接过程不涉及网络，所以最适合起步练习和本地原型开发。

2.2 连接参数逐个拆解

选好驱动后，连接参数才是真正会坑人的地方。我以MySQL为例，把每个参数的用途和填坑经验拆开讲：

import pymysql conn = pymysql.connect( host="127.0.0.1", port=3306, user="root", password="your_password", database="test_db", charset="utf8mb4", connect_timeout=5, read_timeout=10, write_timeout=10, )

• host：数据库服务器的IP或域名。本机连时建议写127.0.0.1而不是localhost。某些系统下localhost会被解析为IPv6地址::1，而数据库服务只监听了IPv4，就会报“无法连接”。这个坑我亲眼见过多个同事踩过，排查到最后发现只是host写法的问题。
• port：数据库端口，MySQL默认是3306，PostgreSQL默认是5432。如果你在服务器上改了默认端口，这一项一定要同步修改。
• user和password：数据库账号密码。注意这里的账号不是操作系统账号，是数据库服务自己维护的账号。
• database：要连接的默认库名。如果不指定，连接成功后需要手动执行USE database_name。建议直接指定，避免后续每句SQL都要带库名前缀。
• charset：字符集参数，这个是最容易出的坑。很多老教程写charset="utf8"，在国内环境中十有八九会出中文乱码。MySQL的utf8字符集实际只支持最多3字节的字符，而中文里很多生僻字、emoji是4字节的，必须用utf8mb4。从MySQL 5.5.3开始支持utf8mb4，这是个可以覆盖全量Unicode字符的超集。
• connect_timeout：建立连接的超时时间，单位秒。生产环境一定要设这个参数。我见过没设超时的程序，在数据库宕机的情况下，每个请求都卡在TCP层等半分钟以上才报错，导致后端服务大面积排队。
• read_timeout和write_timeout：读写超时阈值。执行特别慢的SQL时，这些参数决定了客户端能忍多久。如果业务上有些大查询确实要跑很久，这两个参数要放宽，否则查询会被临时断掉。

2.3 连接池：为什么不能每次现连

新手最容易忽略的一个设计问题是连接复用。我有一次写数据分析脚本，循环里每处理一批数据就connect()一次，处理完close()。跑了半小时之后数据库直接拒绝新连接了。原因很简单：每个连接在服务端都对应一份内存和线程资源，频繁建立和销毁连接，光握手开销就占了大量时间，而且并发一高，数据库的max_connections很容易被打满。

正确做法是使用连接池。DBUtils库的PooledDB是一个常见方案，SQLAlchemy 自己也有内置连接池。连接池的思路是：预先创建一批连接放在池子里，程序需要时从池子里取一条，用完归还而不是关闭。这样连接的创建次数被限制在池子容量的范围内，性能和稳定性都能大幅提升。

用DBUtils做连接池的示例：

from dbutils.pooled_db import PooledDB import pymysql pool = PooledDB( creator=pymysql, maxconnections=20, mincached=5, maxcached=10, maxusage=3, blocking=True, host="127.0.0.1", port=3306, user="root", password="your_password", database="test_db", charset="utf8mb4", ) conn = pool.connection() cursor = conn.cursor() cursor.execute("SELECT 1") print(cursor.fetchone()) cursor.close() conn.close() # 这里是返还连接池，不是真的关闭

参数说明：maxconnections控制连接池最大连接数，需要根据业务并发量来定，我一般初始配置为服务器CPU核数乘以2到3再结合数据库的max_connections做平衡；mincached指启动时就预先建立的空闲连接数；maxcached是池中最多允许保留的空闲连接数；maxusage是单个连接最多被复用多少次后会被强制重建，这样可以避免旧连接被数据库服务端因为超时或状态异常而静默切断。

注意：连接池确实是好东西，但业界普遍不推荐自己手写。连接池要处理连接状态检查、空闲回收、并发分配，看起来逻辑不复杂，实际写起来很容易出并发问题。直接用成熟方案就好。

3. 三种数据库的连接实操与核心代码

理论讲得差不多了，下面直接上实操。我按 SQLite、MySQL、PostgreSQL 三种库分别演示，从安装依赖到跑通增删改查，每一步都给出可复制的代码。

3.1 SQLite：零配置入门

SQLite最适合新手体验“连接数据库”的完整流程。因为它不需要安装服务端，没有网络连接、没有权限校验，一个文件就是整个数据库。Python标准库自带sqlite3，直接导入就能用。

import sqlite3 # 连接数据库。如果文件不存在，SQLite会自动创建 conn = sqlite3.connect("demo.db") # 创建游标对象。游标是用来执行SQL和获取结果的"执行器" cursor = conn.cursor() # 建表 cursor.execute(""" CREATE TABLE IF NOT EXISTS users ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, email TEXT UNIQUE ) """) # 插入数据 cursor.execute( "INSERT INTO users (name, email) VALUES (?, ?)", ("张三", "zhangsan@example.com"), ) conn.commit() # 查询验证 cursor.execute("SELECT id, name, email FROM users") rows = cursor.fetchall() for row in rows: print(row) # 输出: (1, '张三', 'zhangsan@example.com') cursor.close() conn.close()

这段代码里有两个重点。

第一，占位符?是关键。SQLite的Python驱动用问号做参数占位，数据通过第二个参数传进去。千万不要用Python的字符串格式化去拼SQL，这是防SQL注入的基本原则，后面我专门讲。

第二，conn.commit()不能省。SQLite 默认启用事务，执行INSERT、UPDATE、DELETE之后必须手动调用commit()，改动才会真正写入文件。如果忘记提交，数据看起来执行成功了，一关程序就丢失，而且不会报错。这个坑特别隐蔽，我见过不止一次误删数据后才发现没提交的案例。你可以用with conn上下文管理器来避免这个问题：

with sqlite3.connect("demo.db") as conn: cursor = conn.cursor() cursor.execute("INSERT INTO users (name, email) VALUES (?, ?)", ("李四", "lisi@example.com")) # 事务在with块结束时自动提交

3.2 MySQL：从安装依赖到跑通CRUD

MySQL是生产环境用得最多的开源关系型数据库。先安装驱动：

pip install pymysql

然后看完整示例：

import pymysql # 建立连接 conn = pymysql.connect( host="127.0.0.1", # 数据库地址 port=3306, # 数据库端口 user="root", # 数据库账号 password="your_password", # 数据库密码 database="test_db", # 默认连接的库 charset="utf8mb4", # 字符集，重要 connect_timeout=5, # 连接超时 ) try: with conn.cursor() as cursor: # 建表 cursor.execute(""" CREATE TABLE IF NOT EXISTS products ( id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(100) NOT NULL, price DECIMAL(10, 2), created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ) """) # 插入多条数据，使用参数化查询 cursor.executemany( "INSERT INTO products (name, price) VALUES (%s, %s)", [("键盘", 299.00), ("显示器", 1299.00), ("鼠标", 89.00)], ) conn.commit() with conn.cursor() as cursor: cursor.execute("SELECT id, name, price FROM products") for row in cursor.fetchall(): print(row) finally: conn.close()

这段代码里，PyMySQL用%s作为占位符，和SQLite的?不一样，别搞混了。另外注意cursor()也可以当上下文管理器用：with conn.cursor() as cursor:会在代码块退出时自动关闭游标，但要注意它并不会自动提交事务，conn.commit()还是要显式调用。

事务处理我建议掌握一个标准套路。事务是一组要么全部成功、要么全部失败的SQL操作，最经典的例子就是转账：扣款和入账必须同时成功，否则钱就丢了。在Python里这样写：

try: conn.begin() # 显式开启事务 cursor = conn.cursor() cursor.execute("UPDATE accounts SET balance = balance - 1000 WHERE id = 1") cursor.execute("UPDATE accounts SET balance = balance + 1000 WHERE id = 2") conn.commit() # 全部成功，提交 except Exception: conn.rollback() # 任何一个出错，回滚 raise finally: cursor.close() conn.close()

注意：pymysql默认autocommit是关闭的。也就是说，执行完增删改语句后，不执行commit()数据库就不会真正落盘。提交过早或过晚都会影响业务逻辑，这条一定要在头脑里刻死。

3.3 PostgreSQL：类型差异与连接细节

PostgreSQL在复杂查询、数据完整性保障上比MySQL更强，近年使用率明显上升。驱动用psycopg2-binary：

pip install psycopg2-binary

连接和CRUD的基本流程和MySQL几乎一样，因为都遵循DB-API规范：

import psycopg2 conn = psycopg2.connect( host="127.0.0.1", port=5432, user="postgres", password="your_password", database="test_db", connect_timeout=5, ) try: with conn.cursor() as cursor: cursor.execute(""" CREATE TABLE IF NOT EXISTS users ( id SERIAL PRIMARY KEY, name VARCHAR(100) NOT NULL, email VARCHAR(255) UNIQUE NOT NULL ) """) cursor.execute( "INSERT INTO users (name, email) VALUES (%s, %s)", ("王五", "wangwu@example.com"), ) conn.commit() with conn.cursor() as cursor: cursor.execute("SELECT id, name, email FROM users") for row in cursor.fetchall(): print(row) finally: conn.close()

PostgreSQL的占位符同样是%s，但有两个和MySQL差异很大的地方，新手最容易踩雷。

第一个是自增主键的写法。MySQL里是AUTO_INCREMENT，PostgreSQL里是SERIAL类型，建表语句完全不同。

第二个是事务机制。PostgreSQL默认隔离级别是“读已提交”，并且每个语句都在一个隐式事务里，如果你需要多语句原子性，同样需要显式控制提交。另外PostgreSQL对提交的处理更严格，某些错误发生后，事务会进入“已失败”状态，此时如果不先rollback()，后续所有SQL都会被拒绝执行。我第一次遇到这个报错根本想不通，后来才知道是这个原因。

除开这两点，如果你用ORM比如SQLAlchemy同时连接MySQL和PostgreSQL，切换数据库时业务代码基本不用改，只改连接字符串就行，这也是大项目里普遍用ORM的原因。

3.4 用SQLAlchemy统一管理连接与核心参数

实际项目里，我不会直接在业务代码里裸用驱动。裸用驱动意味着每个函数都得自己管理连接、游标、事务，代码重复度极高，而且切换数据库基本等于重写。SQLAlchemy作为Python最常用的ORM库，把连接管理统一封装起来，是我目前最推荐的方案。

安装：

pip install sqlalchemy pymysql # 连MySQL pip install sqlalchemy psycopg2-binary # 连PostgreSQL

用create_engine建立连接：

from sqlalchemy import create_engine, text # 连接MySQL engine = create_engine( "mysql+pymysql://root:your_password@127.0.0.1:3306/test_db?charset=utf8mb4", pool_size=10, max_overflow=5, pool_recycle=3600, echo=False, ) # 连接PostgreSQL 只需要换连接串： # engine = create_engine("postgresql+psycopg2://postgres:your_password@127.0.0.1:5432/test_db") with engine.connect() as conn: result = conn.execute(text("SELECT 1")) print(result.fetchone())

create_engine的连接串格式是：数据库驱动名+驱动名://用户名:密码@主机:端口/数据库名。这里有几个参数值得展开说说。

• pool_size：连接池常驻连接数，默认是5。如果并发请求多，要调大。
• max_overflow：连接池满了之后，最多还能额外创建多少个连接，超过这个数就会排队等待。我一般设置为pool_size的一半。
• pool_recycle：连接重新创建的间隔时间，单位秒。MySQL 服务器端默认wait_timeout是8小时，如果连接池里的连接空闲时间超过这个值，服务端会静默切断，你再拿着旧连接去查询，就会收到 "MySQL server has gone away" 报错。所以pool_recycle一定要小于服务端的超时时间，我习惯设为3600秒。
• echo：设为True时会在控制台打印所有SQL语句，开发调试时很有用，生产环境必须关掉，否则日志量太大。

用SQLAlchemy跑CRUD，可以直接写SQL，也可以用ORM映射。从连接层面来说，ORM只需要你配置好engine，后面的会话管理自动处理连接获取和归还，比手写驱动省心得多。对于多数据库并存的场景，SQLAlchemy是真正能帮你少走弯路的选择。

4. 连接之后的常见问题与排查技巧实录

连接通了不代表万事大吉。我把这几年实际调试中遇到最多的几个问题整理成速查表，再挑几个典型场景细细讲，方便你直接对照排查。

4.1 连接失败的几种典型原因

排查连接问题的核心思路是分级定位：先确认网络通不通，再确认端口通不通，最后确认账号权限够不够。不要一开始就怀疑代码。我一般按这个顺序来：

# 第一步：看IP通不通 ping 127.0.0.1 # 第二步：看端口通不通 telnet 127.0.0.1 3306 # 第三步：看数据库服务是否在运行 systemctl status mysql

如果网络和端口都通，但程序还是报错，下一步就是在数据库服务器本地上用命令行客户端手动连接一次。如果命令行能连上，说明问题几乎都在Python侧的连接参数，逐个核对host、port、user、password、database五个参数即可。

4.2 中文乱码与字符集，根源早已注定

乱码问题在连接层几乎都出在字符集设置不统一上。我把字符集需要保持一致的完整链路画出来给你看：

MySQL服务端字符集 → 数据库/表字符集 → 连接时charset参数 → Python字符串编码

这条链路任何一个环节不一致，都可能产生乱码。链路复杂，但排查方法很简单。

先确认MySQL服务端默认字符集：

SHOW VARIABLES LIKE 'character_set_server'; SHOW VARIABLES LIKE 'character_set_database';

执行结果里的utf8和utf8mb4要分清楚。之前说过，MySQL的utf8并不真正支持全部Unicode字符，它是utf8mb3的别名，最多存3字节，而utf8mb4才能存下emoji和生僻字。

我的建议是：凡是新库、新表，一律用utf8mb4。创建数据库时直接指定：

CREATE DATABASE test_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

然后连接参数里同样写charset="utf8mb4"。这两处保持一致后，90%的乱码问题都能解决。

4.3 连接泄漏与超时：程序里最阴的坑

连接泄漏是生产环境最隐蔽的性能杀手。一句话描述：你创建了连接，用完没有close()，这个连接就占着数据库的服务端资源不释放。短时间看不出问题，等并发一高，数据库的max_connections被打满，其他请求全部排队或者直接报错。

排查连接泄漏的标准手段是，在数据库里执行：

SHOW FULL PROCESSLIST;

如果看到大量Sleep状态的连接，而且数量还在不断增长，说明连接确实没有被正常归还。我见过最夸张的情况是连接数飙到几百个，数据库负载直接挂掉，重启才发现代码里好几个分支都漏了close()。

避免连接泄漏的三个原则：

• 用try/finally或with语句管理连接，确保无论代码是否抛异常，连接都会归还或关闭。
• 使用连接池，用完通过conn.close()归还连接而不是丢弃。
• 数据库账号的max_user_connections设置一个合理上限，即使代码出了bug，也能阻止连接彻底打爆数据库。

超时问题也有经典场景。一个SQL特别慢，比如全表扫描了一个千万级的大表，如果客户端read_timeout设置得比SQL执行时间还短，程序就会误以为数据库出问题了。这种时候要把read_timeout调大，但更根本的做法是优化SQL、加索引，而不是一味增加超时。

5. 关于安全性，我踩过的坑和你必须做的事

最后说安全。连接数据库的安全问题主要分两块：凭据安全和注入防护。这两块我都踩过坑，分享出来帮你避开。

5.1 凭据不要写死在代码里，用配置文件和环境变量

我在早期写项目时习惯把数据库连接字符串直接写在代码文件里，比如password="root123"。后来代码提交到版本库，所有人都能看到生产环境的数据库密码。这个失误影响很大，因为密码一旦泄露，就只能改密码，而改一次密码意味着所有依赖这个库的服务都要同步更新，联动成本很高。

现在我的做法是：

import os import pymysql conn = pymysql.connect( host=os.getenv("DB_HOST", "127.0.0.1"), port=int(os.getenv("DB_PORT", "3306")), user=os.getenv("DB_USER", "root"), password=os.getenv("DB_PASSWORD", ""), database=os.getenv("DB_NAME", "test_db"), charset="utf8mb4", )

把敏感信息放到环境变量里，代码里只留一个变量名。部署时由运维平台或启动脚本注入真实值。这样即使代码泄露，对方也看不到真实密码。

如果是本地开发，可以用.env文件配合python-dotenv库来管理，但注意.env文件一定要加入.gitignore，不要提交到版本库。

注意：数据库账号的权限也要按最小权限原则分配。业务代码用的账号，只给SELECT、INSERT、UPDATE、DELETE这几个必要的权限就够了，不要让业务账号拥有DROP或ALTER权限。这样即使应用被攻破，攻击者的破坏能力也被限制在可控范围内。

5.2 SQL注入风险：占位符是真的护身符

SQL注入是最经典的数据库安全漏洞。简单说，如果你的SQL是直接拼接用户输入拼出来的，用户可以在输入框里写入恶意代码，让程序执行攻击者定义的SQL逻辑。

举个例子，你可能写过这样的代码：

user_input = input("请输入用户名：") sql = "SELECT * FROM users WHERE name = '" + user_input + "'" cursor.execute(sql)

如果用户输入的是' OR '1'='1，整个SQL就变成了：

SELECT * FROM users WHERE name = '' OR '1'='1'

这个条件恒为真，攻击者能查出所有用户数据。如果后面再接一句'; DROP TABLE users; --，后果更严重。

正确的做法是用参数化查询，也就是前面代码里一直在用的占位符方式：

sql = "SELECT * FROM users WHERE name = %s" cursor.execute(sql, (user_input,))

参数化查询的原理是把SQL结构和数据分开传输，数据库先解析SQL结构，再把你传的数据当成纯值来处理，这样用户输入里就算有SQL语法，也只会被当成字符串值，不会被当成SQL代码执行。

无论是sqlite3的?、pymysql和psycopg2的%s，还是把占位符参数传给SQLAlchemy的text()，本质都是同一个原理：数据永远走参数通道，不掺进SQL语句字符串里。

我在代码审查时看同事的代码，只要发现字符串拼接SQL，一律要求改为参数化。这不是矫情，这是必须死守的底线。

收尾的个人体会

连接数据库这关，说白了就是围绕一个核心问题展开：怎么在程序和数据库之间，建立一个既快又稳又安全的通道。快，靠连接池和参数调优；稳，靠超时和状态管理；安全，靠凭据保护和参数化查询。这三条线没有靠哪个特别高深的技巧，全是日常基本功，但恰恰是这些基本功，决定了一个程序在真实环境里是优雅运行，还是间歇性抽风。

我个人的经验是：先老老实实把原生驱动的连接参数吃透，把事务和占位符搞明白，再上ORM。很多人一上来就用SQLAlchemy，结果连接池参数、字符集、事务逻辑都用默认值，出了问题根本不知道去哪查。先会走再学跑，这句话放在数据库连接这个场景里，特别适用。

最后再分享一个小技巧：写任何数据库相关的代码，先写一个select 1的健康检查当作“探路”。不管代码后面有多复杂的操作，先把这条最轻量的SQL跑通，能有效确认“连接没问题”这个前提，之后再排查其他问题，思路会清晰很多。