MySQL Proxy learns R/W Splitting

The trunk version of the MySQL Proxy 0.6.0 just learnt about changing backends within running connection. It is now up to lua-script to decide which backend shall be used to send requests too.

We wrote a complete tutorial which covers everything from:

building and maintaining a connection pool with high and low water marks
transparent authentication (no extra auth against the proxy)
deciding on Query Level which backend to use

and implement a transparent read/write splitter which sends all non-transactional Queries to the slaves and the rest to the master.

R/W Splitting

As the splitting is in the hands of the lua-scripting level you can use the same to implement sharding or other rules to route traffic on statement level.

Connection Pooling

For R/W Splitting we need a connection pooling. We only switch to another backend if we already have a authenticated connection open to that backend.

The MySQL protocol first does a challenge-response handshake. When we enter the query/result stage it is too late to authenticate new connections. We have to make sure that we have enough open connections to operate nicely.

MySQL Protocol States

In the keepalive tutorial we spend quite some code on connection management. The whole connect_servers() function is only to create new connections for all pools.

create one connection to each backend
create new connections until we reach min-idle-connections
if the two above conditions are met, use a connection from the pool

Let's take a glimpse at the code:

--- config
--
-- connection pool
local min_idle_connections = 4
local max_idle_connections = 8

---
-- get a connection to a backend
--
-- as long as we don't have enough connections in the pool, create new connections
--
function connect_server()
  -- make sure that we connect to each backend at least ones to
  -- keep the connections to the servers alive
  --
  -- on read_query we can switch the backends again to another backend

  local least_idle_conns_ndx = 0
  local least_idle_conns = 0

  for i = 1, #proxy.servers do
    local s = proxy.servers[i]

    if s.state ~= proxy.BACKEND_STATE_DOWN then
      -- try to connect to each backend once at least
      if s.idling_connections == 0 then
        proxy.connection.backend_ndx = i
        return
      end

      -- try to open at least min_idle_connections
      if least_idle_conns_ndx == 0 or
         ( s.idling_connections < min_idle_connections and
           s.idling_connections < least_idle_conns ) then
        least_idle_conns_ndx = i
        least_idle_conns = s.idling_connections
      end
    end
  end

  if least_idle_conns_ndx > 0 then
    proxy.connection.backend_ndx = least_idle_conns_ndx
  end

  if proxy.connection.backend_ndx > 0 and
     proxy.servers[proxy.connection.backend_ndx].idling_connections >= min_idle_connections then
    -- we have 4 idling connections in the pool, that's good enough

    return proxy.PROXY_IGNORE_RESULT
  end

  -- open a new connection
end

The real trick is in

---
-- put the authed connection into the connection pool
function read_auth_result(packet)
  -- disconnect from the server
  proxy.connection.backend_ndx = 0
end

The proxy.connection.backend_ndx = 0 we disconnect us from the current backend (lua starts indexing at index 1, 0 is out of bounds). If a second connection comes in now it can use this authed connection too as it is in the pool, idling.

By setting proxy.connection.backend_ndx you control which backend is used to send your packets too. A backend is defined as a entry of the proxy.servers table. Each connection has (zero or) one backend. The backends all have a address, a type (RW or RO) and a state (UP or DOWN).

As we also might have to many open connections in the pool we close them on shutdown again if necessary:

---
-- close the connections if we have enough connections in the pool
--
-- @return nil - close connection
--         IGNORE_RESULT - store connection in the pool
function disconnect_client()
  if proxy.connection.backend_ndx == 0 then
    -- currently we don't have a server backend assigned
    --
    -- pick a server which has too many idling connections and close one
    for i = 1, #proxy.servers do
      local s = proxy.servers[i]

      if s.state ~= proxy.BACKEND_STATE_DOWN and
         s.idling_connections > max_idle_connections then
        -- try to disconnect a backend
        proxy.connection.backend_ndx = i
        return
      end
    end
  end
end

We only search for a backend which has to many open idling connections and use it before we enter the default behaviour of disconnect_client: shutdown the server connection. if proxy.connection.backend_ndx == 0 then is the "we don't have backend associated right now". We already saw this in read_auth_result.

Read/Write Splitting

That is our maintainance of the pool. connect_server() adds new auth'ed connections to the pool, disconnect_client() closes them again. The read/write splitting is part of the query/result cycle:

-- read/write splitting
function read_query( packet )
  if packet:byte() == proxy.COM_QUIT then
    -- don't send COM_QUIT to the backend. We manage the connection
    -- in all aspects.
    proxy.response = {
      type = proxy.MYSQLD_PACKET_ERR,
      errmsg = "ignored the COM_QUIT"
    }

    return proxy.PROXY_SEND_RESULT
  end

  -- as we switch between different connenctions we have to make sure that
  -- we use always the same DB
  if packet:byte() == proxy.COM_INIT_DB then
    -- default_db is connection global
    default_db = packet:sub(2)
  end

  if proxy.connection.backend_ndx == 0 then
    -- we don't have a backend right now
    --
    -- let's pick a master as a good default
    for i = 1, #proxy.servers do
      local s = proxy.servers[i]

      if s.idling_connections > 0 and
         s.state ~= proxy.BACKEND_STATE_DOWN and
         s.type == proxy.BACKEND_TYPE_RW then
        proxy.connection.backend_ndx = i
        break
      end
    end
  end

  if packet:byte() == proxy.COM_QUERY and default_db then
    -- how can I know the db of the server connection ?
    proxy.queries:append(2, string.char(proxy.COM_INIT_DB) .. default_db)
  end
  proxy.queries:append(1, packet)

Up to now it is only making sure that we behave nicely: don't forward COM_QUIT to the backend as he will close the connection on us intercept the COM_INIT_DB to know which DB the client wants to work on. If we switch to another backend we have to make sure the same DB is used.

The read/write splitting is now following a simple rule: send all non-transactional SELECTs to a slave everything else goes to the master

We are still in read_query()

  -- read/write splitting
  --
  -- send all non-transactional SELECTs to a slave
  if is_in_transaction == 0 and
     packet:byte() == proxy.COM_QUERY and
     packet:sub(2, 7) == "SELECT" then
    local max_conns = -1
    local max_conns_ndx = 0

    for i = 1, #proxy.servers do
      local s = proxy.servers[i]

      -- pick a slave which has some idling connections
      if s.type == proxy.BACKEND_TYPE_RO and
         s.idling_connections > 0 then
        if max_conns == -1 or
           s.connected_clients < max_conns then
          max_conns = s.connected_clients
          max_conns_ndx = i
        end
      end
    end

    -- we found a slave which has a idling connection
    if max_conns_ndx > 0 then
      proxy.connection.backend_ndx = max_conns_ndx
    end
  else
    -- send to master
  end

  return proxy.PROXY_SEND_QUERY
end

If we found a slave host which has a idling connection we pick it. If all slaves are busy or down, we just send the query to the master.

As soon as we don't need this connection anymore give it backend to the pool:

---
-- as long as we are in a transaction keep the connection
-- otherwise release it so another client can use it
function read_query_result( inj )
  local res      = assert(inj.resultset)
  local flags    = res.flags

  if inj.id ~= 1 then
    -- ignore the result of the USE <default_db>
    return proxy.PROXY_IGNORE_RESULT
  end
  is_in_transaction = flags.in_trans

  if is_in_transaction == 0 then
    -- release the backend
    proxy.connection.backend_ndx = 0
  end
end

The MySQL Protocol is nice and offers us a in-transaction-flag. This operates on the state of the transaction and works across all engines. If you want to make sure that several statements go to the same backend, open a transaction with BEGIN. No matter which storage engine you use.

Possible extensions

While we are here in this section of the code think about another use case:

if the master is down, ban all writing queries and only allow reading selects against the slaves.

It keeps your site up and running even if your master is gone. You only have to handle errors on write-statements and transactions.

Known Problems

We might have a race-condition that idling connection closes before we can use it. In that case we are in trouble right now and will close the connection to the client.

We have to add queuing of connections and awaking them up when the connection becomes available again to handle this later.

Next Steps

Testing, testing, testing.

$ mysql-proxy \
    --proxy-backend-addresses=10.0.0.1:3306 \
    --proxy-read-only-backend-addresses=10.0.0.10:3306 \
    --proxy-read-only-backend-addresses=10.0.0.12:3306 \
    --proxy-lua-script=examples/tutorial-keepalive.lua

The above code works for my tests, but I don't have any real load. Nor can I create all the error-cases you have in your real-life setups. Please send all your comments, concerns and ideas to the MySQL Proxy forum.

Another upcoming step is externalizing all the load-balancer code and move it into modules to make the code easier to understand and reuseable.