# `AMQP.Connection`
[🔗](https://github.com/pma/amqp/blob/v4.2.1/lib/amqp/connection.ex#L1)

Functions to operate on Connections.

# `t`

```elixir
@type t() :: %AMQP.Connection{pid: pid()}
```

# `close`

```elixir
@spec close(t()) :: :ok | {:error, any()}
```

Closes an open Connection.

Please note that the closing will be performed asynchronously.
To verify the actual closure, you must monitor the process.

# `open`

```elixir
@spec open(keyword() | String.t()) :: {:ok, t()} | {:error, atom()} | {:error, any()}
```

Opens a new connection.

Behaves like `open/2` but takes only either AMQP URI or options.

## Examples

    iex> options = [host: "localhost", port: 5672, virtual_host: "/", username: "guest", password: "guest"]
    iex> AMQP.Connection.open(options)
    {:ok, %AMQP.Connection{}}

    iex> AMQP.Connection.open("amqp://guest:guest@localhost")
    {:ok, %AMQP.Connection{}}

# `open`

```elixir
@spec open(String.t() | keyword(), keyword() | String.t() | :undefined) ::
  {:ok, t()} | {:error, atom()} | {:error, any()}
```

Opens an new Connection to an AMQP broker.

The connections created by this module are supervised under  amqp_client's
supervision tree.  Please note that connections do not get restarted
automatically by the supervision tree in case of a failure. If you need
robust connections and channels, use monitors on the returned connection PID.

## Options

  * `:username` - The name of a user registered with the broker (default
    `"guest"`)

  * `:password` - The password of user (default to `"guest"`)

  * `:virtual_host` - The name of a virtual host in the broker (defaults
    `"/"`)

  * `:host` - The hostname of the broker (default `"localhost"`)

  * `:port` - The port the broker is listening on (default `5672`)

  * `:channel_max` - The channel_max handshake parameter (default `0`)

  * `:frame_max` - The frame_max handshake parameter (defaults `0`)

  * `:heartbeat` - The heartbeat interval in seconds (defaults `10`)

  * `:connection_timeout` - The connection timeout in milliseconds (efaults
    `50000`)

  * `:ssl_options` - Enable SSL by setting the location to cert files
    (default `:none`)

  * `:client_properties` - A list of extra client properties to be sent to
    the server (default `[]`)

  * `:socket_options` - Extra socket options. These are appended to the
    default options. See http://www.erlang.org/doc/man/inet.html#setopts-2 and
    http://www.erlang.org/doc/man/gen_tcp.html#connect-4 for descriptions of
    the available options

  * `:auth_mechanisms` - A list of authentication of SASL authentication
    mechanisms to use. See
    https://www.rabbitmq.com/access-control.html#mechanisms and
    https://github.com/rabbitmq/rabbitmq-auth-mechanism-ssl for descriptions of
    the available options

  * `:name` - A human-readable string that will be displayed in the
    management UI. Connection names do not have to be unique and cannot be
    used as connection identifiers (default `:undefined`)

## Examples

    iex> options = [host: "localhost", port: 5672, virtual_host: "/", username: "guest", password: "guest", name: "my-conn"]
    iex> AMQP.Connection.open(options)
    {:ok, %AMQP.Connection{}}

    iex> AMQP.Connection.open("amqp://guest:guest@localhost", port: 5673)
    {:ok, %AMQP.Connection{}}

## Enabling SSL

To enable SSL, supply the following in the `ssl_options` field:

  * `:cacertfile` - Specifies the certificates of the root Certificate
    Authorities that we wish to implicitly trust

  * `:certfile` - The client's own certificate in PEM format

  * `:keyfile` - The client's private key in PEM format

Here is an example:

    iex> AMQP.Connection.open(
      port: 5671,
      ssl_options: [
        cacertfile: '/path/to/testca/cacert.pem',
        certfile: '/path/to/client/cert.pem',
        keyfile: '/path/to/client/key.pem',
        # only necessary with intermediate CAs
        # depth: 2,
        verify: :verify_peer
      ]
    )

## Backward compatibility for connection name

RabbitMQ supports user-specified connection names since version 3.6.2.

Previously AMQP took a connection name as a separate parameter on `open/2`
and `open/3` and it is still supported in this version.

    iex> options = [host: "localhost", port: 5672, virtual_host: "/", username: "guest", password: "guest"]
    iex> AMQP.Connection.open(options, :undefined)
    {:ok, %AMQP.Connection{}}

    iex> AMQP.Connection.open("amqp://guest:guest@localhost", "my-connection")
    {:ok, %AMQP.Connection{}}

    iex> AMQP.Connection.open("amqp://guest:guest@localhost", "my-connection", options)
    {:ok, %AMQP.Connection{}}

However the connection name parameter is now deprecated and might not be
supported in the future versions.

You are recommended to pass it with `:name` option instead:

    iex> AMQP.Connection.open("amqp://guest:guest@localhost", name: "my-connection")
    {:ok, %AMQP.Connection{}}

# `update_secret`

```elixir
@spec update_secret(t(), String.t(), String.t()) :: :ok | {:error, any()}
```

Updates the secret used to authenticate the given Connection.

This is useful when the credentials used to open the connection have a
limited lifetime, such as an OAuth 2 token, and need to be renewed before
they expire so the broker does not close the connection.

`new_secret` is the new secret and `reason` is a short human readable string
explaining why the secret is being updated.

## Examples

    iex> {:ok, conn} = AMQP.Connection.open()
    iex> AMQP.Connection.update_secret(conn, "new-token", "token refresh")
    :ok

---

*Consult [api-reference.md](api-reference.md) for complete listing*