diff --git a/UPGRADE.md b/UPGRADE.md
index ea130f77144..c6765ebf1bc 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -3,6 +3,8 @@
 ## Deprecations in the wrapper `Connection` class
 
 1. The `executeUpdate()` method has been deprecated in favor of `executeStatement()`. 
+2. The `query()` method has been deprecated in favor of `executeQuery()`. 
+3. The `exec()` method has been deprecated in favor of `executeStatement()`. 
 
 ## PDO-related classes outside of the PDO namespace are deprecated
 
diff --git a/lib/Doctrine/DBAL/Connection.php b/lib/Doctrine/DBAL/Connection.php
index 3aa16f2b20b..cd4c33109eb 100644
--- a/lib/Doctrine/DBAL/Connection.php
+++ b/lib/Doctrine/DBAL/Connection.php
@@ -1249,6 +1249,8 @@ public function project($query, array $params, Closure $function)
     /**
      * Executes an SQL statement, returning a result set as a Statement object.
      *
+     * @deprecated Use {@link executeQuery()} instead.
+     *
      * @return \Doctrine\DBAL\Driver\Statement
      *
      * @throws DBALException
@@ -1360,6 +1362,8 @@ public function executeStatement($sql, array $params = [], array $types = [])
     /**
      * Executes an SQL statement and return the number of affected rows.
      *
+     * @deprecated Use {@link executeStatement()} instead.
+     *
      * @param string $statement
      *
      * @return int The number of affected rows.