Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/workflow.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ name: CI/CD Pipeline
tags: ['v*']

env:
LATEST_PYTHON_VERSION: '3.14'
LATEST_PYTHON_VERSION: '3.15'

jobs:
lint:
Expand All @@ -27,7 +27,7 @@ jobs:
fail-fast: false
matrix:
os: ['ubuntu-latest', 'macos-latest', 'windows-latest']
python-version: ['3.12', '3.14']
python-version: ['3.12', '3.15']
steps:
- uses: actions/checkout@v7
with:
Expand Down
45 changes: 45 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@
- [Installation](#installation)
- [Basic Installation (SQLite only)](#basic-installation-sqlite-only)
- [Database-Specific Installations](#database-specific-installations)
- [MySQL/MariaDB Client Library (mysqlclient)](#mysqlmariadb-client-library-mysqlclient)
- [Database Classes](#database-classes)
- [SQLite](#sqlite)
- [MSSQL (SQL Server)](#mssql-microsoft-sql-server)
Expand Down Expand Up @@ -318,6 +319,50 @@ pip install "ddcdatabases[mysql,postgres,mongodb]"
- PostgreSQL extras may have compilation requirements on some systems
- All extras support both synchronous and asynchronous operations where applicable

## MySQL/MariaDB Client Library (mysqlclient)

The sync driver (`mysql+mysqldb`, from `mysqlclient`) is a C extension that is compiled
against whatever MySQL/MariaDB client library is installed on your system.
The async driver (`aiomysql`) is pure Python and is not affected.

> **MySQL 9 client libraries cannot connect to MariaDB.** MySQL 9 removed the
> `mysql_native_password` authentication plugin, which MariaDB servers use. If
> `mysqlclient` is built against a MySQL 9 client (e.g. `mysql-devel` on Fedora 45+,
> Homebrew `mysql-client`), connecting to MariaDB fails with:
>
> `(2059, "Authentication plugin 'mysql_native_password' cannot be loaded ...")`

Build `mysqlclient` against **MariaDB Connector/C** instead. It supports both
`mysql_native_password` and `caching_sha2_password`, so it works with MariaDB **and**
MySQL 8/9 servers:

```shell
# Fedora / RHEL (conflicts with mysql-devel; `dnf swap` replaces it)
sudo dnf swap mysql-devel mariadb-connector-c-devel # or: sudo dnf install mariadb-connector-c-devel
sudo dnf install pkg-config

# Debian / Ubuntu
sudo apt-get install libmariadb-dev pkg-config

# macOS (Homebrew)
brew install mariadb-connector-c pkg-config
export PKG_CONFIG_PATH="$(brew --prefix mariadb-connector-c)/lib/pkgconfig"
```

If `mysqlclient` was already installed, rebuild it so it links the new library
(clear the cached build first, it was compiled against the old one):

```shell
uv cache clean mysqlclient
uv pip install --reinstall --no-deps mysqlclient # or: pip install --force-reinstall --no-cache-dir --no-deps mysqlclient
```

Check which library it uses (Linux): the output should show `libmariadb.so`, not `libmysqlclient.so`:

```shell
ldd "$(python -c 'import MySQLdb._mysql as m; print(m.__file__)')" | grep -E 'mariadb|mysqlclient'
```


# Database Classes

Expand Down
28 changes: 23 additions & 5 deletions ddcdatabases/core/operations.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
from sqlalchemy import CursorResult, RowMapping
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy.orm import Session
from typing import Any
from typing import Any, Literal, overload

_logger = logging.getLogger(__name__)
_logger.addHandler(logging.NullHandler())
Expand All @@ -35,7 +35,7 @@ def _execute_with_retry[T](self, operation: Callable[[], T], operation_name: str
return retry_operation(operation, self.retry_config, operation_name)
return operation()

def _fetchall_impl(self, stmt: Any, as_dict: bool = False) -> list[RowMapping] | list[dict]:
def _fetchall_impl(self, stmt: Any, as_dict: bool = False) -> list[RowMapping] | list[dict[str, Any]]:
try:
cursor = self.session.execute(stmt)
if as_dict:
Expand All @@ -52,7 +52,16 @@ def _fetchall_impl(self, stmt: Any, as_dict: bool = False) -> list[RowMapping] |
_logger.exception("fetchall failed")
raise DBFetchAllException(e) from e

def fetchall(self, stmt: Any, as_dict: bool = False) -> list[RowMapping] | list[dict]:
@overload
def fetchall(self, stmt: Any, as_dict: Literal[False] = False) -> list[RowMapping]: ...

@overload
def fetchall(self, stmt: Any, as_dict: Literal[True]) -> list[dict[str, Any]]: ...

@overload
def fetchall(self, stmt: Any, as_dict: bool) -> list[RowMapping] | list[dict[str, Any]]: ...

def fetchall(self, stmt: Any, as_dict: bool = False) -> list[RowMapping] | list[dict[str, Any]]:
"""
Execute a SELECT statement and fetch all results.

Expand Down Expand Up @@ -222,7 +231,7 @@ async def _execute_with_retry(self, operation: Callable[[], Any], operation_name
return await retry_operation_async(operation, self.retry_config, operation_name)
return await operation()

async def _fetchall_impl(self, stmt: Any, as_dict: bool = False) -> list[RowMapping] | list[dict]:
async def _fetchall_impl(self, stmt: Any, as_dict: bool = False) -> list[RowMapping] | list[dict[str, Any]]:
try:
cursor = await self.session.execute(stmt)
if as_dict:
Expand All @@ -239,7 +248,16 @@ async def _fetchall_impl(self, stmt: Any, as_dict: bool = False) -> list[RowMapp
_logger.exception("async fetchall failed")
raise DBFetchAllException(e) from e

async def fetchall(self, stmt: Any, as_dict: bool = False) -> list[RowMapping] | list[dict]:
@overload
async def fetchall(self, stmt: Any, as_dict: Literal[False] = False) -> list[RowMapping]: ...

@overload
async def fetchall(self, stmt: Any, as_dict: Literal[True]) -> list[dict[str, Any]]: ...

@overload
async def fetchall(self, stmt: Any, as_dict: bool) -> list[RowMapping] | list[dict[str, Any]]: ...

async def fetchall(self, stmt: Any, as_dict: bool = False) -> list[RowMapping] | list[dict[str, Any]]:
"""
Execute a SELECT statement asynchronously and fetch all results.

Expand Down
3 changes: 2 additions & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ packages = ["ddcdatabases"]

[project]
name = "ddcdatabases"
version = "5.0.3"
version = "5.0.4"
description = "Simplified database ORM connections with support for multiple database engines"
urls.Repository = "https://github.com/ddc/ddcDatabases"
urls.Homepage = "https://pypi.org/project/ddcDatabases"
Expand Down Expand Up @@ -45,6 +45,7 @@ classifiers = [
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
"Programming Language :: Python :: 3.14",
"Programming Language :: Python :: 3.15",
"Operating System :: OS Independent",
"Environment :: Other Environment",
"Intended Audience :: Developers",
Expand Down
Loading
Loading