Makara Documentation

Stickiness ensures that once a query is sent to the primary, subsequent queries in the same request (or subsequent requests) are also routed to the primary to maintain consistency.

Configuration Modes

• sticky: true: Once a query hits the primary, all queries for the remainder of the request go to the primary. Makara sets a client-side cookie (_mkra_stck) with an expiration based on primary_ttl. As long as the cookie is valid, all requests will use the primary.
• sticky: false: Only queries that explicitly require the primary (via needs_primary?) will go there. Subsequent read queries in the same request will continue to go to replicas.

Managing Stickiness

• Forcing Primary: Use proxy.stick_to_primary!(persist) to force the proxy to stick to the primary. If persist is true (default), the stickiness is saved to the context for subsequent requests.
• Skipping Stickiness: To perform an operation that would normally trigger stickiness without actually sticking the context, wrap the code in a proxy.without_sticking block.
• Clearing Context: You can release stuck connections using Makara::Context.release_all or for a specific proxy using Makara::Context.release(proxy_id) or Makara::Context.release('name').

# Force primary and persist across requests
proxy.stick_to_primary!(true)

# Run code without triggering stickiness
proxy.without_sticking do
  # logic here
end

# Clear all stuck connections in the current thread
Makara::Context.release_all

To implement a custom connection selection strategy in Makara, inherit from Makara::Strategies::Abstract. Your implementation must provide a current method to return the connection that should be used for the current request (the 'sticky' connection) and a next method to determine which connection should be used for the subsequent request (the 'rotation' logic).

Key lifecycle methods:

• initialize(pool): Sets the connection pool.
• init: An explicit constructor hook that can be overridden to perform setup logic.
• connection_added(wrapper): An optional hook called when a new connection is added to the pool.
• current: Required. Returns the connection to be used now.
• next: Required. Returns the connection to be used next.

module Makara
  module Strategies
    class MyCustomStrategy < Abstract
      def current
        # Return the current sticky connection
      end

      def next
        # Return the next connection in rotation
      end
    end
  end
end

The MakaraAbstractAdapter uses SQL pattern matching to decide whether a query should be routed to the primary database or can be safely executed on a replica.

• Primary (Master) Queries: Queries that involve locking or specific sequence operations are routed to the primary. This includes SELECT ... FOR UPDATE, SELECT ... LOCK IN SHARE MODE, and calls to sequence functions like nextval, currval, lastval, get_lock, etc.
• Replica (Slave) Queries: Standard SELECT statements are generally routed to replicas.
• All-Connection Queries: Queries matching SET patterns (e.g., SET ...) are executed on all connections in the pool.
• Skip Stickiness: Certain metadata queries (e.g., SHOW FIELDS, DESCRIBE, EXPLAIN, PRAGMA) skip stickiness logic.

Note: sql_master_matchers and sql_slave_matchers are deprecated. Use sql_primary_matchers and sql_replica_matchers instead.

To use Makara, set your adapter to #{db_type}_makara (e.g., mysql2_makara or postgresql_makara) and provide a makara configuration block.

Configuration Options

Top-level makara options:

• id: An identifier for the proxy. Highly recommended if sticky: true is used, to prevent stickiness from breaking when the configuration changes.
• blacklist_duration: Seconds a node is blacklisted after a connection failure (default: 5).
• disable_blacklist: If true, nodes are not blacklisted on error.
• sticky: If true, a node is stuck to once used during a specific context.
• primary_ttl: How long the primary context is persisted (should be longer than replication lag).
• primary_strategy: Strategy for picking the primary node (round_robin [default] or failover).
• replica_strategy: Strategy for picking the replica node (round_robin [default] or failover).
• connection_error_matchers: An array of regexes or strings used to identify errors that should trigger blacklisting instead of being raised.

Connection options:

Each connection in the connections list can override top-level settings.

• role: Must be set to primary for the primary node. If omitted, the node is assumed to be a replica.
• weight: Used to balance traffic (e.g., a node with weight 8 receives more traffic than weight 2).
• name: An optional attribute used for SQL logging.
• url: A full connection string (e.g., mysql2://user:pass@host:port/db).

Warning: Do NOT use the standard ENV['DATABASE_URL'] as it interferes with Makara's initialization. Use custom environment variables instead.

production:
  adapter: 'mysql2_makara'
  database: 'MyAppProduction'
  makara:
    id: mysql
    blacklist_duration: 5
    primary_ttl: 5
    primary_strategy: round_robin
    sticky: true
    connections:
      - role: primary
        host: primary.sql.host
      - role: replica
        host: replica1.sql.host
        weight: 8
        name: Big Replica
      - role: replica
        host: replica2.sql.host
        weight: 2
        name: Small Replica