Finalize jdp-2025-06

Author: mrotteveel

devdoc/jdp/jdp-2025-06-schema-support.adoc

@@ -5,8 +5,8 @@
 
 == Status
 
-* Draft
-* Proposed for: Jaybird 7, potential partial backport to Jaybird 5
+* Published: 2025-11-04
+* Implemented in: Jaybird 7
 
 == Type
 
@@ -52,11 +52,6 @@ JDBC defines various methods, parameters, and return values or result set column
 
 Jaybird 5 is the "`long-term support`" version for Java 8.
 
-[NOTE]
-====
-This document is in flux, and will be updated during implementation of the feature.
-====
-
 == Decision
 
 Jaybird 7 will implement schema support for Firebird 6.0.
@@ -67,8 +62,8 @@ Further details can be found in <<consequences>>.
 Schema support will _not_ be backported to Jaybird 6 as the required changes are simply too large.
 It would mean that Jaybird 6 would contain most of Jaybird 7, and upgrading to a -- theoretical -- Jaybird 6.1 would have similar risks and compatibility issues as upgrading to Jaybird 7.
 
-Decision on a (partial) backport to Jaybird 5 -- as the "`long-term support`" version for Java 8 -- is still pending (e.g. as a Jaybird 5.1.x), and may be the subject of a separate JDP.
-We might only do that on demand and/or when someone is willing to sponsor the work.
+Decision on a (partial) backport to Jaybird 5 -- as the "`long-term support`" version for Java 8 -- is pending (e.g. as a Jaybird 5.1.x), and if so, will be the subject of a separate JDP.
+We will only do that on demand and if someone is willing to sponsor the work.
 
 [#consequences]
 == Consequences
@@ -97,9 +92,11 @@ Jaybird cannot honour this requirement for plain `Statement`, as schema resoluti
 ** Include schema names in joins to ensure matching the right objects
 ** Allow searching for schema or schema pattern as specified in JDBC, or were needed for internal metadata queries
 ** `getCatalogs`;
-it is not possible to identify the schema(s) within the confines of JDBC.
+we currently use this to report package names if `useCatalogAsPackage=true`.
+It is not possible to identify the schema(s) of a package within the confines of JDBC.
 +
 We considered adding a column that lists the schema(s) that contain the package name, but we don't think it will see use in practice.
+If there is demand, this decision may be revisited.
 * `FirebirdConnection`
 ** Added method `String getSearchPath()` to obtain the search path as reported by `RBB$GET_CONTEXT('SYSTEM', 'SEARCH_PATH')`, or `null` if schemas are not supported
 ** Added method `List<String> getSearchPathList()` to obtain the search path as a list of unquoted object names, or empty list if schemas are not supported
@@ -111,10 +108,10 @@ We considered adding a column that lists the schema(s) that contain the package
 this fulfills the JDBC requirements that a `CallableStatement` is not sensitive to current schema changes, but only *if* Jaybird is able to identify the procedure, behaviour is undefined if the procedure was not found.
 ** The API of `StoredProcedureMetaData` (internal API) is changed to not report selectability, but to update the `FBProcedureCall` instance with selectability and other information, like identified schema and/or package.
 ** For qualified *and* unambiguous procedure reference, the selectability is cached *per connection*, for unqualified or ambiguous procedure reference, the lookup is performed on each `Connection.prepareCall`, to account for search path changes
-** Support for packages was missing in the handling of callable statements, and is added, also for older versions
+** Support for packages was missing in the handling of callable statements, and is added, also for older Firebird versions
 * Effects for management API
 ** `StatisticsManager`
-*** `getTableStatistics` received an overload to also accept a list of schemas (`sts_schema`)
+*** `getTableStatistics` received an overload to also accept a collection of schemas (`sts_schema`)
 ** `FBTableStatisticsManager`/`TableStatistics`
 *** Internally `ObjectReference` is used for the table instead of a String
 *** The key of the map returned by `getTableStatistics()` is a qualified table reference (i.e. `{<table-name> | <quoted-schema>.<quoted-table-name>}`.
@@ -124,7 +121,7 @@ For schemaless tables, the unquoted table name is used as the key for backwards
 **** `tableReference()` with the qualified table reference (i.e. `[<quoted-schema>.]<quoted-table-name>` (contrary to the key of getTableStatistics, it's always quoted!))
 * TODO: Add information to Jaybird manual
 
-Note to self: use `// TODO Add schema support` in places that you identify need to get/improve schema support, while working on schema support elsewhere
+// Note to self: use `// TODO Add schema support` in places that you identify need to get/improve schema support, while working on schema support elsewhere
 
 [appendix]
 == License Notice

src/docs/asciidoc/release_notes.adoc

@@ -529,7 +529,6 @@ If `SYSTEM` is not included, the server will automatically add it as the last sc
 use `null` or -- `schemaPattern` only -- `"%"` to match all schemas
 ** `getCatalogs` -- when `useCatalogAsPackage=true` -- returns all (distinct) package names over all schemas.
 Within the limitations and specification of the JDBC API, this method cannot be used to find out which schema(s) contain a specific package name.
-// TODO Maybe add a custom column with a list of schema names?
 ** `getColumnPrivileges` and `getTablePrivileges` received an additional column, `JB_GRANTEE_SCHEMA`, which is non-``null`` for grantees that are schema-bound (e.g. procedures).
 +
 As this is a non-standard column, we recommend to always retrieve it by name.
@@ -559,15 +558,22 @@ we recommend to always use `null` for `catalog`
 * `ResultSetMetaData`
 ** `getSchemaName` reports the schema if the column is backed by a table, otherwise empty string (`""`)
 * `FirebirdConnection`/`FBConnection`
+** `setSchema` will modify the search path by prepending the specified schema, or -- if `setSchema` was called previously -- replacing the previous value set.
++
+The schema is not checked for existence, and setting one will not result in an exception, see also note about `getSchema` below.
+** `getSchema()` reports the value of `CURRENT_SCHEMA`, which is the first valid (i.e. existing) schema on the search path.
++
+The value reported can change if a previously missing schema is created in the database.
 ** Added method `String getSearchPath()` to obtain the search path as reported by `RBB$GET_CONTEXT('SYSTEM', 'SEARCH_PATH')`, or `null` if schemas are not supported
 ** Added method `List<String> getSearchPatList()` to obtain the search path as a list of unquoted object names, or empty list if schemas are not supported
 ** Added methods `setSearchPath(String)` and `setSearchPathList(String...)/(List<String>)` to set the search path;
 these methods throw `SQLFeatureNotSupportedException` if schemas are not supported.
 * `StatisticsManager`
 ** `getTableStatistics`
 *** `getTableStatistics(String[] tableNames)` was changed to accept varargs (`getTableStatistics(String... tableNames)`)
-*** Added overload `getTableStatistics(List<String> tableNames)` with same behaviour as `getTableStatistics(String... tableNames)`
-*** Added overload `getTableStatistics(List<String> schemas, List<String> tableNames)` -- if `schemas` is non-empty, on Firebird 6.0 and higher, it will restrict the search for tables to the specified schemas
+*** Added overload `getTableStatistics(Collection<String> tableNames)` with same behaviour as `getTableStatistics(String... tableNames)`
+*** Added overload `getTableStatistics(Collection<String> schemas, Collection<String> tableNames)` -- if `schemas` is non-empty, on Firebird 6.0 and higher, it will restrict the search for tables to the specified schemas;
+if `tableNames` is empty, and `schemas` is not, only the tables of the specified schemas will be reported
 * `FBTableStatisticsManager` (experimental feature)
 ** For schema-bound tables, the key of the map returned by `getTableStatistics()` is a fully qualified and quoted table reference (i.e. `<quoted-schema>.<quoted-table-name>`).
 For schemaless tables (Firebird 5.0 and older, or tables that were not found), the key is still the unquoted `<table-name>`.