From 8fc6dfc99533f2196cd4e674c6358d1c4dbf96f5 Mon Sep 17 00:00:00 2001
From: Mark Rotteveel <mark@lawinegevaar.nl>
Date: Wed, 6 Nov 2024 15:37:20 +0100
Subject: [PATCH] Document https://github.com/FirebirdSQL/jaybird/issues/825

---
 .../connectionproperties.adoc                 |  6 +++++
 .../systemproperties/systemproperties.adoc    |  8 +++++++
 .../connection/reportsqlwarnings.adoc         | 22 +++++++++++++++++++
 3 files changed, 36 insertions(+)
 create mode 100644 src/docs/asciidoc/reference/connection/reportsqlwarnings.adoc

diff --git a/src/docs/asciidoc/appendices/connectionproperties/connectionproperties.adoc b/src/docs/asciidoc/appendices/connectionproperties/connectionproperties.adoc
index ae97e7b..d920f61 100644
--- a/src/docs/asciidoc/appendices/connectionproperties/connectionproperties.adoc
+++ b/src/docs/asciidoc/appendices/connectionproperties/connectionproperties.adoc
@@ -304,6 +304,12 @@ Boolean property.
 Attempts to create a database if it does not exist.
 See <<ref-create-database-if-not-exist>> for more information.
 
+a|`reportSQLWarnings`
+a|Jaybird specific property ([.since]_Jaybird 6_)
+Possible values (case-insensitive): `ALL` (default), `NONE`.
+Can be used to disable reporting of ``SQLWarning``s.
+See <<ref-report-sql-warnings>> for more information.
+
 |===
 
 In addition, Jaybird allows using arbitrary Database Parameters Block entries as connection properties (provided they are defined in Jaybird's `DpbItems` and `SpbItems` ([.since]_Jaybird 5_), or `ISCConstants` ([.until]_Jaybird 5_)).
diff --git a/src/docs/asciidoc/appendices/systemproperties/systemproperties.adoc b/src/docs/asciidoc/appendices/systemproperties/systemproperties.adoc
index 77528d2..8ecf3e1 100644
--- a/src/docs/asciidoc/appendices/systemproperties/systemproperties.adoc
+++ b/src/docs/asciidoc/appendices/systemproperties/systemproperties.adoc
@@ -59,6 +59,14 @@ The property values are read for each connect, so the value can be changed at an
 Configures the default value for the `enableProtocol` connection property.
 See <<ref-enable-protocol>> for more information.
 
+[#systemproperties-default-report-sql-warnings]
+
+=== Default `reportSQLWarnings` value
+
+`org.firebirdsql.jdbc.defaultReportSQLWarnings`::
+Configures the default value for the `reportSQLWarnings` connection property.
+See <<ref-report-sql-warnings>> for more information.
+
 [[systemproperties-wire-buffers]]
 === Wire protocol buffer sizes
 
diff --git a/src/docs/asciidoc/reference/connection/reportsqlwarnings.adoc b/src/docs/asciidoc/reference/connection/reportsqlwarnings.adoc
new file mode 100644
index 0000000..fb32021
--- /dev/null
+++ b/src/docs/asciidoc/reference/connection/reportsqlwarnings.adoc
@@ -0,0 +1,22 @@
+[#ref-report-sql-warnings]
+=== Reporting of ``SQLWarning``s
+
+The JDBC Specification requires that a JDBC driver reports a `SQLWarning` when it deviates from certain JDBC-specified behaviour (for example, changing a requested result set type), or when the server reports a warning.
+
+These warnings are reported on the `Connection`, `Statement`, or ``ResultSet``footnote:[In the current implementation, Jaybird never has warnings on `ResultSet`], and can be retrieved with `getWarnings()`.
+
+[.since]_Jaybird 6_ The connection property `reportSQLWarnings` can be used to disable the reporting of ``SQLWarning``s.
+
+This connection property supports the following values (case-insensitive):
+
+[horizontal.compact]
+`ALL`::
+(default) report all ``SQLWarning``s
+`NONE`::
+Do not report any ``SQLWarning``s
+
+Invalid values on the connection property will be rejected.
+
+The default value can be overridden with the system property `org.firebirdsql.jdbc.defaultReportSQLWarnings`.
+It supports the same values as connection property `reportSQLWarnings`.
+Invalid values of the system property are ignored.