fix: repair Oracle metadata introspection

Author: cccadet

docker/test-dbs/integration-test.ts

@@ -48,6 +48,7 @@ const RPC_AUTH_HEADERS = {
 };
 
 const { startServer } = await import("@omni-sql/backend");
+const { closeBackendResources } = await import("../../packages/backend/src/handlers.ts");
 
 const SIDECAR_HEALTH_URL = "http://127.0.0.1:41921/health";
 const SIDECAR_SCOPE_URL = "http://127.0.0.1:41921/scope/resolve";
@@ -208,6 +209,7 @@ describe("Integration — pipeline completo via JSON-RPC", () => {
     await new Promise<void>((resolve, reject) =>
       server.close((err) => (err ? reject(err) : resolve())),
     );
+    await closeBackendResources();
     fs.rmSync(tmpDir, { recursive: true, force: true });
   });
 

docker/test-dbs/smoke-test.ts

@@ -55,6 +55,7 @@ const TARGETS: Record<string, Target> = {
       dialect: "sqlserver",
       endpoint: "127.0.0.1:1433/omni_test",
       user: "sa",
+      options: { trustServerCertificate: true, serverName: "localhost" },
     },
     password: "Omni!2024",
   },
@@ -153,7 +154,7 @@ for (const [key, target] of targets) {
       const pub = findSchema(schemas);
 
       const tables = adapter.listTables(pub.name);
-      const tableNames = tables.map((t) => t.name);
+      const tableNames = tables.map((t) => t.name.toLowerCase());
       assert.ok(tableNames.includes("customers"), `customers missing, got: ${tableNames}`);
       assert.ok(tableNames.includes("orders"), `orders missing, got: ${tableNames}`);
       assert.ok(tableNames.includes("products"), `products missing, got: ${tableNames}`);
@@ -163,7 +164,7 @@ for (const [key, target] of targets) {
     it("listColumns (customers)", () => {
       const schemas = adapter.listSchemas();
       const pub = findSchema(schemas);
-      const cols = adapter.listColumns(pub.name, "customers");
+      const cols = adapter.listColumns(pub.name, key === "oracle" ? "CUSTOMERS" : "customers");
       assert.ok(cols.length >= 4, `expected 4+ columns, got ${cols.length}`);
 
       const idCol = cols.find((c) => c.name === "id" || c.name === "ID");
@@ -177,7 +178,7 @@ for (const [key, target] of targets) {
     it("listColumns (orders with FK)", () => {
       const schemas = adapter.listSchemas();
       const pub = findSchema(schemas);
-      const cols = adapter.listColumns(pub.name, "orders");
+      const cols = adapter.listColumns(pub.name, key === "oracle" ? "ORDERS" : "orders");
       const fkCol = cols.find(
         (c) => c.name === "customer_id" || c.name === "CUSTOMER_ID",
       );

docs/releases/v0.2.12.md

@@ -0,0 +1,13 @@
+## 0.2.12 (2026-09-17)
+
+### Bug Fixes
+
+- **Oracle metadata:** qualify catalog columns in the joined column query so introspection succeeds without ambiguous-column errors.
+- **Oracle errors:** show structured `ORA-xxxxx` errors when schema discovery or metadata introspection fails.
+
+### Tests
+
+- Exercise PostgreSQL, MySQL, SQL Server, Oracle, and generic JDBC through the Docker integration suite; fix SQL Server TLS and Oracle identifier expectations in the smoke tests.
+- Close backend resources before removing the integration test database on Windows.
+
+**Full Changelog:** [`v0.2.11...v0.2.12`](https://github.com/cccadet/omni-sql/compare/v0.2.11...v0.2.12)

packages/adapters-oracle/src/index.test.ts

@@ -99,9 +99,12 @@ test("introspectSchemas ignora FK incompleta e preserva FK válida", async () =>
     execute: async (sql: string) => {
       if (sql.includes("FROM all_tables")) {
         return { rows: [{ table_schema: "APP", table_name: "CHILD", table_type: "TABLE" }] };
-      }
-      if (sql.includes("FROM all_tab_columns")) {
-        return {
+      }
+      if (sql.includes("FROM all_tab_columns")) {
+        assert.match(sql, /c\.owner AS "table_schema"/);
+        assert.match(sql, /c\.table_name AS "table_name"/);
+        assert.match(sql, /c\.column_name AS "column_name"/);
+        return {
           rows: [
             { table_schema: "APP", table_name: "CHILD", column_name: "BROKEN_ID", data_type: "NUMBER", is_nullable: "Y", column_default: null, ordinal_position: 1 },
             { table_schema: "APP", table_name: "CHILD", column_name: "PARENT_ID", data_type: "NUMBER", is_nullable: "N", column_default: null, ordinal_position: 2 },

packages/adapters-oracle/src/introspection.ts

@@ -74,12 +74,12 @@ ORDER BY 1, 2
 
 const COLUMNS_SQL = `
 SELECT
-  owner AS "table_schema",
-  table_name AS "table_name",
-  column_name AS "column_name",
-  data_type AS "data_type",
-  nullable AS "is_nullable",
-  data_default AS "column_default",
+  c.owner AS "table_schema",
+  c.table_name AS "table_name",
+  c.column_name AS "column_name",
+  c.data_type AS "data_type",
+  c.nullable AS "is_nullable",
+  c.data_default AS "column_default",
   c.column_id AS "ordinal_position",
   cc.comments AS "description"
 FROM all_tab_columns c

packages/backend/src/handlers.ts

@@ -686,9 +686,12 @@ export const handlers: BackendRpcRouter = {
       console.log(
         `[omni-sql] listSchemas: adapter returned ${schemas.length} schemas ` +
         `in ${Date.now() - tList}ms`,
-      );
-      return { schemas };
-    } finally {
+      );
+      return { schemas };
+    } catch (error) {
+      if (config.dialect === "oracle") throw safeOracleDatabaseError(error) ?? error;
+      throw error;
+    } finally {
       await adapter.close().catch((e) => console.warn(`[omni-sql] listSchemas: close failed: ${errorMessage(e)}`));
     }
   },
@@ -891,18 +894,23 @@ export const handlers: BackendRpcRouter = {
     return { rowsAffected };
   },
 
-  async "metadata.introspect"({ connectionId }: IntrospectParams): Promise<IntrospectResult> {
+  async "metadata.introspect"({ connectionId }: IntrospectParams): Promise<IntrospectResult> {
     const s = requireSession(connectionId);
     console.log(
       `[omni-sql] introspect start: dialect=${logValue(s.config.dialect)}`,
     );
     const tConnect = Date.now();
-    await s.adapter.connect();
-    console.log(`[omni-sql] introspect: connected in ${Date.now() - tConnect}ms, querying metadata…`);
-    const tIntro = Date.now();
-    const db: Database = await refreshMetadataCache(connectionId, s);
-    console.log(`[omni-sql] introspect: adapter.introspect() returned in ${Date.now() - tIntro}ms`);
-    return db;
+    try {
+      await s.adapter.connect();
+      console.log(`[omni-sql] introspect: connected in ${Date.now() - tConnect}ms, querying metadata…`);
+      const tIntro = Date.now();
+      const db: Database = await refreshMetadataCache(connectionId, s);
+      console.log(`[omni-sql] introspect: adapter.introspect() returned in ${Date.now() - tIntro}ms`);
+      return db;
+    } catch (error) {
+      if (s.config.dialect === "oracle") throw safeOracleDatabaseError(error) ?? error;
+      throw error;
+    }
   },
 
   async "metadata.listRelations"({