#825 jdp-2024-08: Optionally disable SQLWarnings

devdoc/jdp/jdp-2024-08-optionally-disable-sql-warnings.adoc

@@ -0,0 +1,45 @@
+= jdp-2024-08: Optionally disable ``SQLWarning``s
+
+== Status
+
+* Draft
+* Proposed for: Jaybird 6
+
+== Type
+
+* Feature-Specification
+
+== Context
+
+JDBC requires a number of situations where the driver diverges from specified behaviour to report that as warnings on the `Connection`, `Statement`, or `ResultSet`.
+In addition, it is expected that warnings reported by the server are reported in similar vein.
+
+Our experience is that users don't like ``SQLWarning``s, especially if tools log them or even report those warnings to the end-user, and will complain about it to us, instead of disabling said logging or complaining to the tool author.
+
+== Decision
+
+Jaybird will add a connection property and a system property to disable reporting of all ``SQLWarning``s.
+The property will also be added to data sources as an explicit setter.
+
+The connection property is called `reportSQLWarnings` with case-insensitive values:
+
+[horizontal]
+`ALL`:: Report all ``SQLWarning``s (the default)
+`NONE`:: Report no ``SQLWarning``s
+
+Invalid values will behave as `ALL`.
+`ALL` is the default because it is behaviour required by the JDBC Specification.
+
+The use of names instead of Boolean values leaves the option open to add a value `SERVER` to report server-generated warnings, but not driver-generated warnings.
+However, at this time we don't think that is needed (especially as Firebird has very few warnings to report).
+
+The system property is called `org.firebirdsql.jdbc.defaultReportSQLWarnings` with the same values.
+It will be dynamically checked when the connection configuration is created.
+
+The ignored warnings will not be logged.
+We may reconsider this in the future to log on `TRACE` for debugging purposes.
+
+== Consequences
+
+When a connection is created with `reportSQLWarning=NONE` (whether explicitly set, or set using the system property), the `getWarnings()` method of `Connection`, `Statement`, and `ResultSet` will never return a non-``null`` value.
+Implementation-wise, the `addWarning` methods of those classes will drop the warning and not register it on the object.