Translate MySQL CONVERT() expressions to SQLite

SQLite doesn't support the CONVERT() function. Translate its two forms:
- CONVERT(expr, type) is equivalent to CAST(expr AS type).
- CONVERT(expr USING charset) is a character set conversion that is
  a no-op in SQLite, as all text is stored as UTF-8.

Trailing modifiers like COLLATE are preserved in the translation.

Fixes #344

Author: JanJakes

packages/mysql-on-sqlite/src/sqlite/class-wp-pdo-mysql-on-sqlite.php

@@ -4221,9 +4221,65 @@ private function translate_simple_expr( WP_Parser_Node $node ): string {
 			);
 		}
 
+		// Translate MySQL CONVERT() to SQLite equivalents.
+		if ( null !== $token && WP_MySQL_Lexer::CONVERT_SYMBOL === $token->id ) {
+			return $this->translate_convert_expr( $node );
+		}
+
 		return $this->translate_sequence( $node->get_children() );
 	}
 
+	/**
+	 * Translate a MySQL CONVERT() expression to SQLite.
+	 *
+	 * MySQL supports two forms of CONVERT():
+	 *   - CONVERT(expr, type)         — equivalent to CAST(expr AS type).
+	 *   - CONVERT(expr USING charset) — converts the character set.
+	 *
+	 * SQLite doesn't support CONVERT(). The type form is translated to CAST(),
+	 * and the charset form is reduced to the expression, as SQLite stores all
+	 * text as UTF-8 and charset conversions are not needed.
+	 *
+	 * @param WP_Parser_Node $node        The "simpleExpr" AST node.
+	 * @return string                     The translated value.
+	 * @throws WP_SQLite_Driver_Exception When the translation fails.
+	 */
+	private function translate_convert_expr( WP_Parser_Node $node ): string {
+		$expr      = $this->translate( $node->get_first_child_node( 'expr' ) );
+		$cast_type = $node->get_first_child_node( 'castType' );
+
+		if ( null !== $cast_type ) {
+			// CONVERT(expr, type) → CAST(expr AS type)
+			$parts = array(
+				sprintf( 'CAST ( %s AS %s )', $expr, $this->translate( $cast_type ) ),
+			);
+		} else {
+			// CONVERT(expr USING charset) → expr
+			$parts = array( $expr );
+		}
+
+		// Translate any trailing modifiers after the closing parenthesis,
+		// as the simpleExpr grammar can include COLLATE or CONCAT_PIPES.
+		$past_close_paren = false;
+		foreach ( $node->get_children() as $child ) {
+			if ( ! $past_close_paren ) {
+				if (
+					$child instanceof WP_Parser_Token
+					&& WP_MySQL_Lexer::CLOSE_PAR_SYMBOL === $child->id
+				) {
+					$past_close_paren = true;
+				}
+				continue;
+			}
+			$translated = $this->translate( $child );
+			if ( null !== $translated ) {
+				$parts[] = $translated;
+			}
+		}
+
+		return implode( ' ', $parts );
+	}
+
 	/**
 	 * Translate a MySQL LIKE expression to SQLite.
 	 *

packages/mysql-on-sqlite/tests/WP_SQLite_Driver_Tests.php

@@ -9986,6 +9986,73 @@ public function testCastExpression(): void {
 		);
 	}
 
+	public function testConvertExpression(): void {
+		// CONVERT(expr, type) should behave like CAST(expr AS type).
+		$result = $this->assertQuery(
+			"SELECT
+				CONVERT('abc', BINARY) AS expr_1,
+				CONVERT('abc', CHAR) AS expr_2,
+				CONVERT('-10', SIGNED) AS expr_3,
+				CONVERT('-10', UNSIGNED) AS expr_4,
+				CONVERT('123.456', DECIMAL) AS expr_5,
+				CONVERT('2025-10-05', DATE) AS expr_6
+			"
+		);
+
+		$this->assertEquals(
+			array(
+				(object) array(
+					'expr_1' => 'abc',
+					'expr_2' => 'abc',
+					'expr_3' => '-10',
+					'expr_4' => '-10',
+					'expr_5' => '123.456',
+					'expr_6' => '2025-10-05',
+				),
+			),
+			$result
+		);
+	}
+
+	public function testConvertUsingExpression(): void {
+		// CONVERT(expr USING charset) converts character set.
+		// In SQLite, all text is UTF-8 — the conversion is a no-op.
+		$result = $this->assertQuery(
+			"SELECT
+				CONVERT('Customer' USING utf8mb4) AS expr_1,
+				CONVERT('test' USING utf8) AS expr_2,
+				CONVERT('data' USING latin1) AS expr_3
+			"
+		);
+
+		$this->assertEquals(
+			array(
+				(object) array(
+					'expr_1' => 'Customer',
+					'expr_2' => 'test',
+					'expr_3' => 'data',
+				),
+			),
+			$result
+		);
+	}
+
+	/**
+	 * @see https://github.com/WordPress/sqlite-database-integration/issues/344
+	 */
+	public function testConvertUsingWithCollate(): void {
+		$result = $this->assertQuery(
+			"SELECT CONVERT('Customer' USING utf8mb4) COLLATE utf8mb4_bin AS val"
+		);
+
+		$this->assertEquals(
+			array(
+				(object) array( 'val' => 'Customer' ),
+			),
+			$result
+		);
+	}
+
 	public function testInsertWithoutInto(): void {
 		$this->assertQuery( 'CREATE TABLE t (id INT PRIMARY KEY, name VARCHAR(255))' );
 

packages/mysql-on-sqlite/tests/WP_SQLite_Driver_Translation_Tests.php

@@ -101,6 +101,43 @@ public function testSelect(): void {
 		);
 	}
 
+	public function testConvert(): void {
+		// CONVERT(expr, type) → CAST(expr AS type)
+		$this->assertQuery(
+			"SELECT CAST ( 'abc' AS BLOB ) AS `CONVERT('abc', BINARY)`",
+			"SELECT CONVERT('abc', BINARY)"
+		);
+
+		$this->assertQuery(
+			"SELECT CAST ( 'abc' AS TEXT ) AS `CONVERT('abc', CHAR)`",
+			"SELECT CONVERT('abc', CHAR)"
+		);
+
+		$this->assertQuery(
+			"SELECT CAST ( '-10' AS INTEGER ) AS `CONVERT('-10', SIGNED)`",
+			"SELECT CONVERT('-10', SIGNED)"
+		);
+
+		// CONVERT(expr USING charset) → expr
+		// When the result is a simple string literal, the auto-alias is the
+		// unquoted string value (matching MySQL's column name behavior).
+		$this->assertQuery(
+			"SELECT 'Customer' AS `Customer`",
+			"SELECT CONVERT('Customer' USING utf8mb4)"
+		);
+
+		$this->assertQuery(
+			"SELECT 'test' AS `test`",
+			"SELECT CONVERT('test' USING utf8)"
+		);
+
+		// CONVERT(expr USING charset) COLLATE collation → expr COLLATE collation
+		$this->assertQuery(
+			"SELECT 'Customer' COLLATE `utf8mb4_bin` AS `CONVERT('Customer' USING utf8mb4) COLLATE utf8mb4_bin`",
+			"SELECT CONVERT('Customer' USING utf8mb4) COLLATE utf8mb4_bin"
+		);
+	}
+
 	public function testInsert(): void {
 		$this->driver->query( 'CREATE TABLE t (c INT, c1 INT, c2 INT)' );
 		$this->driver->query( 'CREATE TABLE t1 (c1 INT, c2 INT)' );