Debian 上使用 Python 连接数据库的完整操作指南

在 Debian 系统上，用 Python 连接数据库是开发中的高频操作。这事儿说简单也简单，但想做得专业、不出错，还真有几个关键步骤得捋清楚。下面这份指南，就帮你把从环境准备到问题排查的全流程，一次性讲明白。

一 环境准备

工欲善其事，必先利其器。动手之前，先把基础环境搭建好。

• 更新系统并安装基础工具： 这是标准起手式，确保你的包管理器是最新的，并安装好 Python3 和 pip。
  • 命令：sudo apt update && sudo apt install -y python3 python3-pip
• 建议使用虚拟环境隔离依赖： 强烈推荐！为每个项目创建独立的虚拟环境，能有效避免依赖冲突，这是专业开发者的好习惯。
  • 命令：python3 -m venv venv && source venv/bin/activate
• 激活虚拟环境后，就可以在里面安心安装接下来所需的数据库驱动了。

二 安装驱动与准备数据库

数据库种类繁多，对应的 Python 驱动也不同。选对、装对驱动，是成功连接的第一步。

• 常见数据库与驱动安装一览： 这张表帮你快速定位。

• 安装 PostgreSQL 开发库： 如果你选择编译安装 psycopg2（非二进制版），这个库必不可少。
  • 命令：sudo apt install -y libpq-dev
• 启动数据库服务： 如果你的数据库就安装在本地 Debian 上，别忘了启动它。
  • MySQL：sudo systemctl start mysql
  • PostgreSQL：sudo systemctl start postgresql
• 防火墙放行端口： 如果系统防火墙是开启状态，记得放行对应端口，否则连接会被无情拒绝。
  • 关键端口：3306（MySQL）、5432（PostgreSQL）。

三 连接与操作示例

驱动装好了，服务也跑起来了，接下来就是实战代码。这里有几个通用原则，无论连接哪种数据库都适用：

• 使用参数化查询： 务必使用 %s、%({name})s 这类占位符，这是防止 SQL 注入攻击的生命线。
• 管理连接与事务： 写入操作后记得 commit()；查询完毕，及时调用 fetch*() 获取结果并关闭游标和连接，释放资源。
• 管理凭据： 生产环境下，切忌将用户名密码直接写在代码里。用环境变量或配置文件来管理，才是稳妥的做法。

下面，我们分别看看三种主流数据库的具体连接方法。

• MySQL 示例（mysql-connector-python）

  import mysql.connector
  from mysql.connector import Error
  
  config = {
      'user': 'your_username',
      'password': 'your_password',
      'host': '127.0.0.1',
      'database': 'your_database',
      'raise_on_warnings': True
  }
  
  try:
      cnx = mysql.connector.connect(**config)
      cur = cnx.cursor()
      cur.execute("SELECT VERSION()")
      print("MySQL version:", cur.fetchone())
  except Error as e:
      print("MySQL error:", e)
  finally:
      if cnx.is_connected():
          cur.close()
          cnx.close()

  驱动可以通过 pip3 install mysql-connector-python 或 pip3 install PyMySQL 安装，二者选一即可。

• PostgreSQL 示例（psycopg2）

  import psycopg2
  
  try:
      conn = psycopg2.connect(
          dbname="your_database",
          user="your_username",
          password="your_password",
          host="127.0.0.1",
          port="5432"
      )
      cur = conn.cursor()
      cur.execute("SELECT version();")
      print("PostgreSQL version:", cur.fetchone())
  except Exception as e:
      print("PostgreSQL error:", e)
  finally:
      if conn:
          cur.close()
          conn.close()

  安装推荐：直接使用 pip3 install psycopg2-binary，省去编译麻烦。如果坚持从源码安装，务必先执行 sudo apt install libpq-dev。

• SQLite 示例（内置模块）

  import sqlite3
  
  conn = sqlite3.connect('example.db')
  cur = conn.cursor()
  cur.execute("SELECT sqlite_version();")
  print("SQLite version:", cur.fetchone())
  conn.close()

  看，这就是 SQLite 的便利之处——无需任何额外安装，Python 自带开箱即用，非常适合本地测试和轻量级应用场景。

四 常见问题与排查

连接过程很少一帆风顺，遇到问题别慌，按这个清单一步步排查，十有八九能找到症结。

• 服务未启动： 最容易被忽略的一步。确认已经执行了 sudo systemctl start mysql 或 sudo systemctl start postgresql。如果想一劳永逸，可以设置服务开机自启。
• 连接被拒绝或超时：
  • 首先，核对连接参数：host、port、用户名、密码、数据库名，一个都不能错。
  • 其次，检查数据库的访问控制配置。比如 PostgreSQL 的 pg_hba.conf 文件，MySQL 的用户授权和 bind-address 设置，都需要允许来自你当前主机的连接。
  • 最后，别忘了上面提过的防火墙，确认 3306 或 5432 端口已放行。
• 驱动安装失败： 特别是编译 psycopg2 时，如果报错，大概率是缺少开发库。记住这个组合拳：先 sudo apt install libpq-dev，再 pip3 install psycopg2。或者，更简单点，直接安装预编译的 psycopg2-binary。
• 权限不足： 连接成功但操作被拒？很可能用户权限不够。需要在数据库内为用户授予相应权限，例如执行类似 GRANT ALL PRIVILEGES ON DATABASE db TO user; 的命令。
• 凭据安全： 最后再强调一次，不要硬编码敏感信息。使用环境变量或独立的配置文件来管理数据库连接字符串，这是迈向生产环境安全的第一步。