JAVA-1227: Document "SELECT *" issue with prepared statement (#703)
diff --git a/changelog/README.md b/changelog/README.md
index 384204b..ec690e9 100644
--- a/changelog/README.md
+++ b/changelog/README.md
@@ -15,6 +15,7 @@
- [improvement] JAVA-1198: Document that BoundStatement is not thread-safe.
- [improvement] JAVA-1200: Upgrade LZ4 to 1.3.0.
- [bug] JAVA-1232: Fix NPE in IdempotenceAwareRetryPolicy.isIdempotent.
+- [improvement] JAVA-1227: Document "SELECT *" issue with prepared statement.
### 3.0.2
diff --git a/faq/README.md b/faq/README.md
index 0f92ec4..3ca02d0 100644
--- a/faq/README.md
+++ b/faq/README.md
@@ -88,6 +88,17 @@
```
+### Why do my 'SELECT *' `PreparedStatement`-based queries stop working after a schema change?
+
+Both the driver and Cassandra maintain a mapping of `PreparedStatement` queries to their
+metadata. When a change is made to a table, such as a column being added or dropped, there
+is currently no mechanism for Cassandra to invalidate the existing metadata. Because of this,
+the driver is not able to properly react to these changes and will improperly read rows after
+a schema change is made.
+
+See [Prepared statements](../manual/statements/prepared) for more information.
+
+
### Can I get the raw bytes of a text column?
If you need to access the raw bytes of a text column, call the
diff --git a/manual/statements/prepared/README.md b/manual/statements/prepared/README.md
index ece8bda..abc771d 100644
--- a/manual/statements/prepared/README.md
+++ b/manual/statements/prepared/README.md
@@ -241,9 +241,27 @@
specific situations; read each method's Javadoc for detailed
explanations.
+### Avoid preparing 'SELECT *' queries
+
+Both the driver and Cassandra maintain a mapping of `PreparedStatement` queries to their
+metadata. When a change is made to a table, such as a column being added or dropped, there
+is currently no mechanism for Cassandra to invalidate the existing metadata. Because of this,
+the driver is not able to properly react to these changes and will improperly read rows after
+a schema change is made.
+
+Therefore it is currently recommended to not create prepared statements
+for 'SELECT *' queries if you plan on making schema changes involving
+adding or dropping columns. Alternatively you should list all columns of interest
+in your statement, i.e.: `SELECT a, b, c FROM tbl`.
+
+This will be addressed in a future release of both Cassandra and the driver. Follow
+[CASSANDRA-10786] and [JAVA-1196] for more information.
+
[PreparedStatement]: http://docs.datastax.com/en/drivers/java/3.0/com/datastax/driver/core/PreparedStatement.html
[BoundStatement]: http://docs.datastax.com/en/drivers/java/3.0/com/datastax/driver/core/BoundStatement.html
[setPrepareOnAllHosts]: http://docs.datastax.com/en/drivers/java/3.0/com/datastax/driver/core/QueryOptions.html#setPrepareOnAllHosts-boolean-
[setReprepareOnUp]: http://docs.datastax.com/en/drivers/java/3.0/com/datastax/driver/core/QueryOptions.html#setReprepareOnUp-boolean-
[execute]: http://docs.datastax.com/en/drivers/java/3.0/com/datastax/driver/core/Session.html#execute-com.datastax.driver.core.Statement-
[executeAsync]: http://docs.datastax.com/en/drivers/java/3.0/com/datastax/driver/core/Session.html#executeAsync-com.datastax.driver.core.Statement-
+[CASSANDRA-10786]: https://issues.apache.org/jira/browse/CASSANDRA-10786
+[JAVA-1196]: https://datastax-oss.atlassian.net/browse/JAVA-1196
\ No newline at end of file
