Support MySQL BINARY operator (#369)

## Summary

MySQL supports `BINARY expr` as a shorthand for `CAST(expr AS BINARY)` —
a type cast that forces byte-by-byte string comparison. The translator
previously stripped the `BINARY` keyword entirely (`translate_token()`
returned `null`), which silently produced wrong results in two cases:

1. **Columns with explicit `COLLATE NOCASE`** (notably
`information_schema` tables, where `TABLE_NAME` is `NOCASE`): `WHERE
TABLE_NAME = BINARY 'Foo'` became case-insensitive instead of
case-sensitive.
2. **`CAST(x AS BINARY) = y`**: translated to `CAST(x AS BLOB) = y`,
which always returned `FALSE` due to SQLite's storage-class ordering
(`BLOB > TEXT`), even when the bytes were equal.

## Translation

`BINARY expr` is now emitted as `expr COLLATE BINARY`:

```sql
-- MySQL
SELECT * FROM t WHERE a = BINARY b
SELECT a FROM t ORDER BY BINARY a
SELECT BINARY 'abc'

-- Translated SQLite
SELECT * FROM `t` WHERE `a` = `b` COLLATE BINARY
SELECT `a` FROM `t` ORDER BY `a` COLLATE BINARY
SELECT 'abc' COLLATE BINARY AS `BINARY 'abc'`
```

`CAST(x AS BINARY)` and `CONVERT(x, BINARY)` now emit `CAST(x AS TEXT)
COLLATE BINARY` via a shared helper — the value keeps `TEXT` storage
class (so equality against `TEXT` works) while the explicit BINARY
collation preserves byte-by-byte comparison semantics:

```sql
-- MySQL
SELECT CAST('abc' AS BINARY)
SELECT CONVERT('abc', BINARY)

-- Translated SQLite
SELECT CAST('abc' AS TEXT) COLLATE BINARY AS `CAST('abc' AS BINARY)`
SELECT CAST('abc' AS TEXT) COLLATE BINARY AS `CONVERT('abc', BINARY)`
```

SQLite's `COLLATE BINARY` overrides an operand's declared collation, so
the `NOCASE`-column case in `information_schema` now works correctly.

## Additional fix

The last commit fixes a pre-existing bug in `translate_select_item()`
surfaced during this work: its alias-inference heuristic (`$item ===
translate($textStringLiteral)`) misfired for `CONVERT(expr USING
charset)`, producing alias `` `Customer` `` instead of the original
expression text for `SELECT CONVERT('Customer' USING utf8mb4)`. Replaced
with a structural walk that stops at a `textStringLiteral` only when
each intermediate level has exactly one child node.

Fixes #31

Author: JanJakes

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

@@ -3960,9 +3960,9 @@ private function translate_token( WP_MySQL_Token $token ): ?string {
 				return 'AUTOINCREMENT';
 			case WP_MySQL_Lexer::BINARY_SYMBOL:
 				/*
-				 * There is no "BINARY expr" equivalent in SQLite. We look for the
-				 * keyword from a higher level to respect it in particular cases
-				 * (REGEXP, LIKE, etc.) and then remove it from the output here.
+				 * "BINARY expr" is translated in "translate_simple_expr_body()".
+				 * Returning null here is a safety net for any unhandled context
+				 * where a bare BINARY token would otherwise leak into the output.
 				 */
 				return null;
 			case WP_MySQL_Lexer::SQL_CALC_FOUND_ROWS_SYMBOL:
@@ -4310,6 +4310,24 @@ private function translate_simple_expr_body( WP_Parser_Node $node ): string {
 			);
 		}
 
+		/*
+		 * Translate "BINARY expr" to "expr COLLATE BINARY".
+		 *
+		 * The MySQL BINARY operator enforces byte-by-byte string comparison.
+		 * In SQLite, COLLATE BINARY is equivalent in comparison contexts.
+		 */
+		if ( null !== $token && WP_MySQL_Lexer::BINARY_SYMBOL === $token->id ) {
+			$expr = $node->get_first_child_node( 'simpleExpr' );
+			return sprintf( '%s COLLATE BINARY', $this->translate( $expr ) );
+		}
+
+		// Translate "CAST(expr AS type)" to its SQLite equivalent.
+		if ( null !== $token && WP_MySQL_Lexer::CAST_SYMBOL === $token->id ) {
+			$expr      = $node->get_first_child_node( 'expr' );
+			$cast_type = $node->get_first_child_node( 'castType' );
+			return $this->translate_cast_expr( $expr, $cast_type );
+		}
+
 		/**
 		 * Translate MySQL CONVERT() expression.
 		 *
@@ -4318,23 +4336,44 @@ private function translate_simple_expr_body( WP_Parser_Node $node ): string {
 		 *   2. CONVERT(expr USING charset): Converts the character set.
 		 */
 		if ( null !== $token && WP_MySQL_Lexer::CONVERT_SYMBOL === $token->id ) {
-			$expr      = $this->translate( $node->get_first_child_node( 'expr' ) );
+			$expr      = $node->get_first_child_node( 'expr' );
 			$cast_type = $node->get_first_child_node( 'castType' );
 
 			if ( null !== $cast_type ) {
 				// CONVERT(expr, type): Translate to cast expression.
 				// TODO: Emulate UNSIGNED cast. SQLite has no unsigned integer type.
-				return sprintf( 'CAST(%s AS %s)', $expr, $this->translate( $cast_type ) );
+				return $this->translate_cast_expr( $expr, $cast_type );
 			} else {
 				// CONVERT(expr USING charset): Keep "expr" as is (no SQLite support).
 				// TODO: Consider rejecting UTF-8-incompatible charasets.
-				return $expr;
+				return $this->translate( $expr );
 			}
 		}
 
 		return $this->translate_sequence( $node->get_children() );
 	}
 
+	/**
+	 * Translate a MySQL CAST expression to SQLite.
+	 *
+	 * Shared by the CAST(expr AS type) and CONVERT(expr, type) forms.
+	 *
+	 * @param  WP_Parser_Node $expr      The "expr" AST node.
+	 * @param  WP_Parser_Node $cast_type The "castType" AST node.
+	 * @return string                    The translated SQLite expression.
+	 */
+	private function translate_cast_expr( WP_Parser_Node $expr, WP_Parser_Node $cast_type ): string {
+		/*
+		 * Translate "CAST(expr AS BINARY)" to "CAST(expr AS TEXT) COLLATE BINARY".
+		 * Emitting "CAST(expr AS BLOB)" would break equality against TEXT values
+		 * due to SQLite's storage-class ordering (BLOB > TEXT).
+		 */
+		if ( $cast_type->has_child_token( WP_MySQL_Lexer::BINARY_SYMBOL ) ) {
+			return sprintf( 'CAST(%s AS TEXT) COLLATE BINARY', $this->translate( $expr ) );
+		}
+		return sprintf( 'CAST(%s AS %s)', $this->translate( $expr ), $this->translate( $cast_type ) );
+	}
+
 	/**
 	 * Translate a MySQL LIKE expression to SQLite.
 	 *
@@ -4693,11 +4732,20 @@ public function translate_select_item( WP_Parser_Node $node ): string {
 		 *
 		 * For example, for "SELECT 'abc'", the resulting column name is "abc"
 		 * in MySQL, but would be "'abc'" in SQLite if an alias was not used.
+		 *
+		 * Descend the AST until we reach a textStringLiteral. If at any level
+		 * we don't have a single child node, bail out; it's not a bare literal.
 		 */
-		$text_string_literal    = $node->get_first_descendant_node( 'textStringLiteral' );
-		$is_text_string_literal = $text_string_literal && $item === $this->translate( $text_string_literal );
-		if ( $is_text_string_literal ) {
-			$alias = $text_string_literal->get_first_child_token()->get_value();
+		$current = $node;
+		while ( 'textStringLiteral' !== $current->rule_name ) {
+			$children = $current->get_children();
+			if ( 1 !== count( $children ) || ! $children[0] instanceof WP_Parser_Node ) {
+				break;
+			}
+			$current = $children[0];
+		}
+		if ( 'textStringLiteral' === $current->rule_name ) {
+			$alias = $current->get_first_child_token()->get_value();
 
 			// When the literal value contains a NULL byte, MySQL truncates the
 			// resulting identifier at the position of the first one of them.

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

@@ -281,15 +281,60 @@ public function testDeleteWithAliasAndLimit() {
 	}
 
 	public function testCastAsBinary() {
-		$this->assertQuery(
-			// Use a confusing alias to make sure it replaces only the correct token
-			"SELECT CAST('ABC' AS BINARY) as `binary`;"
-		);
+		// Use a confusing alias to make sure it replaces only the correct token
+		$this->assertQuery( "SELECT CAST('ABC' AS BINARY) as `binary`" );
 		$results = $this->engine->get_query_results();
 		$this->assertCount( 1, $results );
 		$this->assertEquals( 'ABC', $results[0]->binary );
 	}
 
+	public function testBinaryOperator() {
+		// Use a NOCASE column so plain "=" is case-insensitive. This makes the
+		// BINARY operator's effect (forcing byte-by-byte comparison) visible.
+		$this->assertQuery( 'CREATE TABLE t (name TEXT COLLATE NOCASE NOT NULL)' );
+		$this->assertQuery( "INSERT INTO t (name) VALUES ('abc'), ('ABC')" );
+
+		// Sanity: with NOCASE, plain "=" matches both rows.
+		$result = $this->assertQuery( "SELECT name FROM t WHERE name = 'abc' ORDER BY name" );
+		$this->assertCount( 2, $result );
+
+		// "= BINARY 'x'" forces byte-by-byte equality.
+		$result = $this->assertQuery( "SELECT name FROM t WHERE name = BINARY 'abc'" );
+		$this->assertCount( 1, $result );
+		$this->assertEquals( 'abc', $result[0]->name );
+
+		// "BINARY x = 'X'" is symmetric.
+		$result = $this->assertQuery( "SELECT name FROM t WHERE BINARY name = 'ABC'" );
+		$this->assertCount( 1, $result );
+		$this->assertEquals( 'ABC', $result[0]->name );
+
+		// "ORDER BY BINARY" sorts by byte value ('ABC' before 'abc').
+		$result = $this->assertQuery( 'SELECT name FROM t ORDER BY BINARY name' );
+		$this->assertEquals( 'ABC', $result[0]->name );
+		$this->assertEquals( 'abc', $result[1]->name );
+
+		// CAST(expr AS BINARY) = expr
+		$result = $this->assertQuery( "SELECT CAST('abc' AS BINARY) = 'abc' AS r" );
+		$this->assertEquals( 1, $result[0]->r );
+
+		// CONVERT(expr, BINARY) = expr
+		$result = $this->assertQuery( "SELECT CONVERT('abc', BINARY) = 'abc' AS r" );
+		$this->assertEquals( 1, $result[0]->r );
+
+		// The "information_schema.TABLES.TABLE_NAME" column uses COLLATE NOCASE.
+		// Let's verify that the BINARY override works for this scenario as well.
+		$this->assertQuery( 'CREATE TABLE CaseSensitive (id INT)' );
+
+		$result = $this->assertQuery( "SELECT TABLE_NAME FROM information_schema.TABLES WHERE TABLE_NAME = 'casesensitive'" );
+		$this->assertCount( 1, $result );
+
+		$result = $this->assertQuery( "SELECT TABLE_NAME FROM information_schema.TABLES WHERE TABLE_NAME = BINARY 'casesensitive'" );
+		$this->assertCount( 0, $result );
+
+		$result = $this->assertQuery( "SELECT TABLE_NAME FROM information_schema.TABLES WHERE TABLE_NAME = BINARY 'CaseSensitive'" );
+		$this->assertCount( 1, $result );
+	}
+
 	public function testSelectFromDual() {
 		$result = $this->assertQuery(
 			'SELECT 1 as output FROM DUAL'

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

@@ -104,7 +104,7 @@ 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 CAST('abc' AS TEXT) COLLATE BINARY AS `CONVERT('abc', BINARY)`",
 			"SELECT CONVERT('abc', BINARY)"
 		);
 
@@ -120,12 +120,12 @@ public function testConvert(): void {
 
 		// CONVERT(expr USING charset) → expr
 		$this->assertQuery(
-			"SELECT 'Customer' AS `Customer`",
+			"SELECT 'Customer' AS `CONVERT('Customer' USING utf8mb4)`",
 			"SELECT CONVERT('Customer' USING utf8mb4)"
 		);
 
 		$this->assertQuery(
-			"SELECT 'test' AS `test`",
+			"SELECT 'test' AS `CONVERT('test' USING utf8)`",
 			"SELECT CONVERT('test' USING utf8)"
 		);
 
@@ -136,6 +136,56 @@ public function testConvert(): void {
 		);
 	}
 
+	public function testBinary(): void {
+		// "BINARY expr" on the left side of comparison
+		$this->assertQuery(
+			'SELECT `a` COLLATE BINARY = `b` AS `BINARY a = b` FROM `t`',
+			'SELECT BINARY a = b FROM t'
+		);
+
+		// "BINARY expr" on the right side of comparison
+		$this->assertQuery(
+			'SELECT `a` = `b` COLLATE BINARY AS `a = BINARY b` FROM `t`',
+			'SELECT a = BINARY b FROM t'
+		);
+
+		// "BINARY literal"
+		$this->assertQuery(
+			"SELECT 'abc' COLLATE BINARY AS `BINARY 'abc'`",
+			"SELECT BINARY 'abc'"
+		);
+
+		// "BINARY expr" in ORDER BY
+		$this->assertQuery(
+			'SELECT `a` FROM `t` ORDER BY `a` COLLATE BINARY',
+			'SELECT a FROM t ORDER BY BINARY a'
+		);
+
+		// "BINARY expr" in GROUP BY
+		$this->assertQuery(
+			'SELECT `a` FROM `t` GROUP BY `a` COLLATE BINARY',
+			'SELECT a FROM t GROUP BY BINARY a'
+		);
+
+		// "BINARY expr" wrapping a parenthesized expression
+		$this->assertQuery(
+			"SELECT ( `a` || `b` ) COLLATE BINARY = 'x' AS `BINARY (a || b) = 'x'` FROM `t`",
+			"SELECT BINARY (a || b) = 'x' FROM t"
+		);
+
+		// "CAST(expr AS BINARY)" → "CAST(expr AS TEXT) COLLATE BINARY"
+		$this->assertQuery(
+			"SELECT CAST('abc' AS TEXT) COLLATE BINARY AS `CAST('abc' AS BINARY)`",
+			"SELECT CAST('abc' AS BINARY)"
+		);
+
+		// "CAST(expr AS BINARY) = expr" → "CAST(expr AS TEXT) COLLATE BINARY = expr"
+		$this->assertQuery(
+			"SELECT CAST('abc' AS TEXT) COLLATE BINARY = 'abc' AS `CAST('abc' AS BINARY) = 'abc'`",
+			"SELECT CAST('abc' AS BINARY) = 'abc'"
+		);
+	}
+
 	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)' );