# @title Ruby AMQP gem: Durability and related matters

h1. Durability and related matters


h2. About this guide

This guide covers queue, exchange and message durability, as well as other
topics related to durability, for example, durability in cluster environment.


h2. Covered versions

This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.8.0 and later.


h2. Entity durability and message persistence

h3. Durability of exchanges

AMQP separates concept of durability of entities (queues, exchanges) from messages persistence.
Exchanges can be durable or transient. Durable exchanges survive broker restart, transient exchanges don't (they
have to be redeclared when broker comes back online). Not all scenarios and use cases mandate exchanges to be
durable.


h3. Durability of queues

Durable queues are persisted to disk and thus survive broker restarts. Queues that are not durable are called transient.
Not all scenarios and use cases mandate queues to be durable.

Note that *only durable queues can be bound to durable exchanges*. This guarantees that it is possible to restore bindings
on broker restart.

Durability of a queue does not make _messages_ that are routed to that queue durable. If broker is taken down and then
brought back up, durable queue will be re-declared during broker startup, however, only _persistent_ messages will be recovered.


h3. Persistence of messages

The concept of messages persistence is separate: messages may be published as persistent. That makes
AMQP broker persist them to disk. If the server is restarted, the system ensures that received persistent messages
are not lost. Simply publishing message to a durable exchange or the fact that queue(s) they are routed to
is durable doesn't make messages persistent: it all depends on persistence mode of the messages itself.
Publishing messages as persistent affects performance (just like with data stores, durability comes at a certain cost
in performance and vise versa). Pass :persistent => true to {Exchange#publish} to publish your message as persistent.


h3. Transactions

TBD


h3. Publisher confirms

Because transactions carry certain (for some applications, significant) overhead, RabbitMQ introduced an extension to AMQP 0.9.1
called {http://www.rabbitmq.com/blog/2011/02/10/introducing-publisher-confirms/ publisher confirms} ({http://www.rabbitmq.com/extensions.html#confirms documentation}).

amqp gem implements support for this extension, but it is not loaded by default when you require "amqp". To load it, use

<pre>
<code>
require "amqp/extensions/rabbitmq"
</code>
</pre>

and then define a callback for publisher confirms using {AMQP::Channel#confirm}:

<pre>
<code>
# enable publisher acknowledgements for this channel
channel.confirm_select

# define a callback that will be executed when message is acknowledged
channel.on_ack do |basic_ack|
  puts "Received an acknowledgement: delivery_tag = #{basic_ack.delivery_tag}, multiple = #{basic_ack.multiple}"
end

# define a callback that will be executed when message is rejected using basic.nack (a RabbitMQ-specific extension)
channel.on_nack do |basic_nack|
  puts "Received a nack: delivery_tag = #{basic_nack.delivery_tag}, multiple = #{basic_nack.multiple}"
end
</code>
</pre>

Note that the same callback is used for all messages published via all exchanges on the given channel.


h3. Clustering

To achieve degree of durability critical applications need, it's necessary but not enough to use durable queues,
exchanges and persistent messages. You need to use a cluster of brokers because otherwise, a single hardware problem
may bring broker down completely.

See {file:docs/Clustering.textile Clustering guide} for in-depth discussion of this topic.



h2. Tell us what you think!

Please take a moment and tell us what you think about this guide on "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp:
what was unclear? what wasn't covered? maybe you don't like guide style or grammar and spelling are incorrect? Readers feedback is
key to making documentation better.

If mailing list communication is not an option for you for some reason, you can "contact guides author directly":mailto:michael@novemberain.com?subject=amqp%20gem%20documentation



<div id="disqus_thread"></div>
<script type="text/javascript">
    /* * * CONFIGURATION VARIABLES * * */
    var disqus_shortname = 'rubyamqpdocs'; // required: replace example with your forum shortname

    var disqus_developer = 0; // set to 1 on local machine for testing comments
    var disqus_identifier = 'amqp_durability';
    var disqus_url = 'http://rdoc.info/github/ruby-amqp/amqp/master/file/docs/Durability.textile';

    /* * * DON'T EDIT BELOW THIS LINE * * */
    (function() {
        var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
        dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js';
        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
    })();
</script>