MySQL support

.github/workflows/tests.yaml

@@ -194,3 +194,77 @@ jobs:
             - name: Upload coverage
               uses: codecov/codecov-action@v1
               if: matrix.python-version == '3.13'
+
+    mysql:
+        runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+        services:
+            mysql:
+                image: mysql:8.4
+                env:
+                    MYSQL_ROOT_PASSWORD: rootpassword
+                    MYSQL_DATABASE: piccolo
+                    MYSQL_ROOT_HOST: '%'
+                options: >-
+                    --health-cmd="mysqladmin ping -uroot -prootpassword"
+                    --health-interval=5s
+                    --health-timeout=2s
+                    --health-retries=10
+                ports:
+                    - 3306:3306
+
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v4
+
+            - name: Set up Python ${{ matrix.python-version }}
+              uses: actions/setup-python@v5
+              with:
+                python-version: ${{ matrix.python-version }}
+
+            - name: Install dependencies
+              run: |
+                python -m pip install --upgrade pip
+                pip install -r requirements/requirements.txt
+                pip install -r requirements/test-requirements.txt
+                pip install -r requirements/extras/mysql.txt
+
+            - name: Install MySQL Client
+              run: sudo apt-get update && sudo apt-get install -y mysql-client
+
+            - name: Wait for MySQL
+              run: |
+                set -e
+                for i in {1..60}; do
+                    if mysqladmin ping -h127.0.0.1 -P3306 -uroot -prootpassword > /dev/null 2>&1; then
+                    echo "MySQL is up"
+                    break
+                    fi
+                    echo "Waiting for MySQL… ($i/60)"
+                    sleep 2
+                    if [ "$i" -eq 60 ]; then
+                    echo "MySQL did not become ready in time!" >&2
+                    mysqladmin ping -h127.0.0.1 -P3306 -uroot -prootpassword || true
+                    exit 1
+                    fi
+                done
+
+            - name: Setup MySQL (create database)
+              run: |
+                mysql -h127.0.0.1 -P3306 -uroot -prootpassword -e "CREATE DATABASE IF NOT EXISTS piccolo;"
+
+            - name: Test with pytest, MySQL
+              run: ./scripts/test-mysql.sh
+              env:
+                MY_HOST: 127.0.0.1
+                MY_PORT: 3306
+                MY_USER: root
+                MY_PASSWORD: rootpassword
+                MY_DATABASE: piccolo
+
+            - name: Upload coverage
+              uses: codecov/codecov-action@v1
+              if: matrix.python-version == '3.13'

docs/src/piccolo/engines/connection_pool.rst

@@ -3,7 +3,7 @@
 Connection Pool
 ===============
 
-.. hint:: Connection pools can be used with Postgres and CockroachDB.
+.. hint:: Connection pools can be used with Postgres, CockroachDB and MySQL.
 
 Setup
 ~~~~~

docs/src/piccolo/engines/index.rst

@@ -127,4 +127,5 @@ Engine types
     ./sqlite_engine
     ./postgres_engine
     ./cockroach_engine
+    ./mysql_engine
     ./connection_pool

docs/src/piccolo/engines/mysql_engine.rst

@@ -0,0 +1,44 @@
+MySQLEngine
+===========
+
+Configuration
+-------------
+
+.. code-block:: python
+
+    # piccolo_conf.py
+    from piccolo.engine.mysql import MySQLEngine
+
+
+    DB = MySQLEngine(
+        config={
+            "host": "localhost",
+            "port": 3306,
+            "user": "root",
+            "password": "",
+            "db": "piccolo",
+        }
+    )
+
+config
+~~~~~~
+
+The config dictionary is passed directly to the underlying database adapter, 
+aiomysql. See the `aiomysql docs <https://aiomysql.readthedocs.io/en/stable/connection.html#connection>`_
+to learn more.
+
+-------------------------------------------------------------------------------
+
+Connection Pool
+---------------
+
+See :ref:`ConnectionPool`.
+
+-------------------------------------------------------------------------------
+
+Source
+------
+
+.. currentmodule:: piccolo.engine.mysql
+
+.. autoclass:: MySQLEngine

docs/src/piccolo/getting_started/database_support.rst

@@ -17,6 +17,12 @@ together in production. The main missing feature is support for
 :ref:`automatic database migrations <AutoMigrations>` due to SQLite's limited
 support for ``ALTER TABLE`` ``DDL`` statements.
 
+`MySQL <https://www.mysql.com/>`_ is also supported. There may be some features 
+not supported, but it's OK to use. :ref:`Automatic database migrations <AutoMigrations>` 
+is supported but we must be careful because MySQL ``DDL`` statements
+`are not transactional <https://dev.mysql.com/doc/refman/8.4/en/atomic-ddl.html>`_ 
+and MySQL will commit the changes in transaction.
+
 What about other databases?
 ---------------------------
 

docs/src/piccolo/getting_started/index.rst

@@ -12,5 +12,6 @@ Getting Started
     ./setup_postgres
     ./setup_cockroach
     ./setup_sqlite
+    ./setup_mysql
     ./example_schema
     ./sync_and_async

docs/src/piccolo/getting_started/setup_mysql.rst

@@ -0,0 +1,28 @@
+.. _setting_up_mysql:
+
+###########
+Setup MySQL
+###########
+
+Installation
+************
+
+Follow the  `instructions for your OS <https://dev.mysql.com/doc/refman/8.4/en/installing.html>`_.
+
+
+Creating a database
+*******************
+
+Using ``mysql``:
+
+.. code-block:: bash
+
+    mysql -u root -p
+
+Enter your password and create the database:
+
+.. code-block:: bash
+
+    CREATE DATABASE "my_database_name";
+
+Alternatively, use a GUI tool.

docs/src/piccolo/migrations/create.rst

@@ -256,9 +256,10 @@ Creating an auto migration:
     aren't supported by auto migrations, or to modify the data held in tables, as
     opposed to changing the tables themselves.
 
-.. warning:: Auto migrations aren't supported in SQLite, because of SQLite's
-    extremely limited support for SQL Alter statements. This might change in
-    the future.
+.. warning:: Auto migrations for SQLite and MySQL are supported, with limitations.
+    SQLite has extremely limited support for SQL ALTER statements and MySQL DDL triggers 
+    an implicit commit in transaction and we cannot roll back a DDL using ROLLBACK
+    (non-transactional DDL). This might change in the future.
 
 Troubleshooting
 ~~~~~~~~~~~~~~~

docs/src/piccolo/playground/advanced.rst

@@ -94,6 +94,41 @@ When you have the database setup, you can connect to it as follows:
 
     piccolo playground run --engine=cockroach
 
+
+MySQL
+-----
+
+Install MySQL
+~~~~~~~~~~~~~
+
+See :ref:`the docs on settings up MySQL <setting_up_mysql>`.
+
+Create database
+~~~~~~~~~~~~~~~
+
+By default the playground expects a local database to exist with the following
+credentials:
+
+.. code-block:: bash
+
+    user: "root"
+    password: ""
+    host: "localhost"
+    db: "piccolo_playground"
+    port: 3306
+
+If you want to use different credentials, you can pass them into the playground
+command (use ``piccolo playground run --help`` for details).
+
+Connecting
+~~~~~~~~~~
+
+When you have the database setup, you can connect to it as follows:
+
+.. code-block:: bash
+
+    piccolo playground run --engine=mysql
+
 iPython
 -------
 

docs/src/piccolo/query_clauses/on_conflict.rst

@@ -133,6 +133,8 @@ You can also specify the name of a constraint using a string:
     ...     target='some_constraint'
     ... )
 
+.. warning:: Not supported for MySQL.
+
 ``values``
 ----------
 
@@ -194,11 +196,15 @@ update should be made:
     ...     where=Band.popularity < 1000
     ... )
 
+.. warning:: Not supported for MySQL. A workaround is possible by using an  
+    ``IF`` or ``CASE`` condition in the ``UPDATE`` clause or by first
+    performing a separate ``UPDATE``, but this is not currently supported in Piccolo.
+
 Multiple ``on_conflict`` clauses
 --------------------------------
 
-SQLite allows you to specify multiple ``ON CONFLICT`` clauses, but Postgres and
-Cockroach don't.
+SQLite allows you to specify multiple ``ON CONFLICT`` clauses, but Postgres,
+Cockroach and MySQL don't.
 
 .. code-block:: python
 
@@ -218,6 +224,7 @@ Learn more
 * `Postgres docs <https://www.postgresql.org/docs/current/sql-insert.html#SQL-ON-CONFLICT>`_
 * `Cockroach docs <https://www.cockroachlabs.com/docs/v2.0/insert.html#on-conflict-clause>`_
 * `SQLite docs <https://www.sqlite.org/lang_UPSERT.html>`_
+* `MySQL docs <https://dev.mysql.com/doc/refman/8.4/en/insert.html>`_
 
 Source
 ------

docs/src/piccolo/query_clauses/returning.rst

@@ -49,4 +49,6 @@ how many rows were affected or processed by the operation.
 .. warning:: This works for all versions of Postgres, but only
     `SQLite 3.35.0 <https://www.sqlite.org/lang_returning.html>`_ and above
     support the returning clause. See the :ref:`docs <check_sqlite_version>` on
-    how to check your SQLite version.
+    how to check your SQLite version. 
+
+    Not supported for MySQL because there is no ``RETURNING`` clause in MySQL.

piccolo/apps/migrations/auto/migration_manager.py

@@ -16,12 +16,15 @@
 )
 from piccolo.apps.migrations.auto.serialisation import deserialise_params
 from piccolo.columns import Column, column_types
-from piccolo.columns.column_types import ForeignKey, Serial
+from piccolo.columns.column_types import JSON, Blob, ForeignKey, Serial, Text
 from piccolo.engine import engine_finder
 from piccolo.engine.cockroach import CockroachTransaction
 from piccolo.query import Query
 from piccolo.query.base import DDL
-from piccolo.query.constraints import get_fk_constraint_name
+from piccolo.query.constraints import (
+    get_fk_constraint_name,
+    get_fk_constraint_name_mysql,
+)
 from piccolo.schema import SchemaDDLBase
 from piccolo.table import Table, create_table_class, sort_table_classes
 from piccolo.utils.warnings import colored_warning
@@ -543,10 +546,16 @@ async def _run_alter_columns(self, backwards: bool = False):
 
                     assert isinstance(fk_column, ForeignKey)
 
+                    if existing_table._meta.db.engine_type == "mysql":
+                        constraint_name = await get_fk_constraint_name_mysql(
+                            column=fk_column
+                        )
+                    else:
+                        constraint_name = await get_fk_constraint_name(
+                            column=fk_column
+                        )
+
                     # First drop the existing foreign key constraint
-                    constraint_name = await get_fk_constraint_name(
-                        column=fk_column
-                    )
                     if constraint_name:
                         await self._run_query(
                             _Table.alter().drop_constraint(
@@ -642,6 +651,16 @@ async def _run_alter_columns(self, backwards: bool = False):
                     column._meta._name = alter_column.column_name
                     column._meta.db_column_name = alter_column.db_column_name
 
+                    if _Table._meta.db.engine_type == "mysql" and (
+                        column_class == Text
+                        or column_class == JSON
+                        or column_class == Blob
+                    ):
+                        raise ValueError(
+                            "MySQL does not support default value in alter "
+                            "statement for TEXT, JSON and BLOB columns"
+                        )
+
                     if default is None:
                         await self._run_query(
                             _Table.alter().drop_default(column=column)

piccolo/apps/playground/commands/run.py

@@ -29,7 +29,12 @@
     Varchar,
 )
 from piccolo.columns.readable import Readable
-from piccolo.engine import CockroachEngine, PostgresEngine, SQLiteEngine
+from piccolo.engine import (
+    CockroachEngine,
+    MySQLEngine,
+    PostgresEngine,
+    SQLiteEngine,
+)
 from piccolo.engine.base import Engine
 from piccolo.table import Table
 from piccolo.utils.warnings import colored_string
@@ -424,6 +429,16 @@ def run(
                 "port": port or 26257,
             }
         )
+    elif engine.upper() == "MYSQL":
+        db = MySQLEngine(
+            {
+                "host": host,
+                "db": database,
+                "user": user or "root",
+                "password": password or "",
+                "port": port or 3306,
+            }
+        )
     else:
         db = SQLiteEngine()
     for _table in TABLES: