EMQX Cloud V5 to V6 Upgrade Guide

As an EMQX Dedicated deployment user, you can upgrade EMQX from V5 to V6. To check the current EMQX version, open the deployment details page and click Settings to view the deployment information.

EMQX V6 retains the core architecture and usage model of V5 while introducing or enhancing Namespaces, Log Trace, Event History, BigQuery data integration, Snowflake Streaming data integration, and MQTT Source capabilities. For more information, see What's New.

Availability

EMQX V6 is available only for Dedicated and Dedicated Flex Broker deployments. Serverless deployments do not support EMQX version selection.

Before You Upgrade

1. Make sure automatic reconnection is enabled on your clients and prepare for brief connection interruptions during the upgrade.
2. Record key business baselines before the upgrade, including the number of connected clients, message publish and delivery rates, authentication success rate, and the status of rules and data integrations. Use these values for post-upgrade comparison.
3. Before the upgrade, our SRE team will check the deployment status and special configurations. If anything could affect the upgrade, we will contact you in advance.

Data Migration and Retained Configuration

The following configuration and data will be retained during the upgrade:

• MQTT endpoints and ports
• Authentication and authorization configuration
• Data integration configuration, including connectors, rules, Sources, and Sinks
• TLS certificate information
• Retained messages
• Network management configuration, including NAT Gateway, Internal Endpoint, PrivateLink, and VPC Peering

Upgrading from V5 to V6 does not require the extensive API, authentication and authorization, or data integration architecture compatibility work required for a V4 upgrade. Special parameters configured through support tickets remain subject to the SRE team's pre-upgrade assessment.

Upgrade Impact

1. The upgrade is expected to take 15–25 minutes with no service downtime.
2. A two-hour maintenance window will be created for the upgrade. Service unavailability caused by the upgrade during this window is excluded from SLA availability calculations.
3. Clients may experience two or three brief disconnections during the upgrade. If automatic reconnection is enabled on the devices, normal use will not be affected.
4. Please note: If clean session is set to false, existing sessions will be discarded after the upgrade. If sessions must be retained, contact us in advance.

Post-Upgrade Process

Post-Upgrade Validation

1. After the upgrade, the EMQX Cloud SRE team will check the deployment logs and metrics.
2. Validate the deployment against the business baselines recorded before the upgrade, focusing on the following checks:
   • Clients reconnect automatically
   • Client authentication and authorization operate correctly
   • Subscriptions are restored and message publishing and delivery operate correctly
   • Rules, connectors, Sources, and Sinks operate correctly
   • TLS connections and custom certificates operate correctly
   • Monitoring metrics and alerts match expectations
3. If you identify any issue, contact us immediately for assistance.

Rollback

• A 24-hour rollback window is available before you confirm the upgrade. During this window, the deployment can be rolled back from V6 to V5.
• Rollback is expected to take 15–25 minutes with no service downtime.
• All client connections will be disconnected one or two times during rollback.
• Persistent session state cannot be retained. Clients will create new sessions after reconnecting.

V6 Core Features

V6-Specific Capabilities

Note

The following capabilities are available only for Dedicated and Dedicated Flex deployments that support EMQX V6. Actual availability depends on the V6 minor version, region, and options displayed in the console.

V6-Specific Capability	Practical Value
Namespaces	Provide resource and permission isolation for multi-tenant scenarios. Rules, connectors, actions, and other resources can be organized by tenant, team, or business unit, reducing cross-tenant impact and simplifying operations in a shared cluster.
Log Trace	Collect debug logs for a specific client, topic, client IP address, or rule ID without enabling verbose logging for the entire deployment. This is useful for targeted troubleshooting.
Event History	Retain recent connection, authentication, and subscription events to diagnose connection failures, unexpected disconnections, authentication failures, and subscriptions that do not take effect.
BigQuery Data Integration	Write MQTT data to BigQuery through the rule engine and a BigQuery Sink for SQL analytics and reporting.
Snowflake Streaming Data Integration	Write data to Snowflake tables with low latency through the rule engine and a Snowflake Streaming Sink.

Namespaces

Namespaces enhance multi-tenant management and resource isolation. Administrators can divide resource scopes by tenant, department, or business unit and independently manage rules, connectors, and actions within each namespace. When multiple teams or customers share one deployment, namespaces reduce accidental resource changes and cross-tenant impact.

Log Trace

Log Trace allows users to collect debug-level logs from the console for a specific MQTT client, topic, client IP address, or rule ID. Compared with enabling verbose logging for the entire deployment, it provides a more precise scope with less impact on normal workloads and is suitable for reproducing and diagnosing issues involving a specific client, topic, or rule-processing path.

Event History

Event History records recent client connection, authentication, and subscription events. It can be used to investigate:

• Client connection failures or unexpected disconnections
• Client authentication failures
• Subscriptions that fail to be created or do not take effect
• Connection and subscription timelines

BigQuery Data Integration

The rule engine filters and processes MQTT messages before a BigQuery Sink writes them to Google BigQuery. This integration is suitable for SQL analytics, data warehousing, and reporting on large volumes of IoT data.

Snowflake Streaming Data Integration

The Snowflake Streaming Sink writes MQTT data to Snowflake tables with low latency. It is suitable for near-real-time data ingestion, analytics, and business insights.

MQTT Source Enhancements

The V6 MQTT Source supports shared subscription topics to reduce duplicate messages. It also supports MQTT 5.0 subscription options such as No Local and Retain As Published, providing greater flexibility when bridging data from a remote MQTT service.

Upgrade Confirmation

Confirm the upgrade window and make sure the relevant business and operations personnel remain available during the upgrade. We will provide technical support throughout the process to help ensure a successful upgrade.