#882 Added setters to FirebirdConnection to set search path

Author: mrotteveel

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

@@ -79,14 +79,15 @@ The following changes are made to Jaybird to support schemas when connecting to
 +
 On Firebird 5.0 and older, this will be silently ignored.
 * In internal queries in Jaybird, and fully qualified object names, we'll use the regular -- unquoted -- identifier `SYSTEM`, even though `SYSTEM` is a SQL:2023 reserved word, to preserve dialect 1 compatibility.
-* `Connection.getSchema()` will return the result of `select CURRENT_SCHEMA from SYSTEM.RDB$DATABASE`;
+* `Connection`
+** `getSchema()` will return the result of `select CURRENT_SCHEMA from SYSTEM.RDB$DATABASE`;
 the connection will not store this value
-* `Connection.setSchema(String)` will query the current search path, and if not previously called, it will prepend the schema name to the search path, otherwise it will _replace_ the previously prepended schema name.
+** `setSchema(String)` will query the current search path, and if not previously called, it will prepend the schema name to the search path, otherwise it will _replace_ the previously prepended schema name.
 The schema name is stored _only_ for this replacement operation (i.e. it will not be returned by `getSchema`!)
-** The name must match exactly as is stored in the metadata (it is always case-sensitive!)
-** Jaybird will take care of quoting, and will always quote on dialect 3
-** Existence of the schema is **not** checked, so it is possible the current schema does not change with this operation, as `CURRENT_SCHEMA` reports the first _valid_ schema
-** JDBC specifies that "`__Calling ``setSchema`` has no effect on previously created or prepared Statement objects.__`";
+*** The name must match exactly as is stored in the metadata (it is always case-sensitive!)
+*** Jaybird will take care of quoting, and will always quote on dialect 3
+*** Existence of the schema is **not** checked, so it is possible the current schema does not change with this operation, as `CURRENT_SCHEMA` reports the first _valid_ schema
+*** JDBC specifies that "`__Calling ``setSchema`` has no effect on previously created or prepared Statement objects.__`";
 Jaybird cannot honour this requirement for plain `Statement`, as schema resolution is on prepare time (which for plain `Statement` is on execute), and not always for `CallableStatement`, as the implementation may delay actual prepare until execution, though we do try to identify the procedure when the callable statement is created and use that to fully-qualify the procedure.
 * Request `isc_info_sql_relation_schema` after preparing a query, record it in `FieldDescriptor`, and return it were relevant for JDBC (e.g. `ResultSetMetaData.getSchemaName(int)`)
 ** For Firebird 5.0 and older, we need to ensure that JDBC methods continue to report the correct value (i.e. `""` for schema-less objects)
@@ -102,6 +103,7 @@ We considered adding a column that lists the schema(s) that contain the package
 * `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
+** Added methods `setSearchPath(String)` and `setSearchPathList` with overloads `(String...)` and `(List<String>)` to set the search path.
 * `FBCallableStatement`
 ** On creating the instance, the stored procedure is parsed and identified in the database metadata, including selectability, unless `ignoreProcedureType` is `true`
 *** Parsing of callable statements is changed to be able to identify schema, package and procedure name, including scope specifiers

src/docs/asciidoc/release_notes.adoc

@@ -560,6 +560,8 @@ we recommend to always use `null` for `catalog`
 * `FirebirdConnection`/`FBConnection`
 ** 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>)` where added 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)`)

src/main/org/firebirdsql/jdbc/FBConnection.java

@@ -23,6 +23,7 @@
 import org.firebirdsql.jaybird.props.DatabaseConnectionProperties;
 import org.firebirdsql.jaybird.props.PropertyConstants;
 import org.firebirdsql.jaybird.util.SQLExceptionChainBuilder;
+import org.firebirdsql.jaybird.util.SearchPathHelper;
 import org.firebirdsql.jaybird.xca.FBLocalTransaction;
 import org.firebirdsql.jaybird.xca.FBManagedConnection;
 import org.firebirdsql.jdbc.InternalTransactionCoordinator.MetaDataTransactionCoordinator;
@@ -1118,11 +1119,21 @@ public final String getSearchPath() throws SQLException {
         return getSchemaInfo().searchPath();
     }
 
+    @Override
+    public final void setSearchPath(String searchPath) throws SQLException {
+        getSchemaChanger().setSearchPath(searchPath);
+    }
+
     @Override
     public final List<String> getSearchPathList() throws SQLException {
         return getSchemaInfo().toSearchPathList();
     }
 
+    @Override
+    public void setSearchPathList(List<String> schemas) throws SQLException {
+        getSchemaChanger().setSearchPath(SearchPathHelper.toSearchPath(schemas, getQuoteStrategy()));
+    }
+
     private SchemaChanger.SchemaInfo getSchemaInfo() throws SQLException {
         try (var ignored = withLock()) {
             return getSchemaChanger().getCurrentSchemaInfo();

src/main/org/firebirdsql/jdbc/FirebirdConnection.java

@@ -11,6 +11,7 @@
 import java.sql.Blob;
 import java.sql.Connection;
 import java.sql.SQLException;
+import java.util.Arrays;
 import java.util.List;
 
 /**
@@ -128,24 +129,79 @@ public interface FirebirdConnection extends Connection {
      */
     void resetKnownClientInfoProperties();
 
+    /**
+     * Sets the search path as if executing {@code SET SEARCH_PATH TO ...}.
+     *
+     * @param searchPath
+     *         comma-separated search path (names must be correctly quoted — if needed)
+     * @throws java.sql.SQLFeatureNotSupportedException
+     *         if the server does not support schemas (Firebird 5.0 or older)
+     * @throws SQLException
+     *         if {@code schemas} is null or blank, or for database access errors
+     * @see #getSearchPath()
+     * @see #setSearchPathList(List)
+     * @see #setSchema(String)
+     * @since 7
+     */
+    void setSearchPath(String searchPath) throws SQLException;
+
     /**
      * Returns the schema search path.
      *
      * @return comma-separated list of quoted schema names of the search path, or {@code null} if schemas are not
      * supported
      * @throws SQLException
      *         if the connections is closed, or for database access errors
+     * @see #setSearchPath(String)
      * @see #getSearchPathList()
      * @since 7
      */
     String getSearchPath() throws SQLException;
 
+    /**
+     * Sets the search path as if executing {@code SET SEARCH_PATH TO ...}.
+     *
+     * @param schemas
+     *         schemas to set as search path (names must be unquoted)
+     * @throws java.sql.SQLFeatureNotSupportedException
+     *         if the server does not support schemas (Firebird 5.0 or older)
+     * @throws SQLException
+     *         if {@code schemas} is empty, or for database access errors
+     * @see #setSearchPathList(List)
+     * @see #getSearchPathList()
+     * @see #setSearchPath(String)
+     * @see #setSchema(String)
+     * @since 7
+     */
+    default void setSearchPathList(String... schemas) throws SQLException {
+        setSearchPathList(Arrays.asList(schemas));
+    }
+
+    /**
+     * Sets the search path as if executing {@code SET SEARCH_PATH TO ...}.
+     *
+     * @param schemas
+     *         schemas to set as search path (names must be unquoted)
+     * @throws java.sql.SQLFeatureNotSupportedException
+     *         if the server does not support schemas (Firebird 5.0 or older)
+     * @throws SQLException
+     *         if {@code schemas} is empty, or for database access errors
+     * @see #setSearchPathList(List)
+     * @see #getSearchPathList()
+     * @see #setSearchPath(String)
+     * @see #setSchema(String)
+     * @since 7
+     */
+    void setSearchPathList(List<String> schemas) throws SQLException;
+
     /**
      * Returns the schema search path as a list of unquoted schema names.
      *
      * @return list of unquoted schema names, or an empty list if schemas are not supported
      * @throws SQLException
      *         if the connection is closed, or for database access errors
+     * @see #setSearchPathList(String...)
+     * @see #setSearchPathList(List)
      * @see #getSearchPath()
      * @since 7
      */

src/main/org/firebirdsql/jdbc/SchemaChanger.java

@@ -13,6 +13,7 @@
 import java.util.List;
 import java.util.Objects;
 
+import static org.firebirdsql.jaybird.util.StringUtils.isNullOrBlank;
 import static org.firebirdsql.util.FirebirdSupportInfo.supportInfoFor;
 
 /**
@@ -41,9 +42,20 @@ sealed abstract class SchemaChanger {
      * @throws SQLException
      *         for database access errors, or if {@code schema} is {@code null} or blank <em>if</em> schemas are
      *         supported
+     * @see #setSearchPath(String)
      */
     abstract void setSchema(String schema) throws SQLException;
 
+    /**
+     * Sets the search path, overriding any previously set current schema or search path.
+     *
+     * @param searchPath new search path to set (non-{@code null} and not blank, comma-separate, and quoted if needed)
+     * @throws java.sql.SQLFeatureNotSupportedException if schemas are not supported (Firebird 5.0 and older)
+     * @throws SQLException for database access errors, or if {@code searchPath} is {@code null} or blank
+     * @see #setSchema(String)
+     */
+    abstract void setSearchPath(String searchPath) throws SQLException;
+
     /**
      * Current schema and search path.
      * <p>
@@ -134,7 +146,7 @@ SchemaInfo getCurrentSchemaInfo() throws SQLException {
 
         @Override
         void setSchema(String schema) throws SQLException {
-            if (schema == null || schema.isBlank()) {
+            if (isNullOrBlank(schema)) {
                 // TODO externalize?
                 throw new SQLDataException("schema must be non-null and not blank",
                         SQLStateConstants.SQL_STATE_INVALID_USE_NULL);
@@ -166,14 +178,30 @@ void setSchema(String schema) throws SQLException {
                     newSearchPath.addAll(originalSearchPath);
                 }
 
-                //noinspection SqlSourceToSinkFlow
-                getStatement().execute("set search_path to "
-                        + SearchPathHelper.toSearchPath(newSearchPath, connection.getQuoteStrategy()));
+                setSearchPath0(SearchPathHelper.toSearchPath(newSearchPath, connection.getQuoteStrategy()));
                 schemaInfoAfterLastChange = getCurrentSchemaInfo();
                 lastSearchPath = List.copyOf(newSearchPath);
                 lastSchemaChange = schema;
             }
         }
+
+        @Override
+        void setSearchPath(String searchPath) throws SQLException {
+            if (isNullOrBlank(searchPath)) {
+                // TODO externalize?
+                throw new SQLDataException("search path must have at least one schema",
+                        SQLStateConstants.SQL_STATE_INVALID_USE_NULL);
+            }
+            setSearchPath0(searchPath);
+            schemaInfoAfterLastChange = getCurrentSchemaInfo();
+            lastSearchPath = schemaInfoAfterLastChange.toSearchPathList();
+            // given this change was no explicit call to setSchema, clear it
+            lastSchemaChange = null;
+        }
+
+        private void setSearchPath0(String searchPath) throws SQLException {
+            getStatement().execute("set search_path to " + searchPath);
+        }
     }
 
     /**
@@ -188,6 +216,11 @@ void setSchema(String schema) {
             // do nothing (not even validate the name)
         }
 
+        @Override
+        void setSearchPath(String searchPath) throws SQLException {
+            throw new FBDriverNotCapableException("Schema support required for setSearchPath");
+        }
+
         @Override
         SchemaInfo getCurrentSchemaInfo() {
             return SchemaInfo.NULL_INSTANCE;

src/test/org/firebirdsql/jdbc/FBConnectionSchemaTest.java

@@ -4,6 +4,7 @@
 
 import org.firebirdsql.common.extension.UsesDatabaseExtension;
 import org.firebirdsql.common.extension.UsesDatabaseExtension.UsesDatabaseForAll;
+import org.firebirdsql.common.matchers.SQLExceptionMatchers;
 import org.firebirdsql.jaybird.props.PropertyNames;
 import org.firebirdsql.jaybird.util.SearchPathHelper;
 import org.junit.jupiter.api.Test;
@@ -17,15 +18,18 @@
 import java.sql.ResultSetMetaData;
 import java.sql.SQLDataException;
 import java.sql.SQLException;
+import java.sql.SQLFeatureNotSupportedException;
 import java.util.List;
 
 import static org.firebirdsql.common.FBTestProperties.getConnectionViaDriverManager;
 import static org.firebirdsql.common.FBTestProperties.getDefaultSupportInfo;
 import static org.firebirdsql.common.FbAssumptions.assumeNoSchemaSupport;
 import static org.firebirdsql.common.FbAssumptions.assumeSchemaSupport;
+import static org.firebirdsql.common.matchers.SQLExceptionMatchers.message;
 import static org.hamcrest.MatcherAssert.assertThat;
 import static org.hamcrest.Matchers.empty;
 import static org.hamcrest.Matchers.is;
+import static org.hamcrest.Matchers.startsWith;
 import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNull;
@@ -203,6 +207,97 @@ void connectionSearchPath(String searchPath, String expectedSchema, String expec
         }
     }
 
+    @Test
+    void setSearchPath_noSchemaSupport_throwsFBDriverNotCapable() throws Exception {
+        assumeNoSchemaSupport();
+        try (var connection = getConnectionViaDriverManager()) {
+            assertThrows(FBDriverNotCapableException.class, () -> connection.setSearchPath("SYSTEM"));
+        }
+    }
+
+    @ParameterizedTest
+    @NullAndEmptySource
+    @ValueSource(strings = { " ", "  " })
+    void setSearchPath_schemaSupport_nullOrBlank_notAccepted(String searchPath) throws Exception {
+        assumeSchemaSupport();
+        try (var connection = getConnectionViaDriverManager()) {
+            var exception = assertThrows(SQLDataException.class, () -> connection.setSearchPath(searchPath));
+            assertThat(exception, message(startsWith("search path must have at least one schema")));
+        }
+    }
+
+    @ParameterizedTest
+    @CsvSource(useHeadersInDisplayName = true, textBlock = """
+            searchPath,       expectedSearchPath
+            PUBLIC,           '"PUBLIC", "SYSTEM"'
+            'PUBLIC, SYSTEM', '"PUBLIC", "SYSTEM"'
+            public,           '"PUBLIC", "SYSTEM"'
+            "public",         '"public", "SYSTEM"'
+            SCHEMA_1,         '"SCHEMA_1", "SYSTEM"'
+            "case_sensitive", '"case_sensitive", "SYSTEM"'
+            # NOTE Unquoted!
+            case_sensitive,   '"CASE_SENSITIVE", "SYSTEM"'
+            'SCHEMA_1, "case_sensitive", SYSTEM, PUBLIC', '"SCHEMA_1", "case_sensitive", "SYSTEM", "PUBLIC"'
+            """)
+    void setSearchPath_schemaSupport(String searchPath, String expectedSearchPath) throws Exception {
+        assumeSchemaSupport();
+        try (var connection = getConnectionViaDriverManager()) {
+            connection.setSearchPath(searchPath);
+
+            assertEquals(expectedSearchPath, connection.getSearchPath(), "searchPath");
+        }
+    }
+
+    @Test
+    void setSearchPathList_stringArr_noSchemaSupport_throwsFBDriverNotCapable() throws Exception {
+        assumeNoSchemaSupport();
+        try (var connection = getConnectionViaDriverManager()) {
+            assertThrows(SQLFeatureNotSupportedException.class, () -> connection.setSearchPathList("SYSTEM"));
+        }
+    }
+
+    // As setSearchPathList(String...) goes through setSearchPathList(List<String>), we only tests through the latter
+
+    @Test
+    void setSearchPathList_stringList_noSchemaSupport_throwsFBDriverNotCapable() throws Exception {
+        assumeNoSchemaSupport();
+        try (var connection = getConnectionViaDriverManager()) {
+            assertThrows(SQLFeatureNotSupportedException.class, () -> connection.setSearchPathList(List.of("SYSTEM")));
+        }
+    }
+
+    @Test
+    void setSearchPathList_stringList_schemaSupport_empty_notAccepted() throws Exception {
+        assumeSchemaSupport();
+        try (var connection = getConnectionViaDriverManager()) {
+            var exception = assertThrows(SQLDataException.class, () -> connection.setSearchPathList(List.of()));
+            assertThat(exception, message(startsWith("search path must have at least one schema")));
+        }
+    }
+
+    @ParameterizedTest
+    @CsvSource(useHeadersInDisplayName = true, textBlock = """
+            searchPath,       expectedSearchPath
+            PUBLIC,           '"PUBLIC", "SYSTEM"'
+            'PUBLIC, SYSTEM', '"PUBLIC", "SYSTEM"'
+            public,           '"PUBLIC", "SYSTEM"'
+            "public",         '"public", "SYSTEM"'
+            SCHEMA_1,         '"SCHEMA_1", "SYSTEM"'
+            "case_sensitive", '"case_sensitive", "SYSTEM"'
+            # NOTE Unquoted!
+            case_sensitive,   '"CASE_SENSITIVE", "SYSTEM"'
+            'SCHEMA_1, "case_sensitive", SYSTEM, PUBLIC', '"SCHEMA_1", "case_sensitive", "SYSTEM", "PUBLIC"'
+            """)
+    void setSearchPathList_stringList_schemaSupport(String searchPath, String expectedSearchPath) throws Exception {
+        assumeSchemaSupport();
+        try (var connection = getConnectionViaDriverManager()) {
+            List<String> searchPathList = SearchPathHelper.parseSearchPath(searchPath);
+            connection.setSearchPathList(searchPathList);
+
+            assertEquals(expectedSearchPath, connection.getSearchPath(), "searchPath");
+        }
+    }
+
     private static void checkSchemaResolution(Connection connection, String expectedSchema) throws SQLException {
         try (var pstmt = connection.prepareStatement("select * from TABLE_ONE")) {
             ResultSetMetaData rsmd = pstmt.getMetaData();