Rework error codes (#134)

Author: wojtekmach

.github/workflows/ci.yml

@@ -10,6 +10,7 @@ jobs:
   test:
     runs-on: ubuntu-16.04
     strategy:
+      fail-fast: false
       matrix:
         db:
           - mysql:5.6

lib/myxql.ex

@@ -96,7 +96,7 @@ defmodule MyXQL do
       the prepare statement count of your databases (such as using a dashboard or
       setting alarm handlers)
 
-    * `:disconnect_on_error_codes` - List of error code atoms that when encountered
+    * `:disconnect_on_error_codes` - List of error code integers or atoms that when encountered
       will disconnect the connection. See "Disconnecting on Errors" section below for more
       information.
 
@@ -129,11 +129,11 @@ defmodule MyXQL do
       iex> {:ok, pid} = MyXQL.start_link(after_connect: &MyXQL.query!(&1, "SET time_zone = '+00:00'"))
       {:ok, #PID<0.69.0>}
 
-  ## Disconnecting on Errors
+  ## Disconnecting on errors
 
-  Sometimes the connection becomes unusable. For example, some services, such as AWS Aurora,
-  support failover. This means the database you are currently connected to may suddenly become
-  read-only, and an attempt to do any write operation, such as INSERT/UPDATE/DELETE will lead to
+  Sometimes the connection becomes unusable. For example, services such as AWS Aurora support
+  failover which means the database you are currently connected to may suddenly become
+  read-only. An attempt to do any write operation, such as INSERT/UPDATE/DELETE will lead to
   errors such as:
 
       ** (MyXQL.Error) (1792) (ER_CANT_EXECUTE_IN_READ_ONLY_TRANSACTION) Cannot execute statement in a READ ONLY transaction.
@@ -147,18 +147,35 @@ defmodule MyXQL do
   MyXQL automatically disconnects the connection on the following error codes and they don't have
   to be configured:
 
-    * `ER_MAX_PREPARED_STMT_COUNT_REACHED`
+    * `:ER_MAX_PREPARED_STMT_COUNT_REACHED`
 
-  To convert error code number to error code name you can use `perror` command-line utility that
-  ships with MySQL client installation, e.g.:
+  You can pass error codes as integers too:
+
+      disconnect_on_error_codes: [1792]
+
+  ## Error codes
+
+  MyXQL maintains a mapping of integers/atoms for commonly used errors. You can add additional
+  ones by adding the following compile-time configuration:
+
+      config :myxql, :extra_error_codes, [
+        {1048, :ER_BAD_NULL_ERROR}
+      ]
+
+  After adding the configuration, MyXQL needs to be recompiled. It can be done with:
+
+      $ mix deps.clean myxql --build
+
+  To convert error code integers to names you can use `perror` command-line utility that ships
+  with MySQL client installation, e.g.:
 
       bash$ perror 1792
       MySQL error code 1792 (ER_CANT_EXECUTE_IN_READ_ONLY_TRANSACTION): Cannot execute statement in a READ ONLY transaction.
 
   """
   @spec start_link([start_option()]) :: {:ok, pid()} | {:error, MyXQL.Error.t()}
   def start_link(options) do
-    ensure_deps_started!(options)
+    options = ensure_valid_error_codes!(options)
     DBConnection.start_link(MyXQL.Connection, options)
   end
 
@@ -526,9 +543,9 @@ defmodule MyXQL do
   Returns a supervisor child specification for a DBConnection pool.
   """
   @spec child_spec([start_option()]) :: :supervisor.child_spec()
-  def child_spec(opts) do
-    ensure_deps_started!(opts)
-    DBConnection.child_spec(MyXQL.Connection, opts)
+  def child_spec(options) do
+    options = ensure_valid_error_codes!(options)
+    DBConnection.child_spec(MyXQL.Connection, options)
   end
 
   @doc """
@@ -547,18 +564,37 @@ defmodule MyXQL do
 
   ## Helpers
 
-  defp ensure_deps_started!(opts) do
-    if Keyword.get(opts, :ssl, false) and
-         not List.keymember?(:application.which_applications(), :ssl, 0) do
-      raise """
-      SSL connection cannot be established because `:ssl` application is not started,
-      you can add it to `:extra_applications` in your `mix.exs`:
+  defp ensure_valid_error_codes!(opts) do
+    default_error_codes = [
+      :ER_MAX_PREPARED_STMT_COUNT_REACHED
+    ]
 
-          def application() do
-            [extra_applications: [:ssl]]
+    codes = default_error_codes ++ Keyword.get(opts, :disconnect_on_error_codes, [])
+
+    codes =
+      for code <- codes do
+        if is_integer(code) do
+          code
+        else
+          integer = MyXQL.Protocol.ServerErrorCodes.name_to_code(code)
+
+          unless integer do
+            raise """
+            #{inspect(code)} is not a recognized error code
+
+            To solve this, you can either:
+
+              - pass an integer error code
+
+              - make it recognizable by adding it to `config :myxql, extra_error_codes: [...]`
+                (See "Error codes" in MyXQL.start_link/1 documentation for more information).
+            """
           end
 
-      """
-    end
+          integer
+        end
+      end
+
+    Keyword.put(opts, :disconnect_on_error_codes, codes)
   end
 end

lib/myxql/connection.ex

@@ -5,10 +5,6 @@ defmodule MyXQL.Connection do
   import MyXQL.Protocol.{Flags, Records}
   alias MyXQL.{Client, Cursor, Query, Protocol, Result, TextQuery}
 
-  @disconnect_on_error_codes [
-    :ER_MAX_PREPARED_STMT_COUNT_REACHED
-  ]
-
   defstruct [
     :client,
     cursors: %{},
@@ -26,15 +22,12 @@ defmodule MyXQL.Connection do
     ping_timeout = Keyword.get(opts, :ping_timeout, 15_000)
     config = Client.Config.new(opts)
 
-    disconnect_on_error_codes =
-      @disconnect_on_error_codes ++ Keyword.get(opts, :disconnect_on_error_codes, [])
-
     case Client.connect(config) do
       {:ok, %Client{} = client} ->
         state = %__MODULE__{
           client: client,
           prepare: prepare,
-          disconnect_on_error_codes: disconnect_on_error_codes,
+          disconnect_on_error_codes: Keyword.fetch!(opts, :disconnect_on_error_codes),
           ping_timeout: ping_timeout,
           queries: queries_new()
         }
@@ -348,7 +341,7 @@ defmodule MyXQL.Connection do
 
   defp error(err_packet(code: code, message: message)) do
     name = Protocol.error_code_to_name(code)
-    %MyXQL.Error{message: "(#{code}) (#{name}) " <> message, mysql: %{code: code, name: name}}
+    %MyXQL.Error{mysql: %{code: code, name: name}, message: message}
   end
 
   defp error(reason) do
@@ -385,9 +378,9 @@ defmodule MyXQL.Connection do
   end
 
   defp maybe_disconnect(exception, state) do
-    %MyXQL.Error{mysql: %{name: error_name}} = exception
+    %MyXQL.Error{mysql: %{code: code}} = exception
 
-    if error_name in state.disconnect_on_error_codes do
+    if code in state.disconnect_on_error_codes do
       {:disconnect, exception, state}
     else
       {:error, exception, state}

lib/myxql/error.ex

@@ -9,7 +9,16 @@ defmodule MyXQL.Error do
   @type t :: %__MODULE__{
           connection_id: non_neg_integer() | nil,
           message: String.t(),
-          mysql: %{code: integer(), name: atom()} | nil,
+          mysql: %{code: integer(), name: atom() | nil} | nil,
           statement: iodata() | nil
         }
+
+  @impl true
+  def message(%{mysql: %{code: code, name: nil}, message: message}) do
+    "(#{code}) " <> message
+  end
+
+  def message(%{mysql: %{code: code, name: name}, message: message}) do
+    "(#{code}) (#{name})" <> message
+  end
 end