diff --git a/source/upgrade.txt b/source/upgrade.txt
index aba02f3cc..ab6467a54 100644
--- a/source/upgrade.txt
+++ b/source/upgrade.txt
@@ -151,6 +151,24 @@ Version 5.0 Breaking Changes
   responding in the same way as ``Decimal128`` values. In particular,
   ``BsonDecimal128.isNumber()`` now returns ``true``, and
   ``BsonDecimal128.asNumber()`` returns the equivalent ``BsonNumber``.
+  
+- This driver version removes the `ServerAddress <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ServerAddress.html>`__
+  methods ``getSocketAddress()`` and ``getSocketAddresses()``.
+
+  Instead of ``getSocketAddress()``, use the ``getByName()`` instance
+  method of ``java.net.InetAddress``.
+
+  Instead of ``getSocketAddresses()``, use the ``getAllByName()`` instance
+  method of ``java.net.InetAddress``.
+
+- This driver version removes the `UnixServerAddress <{+api+}/apidocs/mongodb-driver-core/com/mongodb/UnixServerAddress.html>`__
+  methods ``getSocketAddress()`` and ``getUnixSocketAddress()``.
+
+  Instead of ``getUnixSocketAddress()``, construct an instance of
+  ``jnr.unixsocket.UnixSocketAddress``. Pass the full path of the UNIX
+  socket file to the constructor. By default, MongoDB creates a UNIX
+  socket file located at ``"/tmp/mongodb-27017.sock"``. To learn more
+  about the ``UnixSocketAddress``, see the `UnixSocketAddress <https://www.javadoc.io/doc/com.github.jnr/jnr-unixsocket/latest/jnr/unixsocket/UnixSocketAddress.html>`__ API documentation.
 
 .. _java-breaking-changes-v4.8: