Add support for unix socket connection (#115)

* Add connection options specs

* Add specs for unix socket transport

* Add UnixSocket support to connection

* Update specs to be able to run with socket

* Use native mysql in CI

* Drop mysql 5.6 in CI

* Use URI for transport

* Update README

Author: bcardiff

.github/workflows/ci.yml

@@ -14,31 +14,37 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         crystal: [1.3.0, latest, nightly]
-        mysql_docker_image: ["mysql:5.6", "mysql:5.7"]
+        mysql_version: ["5.7"]
+        database_host: ["default", "/tmp/mysql.sock"]
     runs-on: ${{ matrix.os }}
     steps:
       - name: Install Crystal
         uses: crystal-lang/install-crystal@v1
         with:
           crystal: ${{ matrix.crystal }}
 
-      - name: Shutdown Ubuntu MySQL (SUDO)
-        run: sudo service mysql stop # Shutdown the Default MySQL, "sudo" is necessary, please not remove it
+      - id: setup-mysql
+        uses: shogo82148/actions-setup-mysql@v1
+        with:
+          mysql-version: ${{ matrix.mysql_version }}
 
-      - name: Setup MySQL
+      - name: Wait for MySQL
         run: |
-          docker run -e MYSQL_ALLOW_EMPTY_PASSWORD=yes -p 3306:3306 -d ${{ matrix.mysql_docker_image }}
-          docker ps -a                                            # log docker image
           while ! echo exit | nc localhost 3306; do sleep 5; done # wait mysql to start accepting connections
 
       - name: Download source
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Install shards
         run: shards install
 
-      - name: Run specs
+      - name: Run specs (Socket)
+        run: DATABASE_HOST=${{ steps.setup-mysql.outputs.base-dir }}/tmp/mysql.sock crystal spec
+        if: matrix.database_host == '/tmp/mysql.sock'
+
+      - name: Run specs (Plain TCP)
         run: crystal spec
+        if: matrix.database_host == 'default'
 
       - name: Check formatting
         run: crystal tool format; git diff --exit-code

README.md

@@ -86,8 +86,29 @@ The connection string has the following syntax:
 mysql://[user[:[password]]@]host[:port][/schema][?param1=value1&param2=value2]
 ```
 
-Connection query params:
+#### Transport
 
-- encoding: The collation & charset (character set) to use during the connection.
+The driver supports tcp connection or unix sockets
+
+- `mysql://localhost` will connect using tcp and the default MySQL port 3306.
+- `mysql://localhost:8088` will connect using tcp using port 8088.
+- `mysql:///path/to/other.sock` will connect using unix socket `/path/to/other.sock`.
+
+Any of the above can be used with `user@` or `user:password@` to pass credentials.
+
+#### Default database
+
+A `database` query string will specify the default database. 
+Connection strings with a host can also use the first path component to specify the default database.
+Query string takes precedence because it's more explicit.
+
+- `mysql://localhost/mydb`
+- `mysql://localhost:3306/mydb`
+- `mysql://localhost:3306?database=mydb`
+- `mysql:///path/to/other.sock?database=mydb`
+
+#### Other query params
+
+- `encoding`: The collation & charset (character set) to use during the connection.
             If empty or not defined, it will be set to `utf8_general_ci`.
             The list of available collations is defined in [`MySql::Collations::COLLATIONS_IDS_BY_NAME`](src/mysql/collations.cr)

spec/connection_options_spec.cr

@@ -0,0 +1,125 @@
+require "./spec_helper"
+
+private def from_uri(uri)
+  Connection::Options.from_uri(URI.parse(uri))
+end
+
+private def tcp(host, port)
+  URI.new("tcp", host, port)
+end
+
+private def socket(path)
+  URI.new("unix", nil, nil, path)
+end
+
+describe Connection::Options do
+  describe ".from_uri" do
+    it "parses mysql://user@host/db" do
+      from_uri("mysql://root@localhost/test").should eq(
+        MySql::Connection::Options.new(
+          transport: tcp("localhost", 3306),
+          username: "root",
+          password: nil,
+          initial_catalog: "test",
+          charset: Collations.default_collation
+        )
+      )
+    end
+
+    it "parses mysql://host" do
+      from_uri("mysql://localhost").should eq(
+        MySql::Connection::Options.new(
+          transport: tcp("localhost", 3306),
+          username: nil,
+          password: nil,
+          initial_catalog: nil,
+          charset: Collations.default_collation
+        )
+      )
+    end
+
+    it "parses mysql://host:port" do
+      from_uri("mysql://localhost:1234").should eq(
+        MySql::Connection::Options.new(
+          transport: tcp("localhost", 1234),
+          username: nil,
+          password: nil,
+          initial_catalog: nil,
+          charset: Collations.default_collation
+        )
+      )
+    end
+
+    it "parses ?encoding=..." do
+      from_uri("mysql://localhost:1234?encoding=utf8mb4_unicode_520_ci").should eq(
+        MySql::Connection::Options.new(
+          transport: tcp("localhost", 1234),
+          username: nil,
+          password: nil,
+          initial_catalog: nil,
+          charset: "utf8mb4_unicode_520_ci"
+        )
+      )
+    end
+
+    it "parses mysql://user@host?database=db" do
+      from_uri("mysql://root@localhost?database=test").should eq(
+        MySql::Connection::Options.new(
+          transport: tcp("localhost", 3306),
+          username: "root",
+          password: nil,
+          initial_catalog: "test",
+          charset: Collations.default_collation
+        )
+      )
+    end
+
+    it "parses mysql:///path/to/socket" do
+      from_uri("mysql:///path/to/socket").should eq(
+        MySql::Connection::Options.new(
+          transport: socket("/path/to/socket"),
+          username: nil,
+          password: nil,
+          initial_catalog: nil,
+          charset: Collations.default_collation
+        )
+      )
+    end
+
+    it "parses mysql:///path/to/socket?database=test" do
+      from_uri("mysql:///path/to/socket?database=test").should eq(
+        MySql::Connection::Options.new(
+          transport: socket("/path/to/socket"),
+          username: nil,
+          password: nil,
+          initial_catalog: "test",
+          charset: Collations.default_collation
+        )
+      )
+    end
+
+    it "parses mysql:///path/to/socket?encoding=utf8mb4_unicode_520_ci" do
+      from_uri("mysql:///path/to/socket?encoding=utf8mb4_unicode_520_ci").should eq(
+        MySql::Connection::Options.new(
+          transport: socket("/path/to/socket"),
+          username: nil,
+          password: nil,
+          initial_catalog: nil,
+          charset: "utf8mb4_unicode_520_ci"
+        )
+      )
+    end
+
+    it "parses mysql://user:pass@/path/to/socket?database=test" do
+      from_uri("mysql://root:password@/path/to/socket?database=test").should eq(
+        MySql::Connection::Options.new(
+          transport: socket("/path/to/socket"),
+          username: "root",
+          password: "password",
+          initial_catalog: "test",
+          charset: Collations.default_collation
+        )
+      )
+    end
+  end
+end

spec/driver_spec.cr

@@ -32,7 +32,7 @@ describe Driver do
       db.exec "FLUSH PRIVILEGES"
     end
 
-    DB.open "mysql://crystal_test:secret@#{database_host}/crystal_mysql_test" do |db|
+    DB.open "mysql://crystal_test:secret@#{database_host}?database=crystal_mysql_test" do |db|
       db.scalar("SELECT DATABASE()").should eq("crystal_mysql_test")
       db.scalar("SELECT CURRENT_USER()").should match(/^crystal_test@/)
     end
@@ -48,7 +48,7 @@ describe Driver do
       db.exec "CREATE DATABASE crystal_mysql_test"
 
       # By default, the encoding for the  DB connection is set to utf8_general_ci
-      DB.open "mysql://crystal_test:secret@#{database_host}/crystal_mysql_test" do |db|
+      DB.open "mysql://crystal_test:secret@#{database_host}?database=crystal_mysql_test" do |db|
         db.scalar("SELECT @@collation_connection").should eq("utf8_general_ci")
         db.scalar("SELECT @@character_set_connection").should eq("utf8")
       end
@@ -61,7 +61,7 @@ describe Driver do
       db.exec "DROP DATABASE IF EXISTS crystal_mysql_test"
       db.exec "CREATE DATABASE crystal_mysql_test"
 
-      DB.open "mysql://crystal_test:secret@#{database_host}/crystal_mysql_test?encoding=utf8mb4_unicode_520_ci" do |db|
+      DB.open "mysql://crystal_test:secret@#{database_host}?database=crystal_mysql_test&encoding=utf8mb4_unicode_520_ci" do |db|
         db.scalar("SELECT @@collation_connection").should eq("utf8mb4_unicode_520_ci")
         db.scalar("SELECT @@character_set_connection").should eq("utf8mb4")
       end

spec/spec_helper.cr

@@ -5,7 +5,11 @@ require "semantic_version"
 include MySql
 
 def db_url(initial_db = nil)
-  "mysql://root@#{database_host}/#{initial_db}"
+  if initial_db
+    "mysql://root@#{database_host}?database=#{initial_db}"
+  else
+    "mysql://root@#{database_host}"
+  end
 end
 
 def database_host
@@ -18,7 +22,7 @@ def with_db(database_name, options = nil, &block : DB::Database ->)
     db.exec "CREATE DATABASE crystal_mysql_test"
   end
 
-  DB.open "#{db_url(database_name)}?#{options}", &block
+  DB.open "#{db_url(database_name)}&#{options}", &block
 ensure
   DB.open db_url do |db|
     db.exec "DROP DATABASE IF EXISTS crystal_mysql_test"

src/mysql/connection.cr

@@ -2,41 +2,59 @@ require "socket"
 
 class MySql::Connection < DB::Connection
   record Options,
-    host : String,
-    port : Int32,
+    transport : URI,
     username : String?,
     password : String?,
     initial_catalog : String?,
     charset : String do
     def self.from_uri(uri : URI) : Options
-      host = uri.hostname || raise "no host provided"
-      port = uri.port || 3306
+      params = uri.query_params
+      initial_catalog = params["database"]?
+
+      if (host = uri.hostname) && !host.blank?
+        port = uri.port || 3306
+        transport = URI.new("tcp", host, port)
+
+        # for tcp socket we support the first component to be the database
+        # but the query string takes precedence because it's more explicit
+        if initial_catalog.nil? && (path = uri.path) && path.size > 1
+          initial_catalog = path[1..-1]
+        end
+      else
+        transport = URI.new("unix", nil, nil, uri.path)
+      end
+
       username = uri.user
       password = uri.password
 
-      charset = uri.query_params.fetch "encoding", Collations.default_collation
-
-      path = uri.path
-      if path && path.size > 1
-        initial_catalog = path[1..-1]
-      else
-        initial_catalog = nil
-      end
+      charset = params.fetch "encoding", Collations.default_collation
 
       Options.new(
-        host: host, port: port, username: username, password: password,
+        transport: transport,
+        username: username, password: password,
         initial_catalog: initial_catalog, charset: charset)
     end
   end
 
   def initialize(options : ::DB::Connection::Options, mysql_options : ::MySql::Connection::Options)
     super(options)
-    @socket = uninitialized TCPSocket
+    @socket = uninitialized UNIXSocket | TCPSocket
 
     begin
       charset_id = Collations.id_for_collation(mysql_options.charset).to_u8
 
-      @socket = TCPSocket.new(mysql_options.host, mysql_options.port)
+      transport = mysql_options.transport
+      @socket =
+        case transport.scheme
+        when "tcp"
+          host = transport.host || raise "Missing host in transport #{transport}"
+          TCPSocket.new(host, transport.port)
+        when "unix"
+          UNIXSocket.new(transport.path)
+        else
+          raise "Transport not supported #{transport}"
+        end
+
       handshake = read_packet(Protocol::HandshakeV10)
 
       write_packet(1) do |packet|