使用Flask SQLAlchemy连接MariaDB时遇paramstyle属性缺失错误

问题 #

尝试使用Flask SQLAlchemy连接MariaDB时，遇到如下错误：

AttributeError: module 'mariadb' has no attribute 'paramstyle'

连接配置代码如下：

def create_app():
    # APP SETUP
    app = Flask(__name__, instance_relative_config=True)
    app.config.from_mapping(
     SQLALCHEMY_DATABASE_URI='mariadb+mariadbconnector://user:pass@localhost:port/database',
    )

    # DATABASE SETUP
    db.init_app(app)
    with app.app_context():
        db.create_all()

    return app

已尝试的解决方法：

• 将URI中的mariadb+mariadbconnector替换为mysql+pymysql，报错变为AttributeError: module 'pymysql' has no attribute 'paramstyle'
• 切换为mysql+mysqldb，报错变为AttributeError: module 'MySQLdb' has no attribute 'paramstyle'
• 切回MariaDB驱动，执行sudo apt install libmariadb3 libmariadb-dev安装系统依赖，但问题依旧

完整错误栈：

Traceback (most recent call last):
  File "/home/runcloud/webapps/spotlessmind-app/venv/lib/python3.12/site-packages/gunicorn/arbiter.py", line 608, in spawn_worker
    worker.init_process()
  File "/home/runcloud/webapps/spotlessmind-app/venv/lib/python3.12/site-packages/gunicorn/workers/base.py", line 135, in init_process
    self.load_wsgi()
  File "/home/runcloud/webapps/spotlessmind-app/venv/lib/python3.12/site-packages/gunicorn/workers/base.py", line 147, in load_wsgiapp
    self.wsgi = self.app.wsgi()
                ^^^^^^^^^^^^^^^
  File "/home/runcloud/webapps/spotlessmind-app/venv/lib/python3.12/site-packages/gunicorn/app/base.py", line 66, in wsgi
    self.callable = self.load()
                    ^^^^^^^^^^^
  File "/home/runcloud/webapps/spotlessmind-app/venv/lib/python3.12/site-packages/gunicorn/app/wsgiapp.py", line 57, in load
    return self.load_wsgiapp()
           ^^^^^^^^^^^^^^^^^^^
  File "/home/runcloud/webapps/spotlessmind-app/venv/lib/python3.12/site-packages/gunicorn/app/wsgiapp.py", line 47, in load_wsgiapp
    return util.import_app(self.app_uri)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runcloud/webapps/spotlessmind-app/venv/lib/python3.12/site-packages/gunicorn/util.py", line 370, in import_app
    mod = importlib.import_module(module)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/importlib/__init__.py", line 90, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 995, in exec_module
  File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
  File "/home/runcloud/webapps/spotlessmind-app/wsgi.py", line 3, in <module>
    app = create_app()
          ^^^^^^^^^^^^
  File "/home/runcloud/webapps/spotlessmind-app/spotlessmind/__init__.py", line 28, in create_app
    db.init_app(app)
  File "/home/runcloud/webapps/spotlessmind-app/venv/lib/python3.12/site-packages/flask_sqlalchemy/extension.py", line 374, in init_app
    engines[key] = self._make_engine(key, options, app)
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runcloud/webapps/spotlessmind-app/venv/lib/python3.12/site-packages/flask_sqlalchemy/extension.py", line 665, in _make_engine
    return sa.engine_from_config(options, prefix="")
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runcloud/webapps/spotlessmind-app/venv/lib/python3.12/site-packages/sqlalchemy/engine/create.py", line 820, in engine_from_config
    return create_engine(url, **options)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<string>", line 2, in create_engine
  File "/home/runcloud/webapps/spotlessmind-app/venv/lib/python3.12/site-packages/sqlalchemy/util/deprecations.py", line 281, in warned
    return fn(*args, **kwargs)  # type: ignore[no-any-return]
           ^^^^^^^^^^^^^^^^^^^
  File "/home/runcloud/webapps/spotlessmind-app/venv/lib/python3.12/site-packages/sqlalchemy/engine/create.py", line 612, in create_engine
    dialect = dialect_cls(**dialect_args)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runcloud/webapps/spotlessmind-app/venv/lib/python3.12/site-packages/sqlalchemy/dialects/mysql/mariadbconnector.py", line 143, in __init__
    super().__init__(**kwargs)
  File "/home/runcloud/webapps/spotlessmind-app/venv/lib/python3.12/site-packages/sqlalchemy/dialects/mysql/base.py", line 2518, in __init__
    default.DefaultDialect.__init__(self, **kwargs)
  File "<string>", line 2, in __init__
  File "/home/runcloud/webapps/spotlessmind-app/venv/lib/python3.12/site-packages/sqlalchemy/util/deprecations.py", line 281, in warned
    return fn(*args, **kwargs)  # type: ignore[no-any-return]
           ^^^^^^^^^^^^^^^^^^^
  File "/home/runcloud/webapps/spotlessmind-app/venv/lib/python3.12/site-packages/sqlalchemy/engine/default.py", line 333, in __init__
    self.paramstyle = self.dbapi.paramstyle
                      ^^^^^^^^^^^^^^^^^^^^^
AttributeError: module 'mariadb' has no attribute 'paramstyle'

解决方案 #

1. 确保依赖安装在虚拟环境内 #

所有数据库驱动包必须安装在项目对应的虚拟环境中，而非系统全局Python环境：

• 激活虚拟环境：

  source /home/runcloud/webapps/spotlessmind-app/venv/bin/activate
  

• 针对MariaDB驱动，重新安装Python包：

  pip install mariadb
  

• 若使用pymysql，执行：

  pip install pymysql
  

2. 验证Python版本兼容性 #

当前使用Python 3.12，部分旧版驱动可能未适配该版本：

• 安装兼容Python 3.12的驱动版本：
  • mariadb：确保版本≥1.1.0
  • pymysql：确保版本≥1.1.0

3. 排查命名冲突 #

检查项目目录下是否存在mariadb.py、pymysql.py或MySQLdb.py这类与驱动同名的文件，它们会覆盖第三方库的导入，导致加载错误模块。若存在，立即重命名这类文件。

4. 检查驱动模块完整性 #

在虚拟环境中执行以下代码，验证驱动模块是否正常：

import mariadb
print(dir(mariadb))  # 查看模块属性，确认是否包含paramstyle
print(mariadb.__file__)  # 确认导入的是虚拟环境内的模块

若输出中无paramstyle，说明模块安装不完整，卸载后重新安装：

pip uninstall mariadb -y
pip install mariadb --no-cache-dir

5. 显式指定DBAPI #

若以上方法无效，尝试在配置中显式指定使用的dbapi：

import mariadb

def create_app():
    app = Flask(__name__, instance_relative_config=True)
    app.config.from_mapping(
        SQLALCHEMY_DATABASE_URI='mariadb+mariadbconnector://user:pass@localhost:port/database',
        SQLALCHEMY_ENGINE_OPTIONS={
            "dbapi": mariadb
        }
    )
    db.init_app(app)
    with app.app_context():
        db.create_all()
    return app

内容的提问来源于stack exchange，提问作者Nicolas Gatien