Refactor test to use Docker container with Unix socket proxy

Updates the test to use describeWithContainer with mysql_plain image
and UnixDomainSocketProxy to work in CI environments where Docker is
available but local Unix sockets are not.

The test now:
- Only runs when Docker is enabled (via isDockerEnabled check)
- Creates a Unix socket proxy that forwards to the MySQL container
- Tests all three connection formats:
  1. Standard format with localhost
  2. Shorthand format without hostname (issue #23954)
  3. Options object with path property

docs/api/sql.md

@@ -126,7 +126,11 @@ new SQL("mysql2://user:pass@localhost:3306/database");
 // With query parameters
 new SQL("mysql://user:pass@localhost/db?ssl=true");
 
-// Unix socket connection
+// Unix socket connection (hostname is ignored when socket is provided)
+new SQL(
+  "mysql://user:pass@localhost/database?socket=/var/run/mysqld/mysqld.sock",
+);
+// Hostname can also be omitted:
 new SQL("mysql://user:pass@/database?socket=/var/run/mysqld/mysqld.sock");
 ```
 

src/js/internal/sql/shared.ts

@@ -464,8 +464,16 @@ function parseConnectionDetailsFromOptionsOrEnvironment(
           );
         }
 
-        // unrelated error to do with url parsing, we should re-throw. This is a real user error
-        throw e;
+        // Handle special case: mysql://user:pass@/database?socket=/path
+        // This is a common pattern for Unix socket connections where hostname is omitted
+        if (typeof urlToProcess === "string" && /@\//.test(urlToProcess)) {
+          // Replace @/ with @localhost/ to make it a valid URL
+          urlToProcess = new URL(urlToProcess.replace(/@\//, "@localhost/"));
+          protocol = urlToProcess.protocol.replace(/:$/, "");
+        } else {
+          // unrelated error to do with url parsing, we should re-throw. This is a real user error
+          throw e;
+        }
       }
     } else {
       // Add protocol if missing
@@ -582,7 +590,8 @@ function parseOptions(
     for (const key in queryObject) {
       if (key.toLowerCase() === "sslmode") {
         sslMode = normalizeSSLMode(queryObject[key]);
-      } else if (key.toLowerCase() === "path") {
+      } else if (key.toLowerCase() === "path" || key.toLowerCase() === "socket") {
+        // Support both 'path' and 'socket' query parameters for Unix socket connections
         path = queryObject[key];
       } else {
         // this is valid for postgres for other databases it might not be valid

test/regression/issue/23954.test.ts

@@ -0,0 +1,80 @@
+import { SQL } from "bun";
+import { afterAll, beforeAll, expect, test } from "bun:test";
+import { describeWithContainer, isDockerEnabled } from "harness";
+import { UnixDomainSocketProxy } from "../../unix-domain-socket-proxy.ts";
+
+// Test for issue #23954: Unix socket connection for MySQL
+// https://github.com/oven-sh/bun/issues/23954
+
+if (isDockerEnabled()) {
+  describeWithContainer(
+    "MySQL Unix socket connection (issue #23954)",
+    {
+      image: "mysql_plain",
+      concurrent: true,
+    },
+    container => {
+      let socketProxy: UnixDomainSocketProxy;
+      let socketPath: string;
+
+      beforeAll(async () => {
+        await container.ready;
+        // Create Unix socket proxy for MySQL
+        socketProxy = await UnixDomainSocketProxy.create("MySQL", container.host, container.port);
+        socketPath = socketProxy.path;
+      });
+
+      afterAll(() => {
+        if (socketProxy) {
+          socketProxy.stop();
+        }
+      });
+
+      test("MySQL connection via Unix socket using 'socket' query parameter with localhost", async () => {
+        // Standard format: hostname is required but ignored when socket is provided
+        const mysql = new SQL(`mysql://root:@localhost/bun_sql_test?socket=${socketPath}`);
+
+        try {
+          // Try a simple query
+          const result = await mysql`SELECT 1 as value`;
+          expect(result).toEqual([{ value: 1 }]);
+        } finally {
+          await mysql.close();
+        }
+      });
+
+      test("MySQL connection via Unix socket using 'socket' query parameter without hostname (docs format)", async () => {
+        // Shorthand format from docs: mysql://user:pass@/database?socket=/path
+        // The missing hostname is replaced with localhost internally
+        const mysql = new SQL(`mysql://root:@/bun_sql_test?socket=${socketPath}`);
+
+        try {
+          // Try a simple query
+          const result = await mysql`SELECT 1 as value`;
+          expect(result).toEqual([{ value: 1 }]);
+        } finally {
+          await mysql.close();
+        }
+      });
+
+      test("MySQL connection via Unix socket using path in options object", async () => {
+        // Using the options object with path property
+        const mysql = new SQL({
+          adapter: "mysql",
+          username: "root",
+          password: "",
+          database: "bun_sql_test",
+          path: socketPath,
+        });
+
+        try {
+          // Try a simple query
+          const result = await mysql`SELECT 1 as value`;
+          expect(result).toEqual([{ value: 1 }]);
+        } finally {
+          await mysql.close();
+        }
+      });
+    },
+  );
+}