Connections and transports

Basics

To send and receive messages you need a transport and a connection. There are several transports to choose from (amqplib, pika, redis, in-memory), and you can even create your own. The default transport is amqplib.

Create a connection using the default transport:

>>> from kombu import BrokerConnection
>>> connection = BrokerConnection("amqp://guest:guest@localhost:5672//")

The connection will not be established yet, as the connection is established when needed. If you want to explicitly establish the connection you have to call the connect() method:

>>> connection.connect()

You can also check whether the connection is connected:

>>> connection.connected()
True

Connections must always be closed after use:

>>> connection.close()

But best practice is to release the connection instead, this will release the resource if the connection is associated with a connection pool, or close the connection if not, and makes it easier to do the transition to connection pools later:

>>> connection.release()

Of course, the connection can be used as a context, and you are encouraged to do so as it makes it harder to forget releasing open resources:

with BrokerConnection() as connection:
    # work with connection

URLs

Connection parameters can be provided as an URL in the format:

transport://userid:password@hostname:port/virtual_host

All of these are valid URLs:

# Specifies using the amqp transport only, default values
# are taken from the keyword arguments.
amqp://

# Using Redis
redis://localhost:6379/

# Using virtual host '/foo'
amqp://localhost//foo

# Using virtual host 'foo'
amqp://localhost/foo

The query part of the URL can also be used to set options, e.g.:

amqp://localhost/myvhost?ssl=1

See Keyword arguments for a list of supported options.

A connection without options will use the default connection settings, which is using the localhost host, default port, user name guest, password guest and virtual host “/”. A connection without arguments is the same as:

>>> BrokerConnection("amqp://guest:guest@localhost:5672//")

The default port is transport specific, for AMQP this is 5672.

Other fields may also have different meaning depending on the transport used. For example, the Redis transport uses the virtual_host argument as the redis database number.

Keyword arguments

The BrokerConnection class supports additional keyword arguments, these are:

hostname:Default host name if not provided in the URL.
userid:Default user name if not provided in the URL.
password:Default password if not provided in the URL.
virtual_host:Default virtual host if not provided in the URL.
port:Default port if not provided in the URL.
transport:Default transport if not provided in the URL. Can be a string specifying the path to the class. (e.g. kombu.transport.pyamqplib.Transport), or one of the aliases: amqplib, pika, redis, memory, and so on.
ssl:Use SSL to connect to the server. Default is False. Only supported by the amqp transport.
insist:Insist on connecting to a server. In a configuration with multiple load-sharing servers, the insist option tells the server that the client is insisting on a connection to the specified server. Default is False. Only supported by the amqp and pika transports, and not by AMQP 0-9-1.
connect_timeout:
 Timeout in seconds for connecting to the server. May not be supported by the specified transport.
transport_options:
 A dict of additional connection arguments to pass to alternate kombu channel implementations. Consult the transport documentation for available options.

Transport Comparison

Client Type Direct Topic Fanout
amqplib Native Yes Yes Yes
pika Native Yes Yes Yes
redis Virtual Yes Yes [1] Yes (PUB/SUB)
beanstalk Virtual Yes Yes [1] No
SQS Virtual Yes Yes [1] Yes [2]
mongodb Virtual Yes Yes [1] No
couchdb Virtual Yes Yes [1] No
in-memory Virtual Yes Yes [1] No
[1](1, 2, 3, 4, 5, 6) Declarations only kept in memory, so exchanges/queues must be declared by all clients that needs them.
[2]Fanout supported via storing routing tables in SimpleDB. Can be disabled by setting the supports_fanout transport option.

Table Of Contents

Previous topic

Introduction

Next topic

Producers

This Page