Engineering & roadmap
Implementation review: PB-024, PR 581
Development documentation. This guide follows a reviewed snapshot of main and may describe capabilities not yet in Stable. Check Preview labels and release notes. Some executable names and paths remain unchanged for compatibility. Legacy names explained ↗
| Field | Value |
|---|---|
| Backlog item | PB-024 Native Warehouse and SQL database connectivity (feature FEAT-FAB-11; owner's id SQL-004) |
| Pull request | #580 (mssql-python driver), merged as 49e3dbfd; #581 (SQL-004 read-only warehouse queries), merged as d8b18ffe; #636 (WH-01 Warehouse page), merged as af8dee38. Later fixes after the tenant run: #808 (b2db2c79), #809 (61eee496) |
| Package | None (no docs/product/pr-ready/PB-024.md) |
| Reviewer | Engineering quality review thread. It didn't write #580, #581 or #636. |
| Date | 2026-10-27 |
| Environment | Linux container, main 6159e507, Python venv for the engine, Playwright Chromium. No tenant, no Windows, no second PC. |
Outcome#
Changes Required (recommended).
Querying a Fabric Warehouse and a SQL analytics endpoint as the signed-in user, read-only unless a confirmed change is started, is built and well tested with a fake connection. Two things keep it from being accepted: the item names the Fabric SQL database and the code can't reach one (warehouse.KINDS is warehouse and endpoint only, and the host must be *.datawarehouse.fabric.microsoft.com); and the engine that every green build of main publishes to the Preview channel carries Microsoft's ODBC Driver 18, whose redistribution terms (end users agree to protective terms) aren't met: docs/end-user-terms.md is a draft "not in effect" that the app doesn't show. No live query was run from this container.
Recommended by: Engineering quality review. Decided by (product owner): pending.
Acceptance criteria#
SQL-004 has no written definition in the repo. grep -rn SQL-004 docs/ finds only references: PRODUCT_BACKLOG.md (PB-024 points to it), quality/architecture.md:30 ("owners for SQL-004+ pending"), quality/pr-review.md:434 (the #581 review) and COMPETITIVE_CAPABILITY_MATRIX.md:47 ("Scope SQL-004 to what local development needs (run, compare, check)"). The nearest statements of scope are #581's commit message (50fa32d0: "W4 of the warehouse plan: ... runs one T-SQL query that only reads ... through mssql-python with an Azure SQL token ... server ... must be a *.datawarehouse.fabric.microsoft.com host") and the WH-01 row of docs/warehouse.md:233. PB-024 has since been absorbed by the warehouse program (PRODUCT_BACKLOG.md:349, "Absorbs ... the SQL sprint's SQL-004/005 screens"). The criteria below come from the item's problem statement and the checks the request named.
| # | Criterion | Result | Evidence |
|---|---|---|---|
| 1 | Connect to a Fabric Warehouse | Met (not live-tested here) | warehouse.resolve reads the server from Fabric's connectionString for the item (sidecar/fabric_desktop/warehouse.py:101-124); connect opens one unpooled connection with Encrypt=yes;TrustServerCertificate=no and the token in SQL_COPT_SS_ACCESS_TOKEN (warehouse.py:236-246). test_a_query_runs_on_the_warehouse_fabric_names_and_pages_like_any_run uses a fake driver. |
| 2 | Connect to a lakehouse's SQL analytics endpoint | Met (not live-tested here) | kind="endpoint" reads sqlEndpointProperties.connectionString from the lakehouse (warehouse.py:114-116); test_a_sql_analytics_endpoint_is_found_through_its_lakehouse; browser test "Workspaces offers the page on a warehouse and on an endpoint whose lakehouse is listed". |
| 3 | Connect to a Fabric SQL database | Not met | KINDS = ("warehouse", "endpoint") (warehouse.py:57); sql_start refuses any other kind (sql_exec.py:243-245); HOST_SUFFIX = ".datawarehouse.fabric.microsoft.com" (warehouse.py:58) would refuse a SQL database's server anyway. FEAT-FAB-11 lists "no Fabric SQL database" as a known limitation; docs/warehouse.md and sql-execution.md don't mention SQL databases. |
| 4 | Signs in as the user with an Azure SQL token | Met in code; scope unproven on a tenant here | WAREHOUSE_SCOPES = ["https://database.windows.net/user_impersonation"] (auth.py:74), asked on first use (auth.py:292). The worker asks the engine for it over its pipe and keeps it in memory (sql_exec.py:467-468). The token is only sent to a Fabric-resolved *.datawarehouse.fabric.microsoft.com host with no ;,={}/ characters (warehouse.py:122); test_a_server_that_isnt_fabrics_is_never_used. test_the_token_is_for_azure_sql. docs/permissions.md:46 lists the scope and still says "Not yet tried". |
| 5 | Queries are read-only unless a change is confirmed | Met | Without allow=["warehouse_write"], one statement that reads, parsed by sqlglot; INTO, EXEC, DECLARE, second statements and OPENROWSET/OPENQUERY/OPENDATASOURCE are refused before Fabric is asked (warehouse.py:132-163; sql_exec.py:293), checked again in the worker (warehouse.py:257-263), and the transaction is rolled back (warehouse.py:299-304). My probe of 16 statements: multi-statement, CTE+DELETE, SELECT INTO, EXEC, UPDATE, TRUNCATE, DECLARE and SET were refused; an OPENROWSET(BULK ...) that sqlglot can't parse was refused as unreadable. |
| 6 | Warehouse writes (D1) are gated: preview, confirm, typed name in Prod | Met | Engine: a change needs confirm and a non-empty confirm_name (sql_exec.py:276-277), the name is checked against Fabric's before connecting (sql_exec.py:322-327), and sql_warehouse_writes off refuses every change (sql_exec.py:272; a broken policy turns it off, test_the_setting_is_on_by_default_and_a_broken_policy_turns_it_off). UI: a Prod workspace, or one with no mapped environment, needs the name typed (app/ui/sqlchanges.js:12-29, 55-57); #808 made unmapped and shared Dev/Prod workspaces count as Prod. Browser "in Prod the warehouse's name has to be typed" passes. |
| 7 | Timeouts and cancel | Met (fake driver) | The run is its own process; Stop and the time limit end it (warehouse.py:35-36; sql_exec.py:537), the driver timeout is set too (warehouse.py:268-269), login timeout 60 s (warehouse.py:61). test_stop_ends_the_run_and_its_connection, test_the_time_limit_stops_a_slow_warehouse_query, test_a_failed_query_still_rolls_back_and_closes. Whether Fabric ends the query when the connection drops wasn't tried here. |
| 8 | Driver packaged into the engine, licence terms handled | Partly | mssql-python 1.16.0 with mssql-python-odbc 18.6.2.2 and mssql-python-rs 0.3.0 pinned (sidecar/constraints.txt:38-40, pyproject.toml:47); the release engine is built from constraints.txt (.github/workflows/ci.yml:177-178) and published on every green build of main (ci.yml:308-312). docs/install.md:80 names the ODBC Driver 18 and msvcp140.dll licences. The ODBC licence's redistribution conditions aren't met: docs/end-user-terms.md:3 says the terms are a draft, not shown and binding no one, and lines 55-63 list open items (REDIST list, mssql-auth.dll, msvcp140.dll, indemnity, network check). The #580 review asked for "Chris's licence decision before merge" (quality/pr-review.md:435); I found no recorded decision. |
Checks#
| Check | Result | Evidence or note |
|---|---|---|
| Scope matches the item and package | Partly | Warehouse and endpoint are covered; Fabric SQL database isn't (criterion 3). No package. |
| New tests fail without the change, pass with it | Met | #581: on a tree of 49e3dbfd (before #581) with #581's test_warehouse_queries.py, collection fails (no fabric_desktop.warehouse); on d8b18ffe, test_warehouse_queries.py + test_warehouse_driver.py 30 passed. #636: on d3ce6d1e (before #636) with #636's warehouse-page.test.cjs, 6 of 6 fail; on af8dee38 (#636 merged) 6 of 6 pass. #580's driver test can't fail without the change here, since the venv already has mssql-python installed. |
| Full suites pass (pytest, UI, cargo) | Partly | On main 6159e507: test_warehouse_driver 2 passed; test_warehouse_queries 100 passed; test_sql_exec 98 passed; test_policy 6 passed; test_warehouse_project 44 passed; test_sql_queries 7 passed; test_tsql_contract 321 passed, 70 skipped (live cases need FABRIC_DESKTOP_TSQL_LIVE=1). UI ui.test.cjs 297/297. Browser: warehouse-page 18/18, warehouse-changes 9/9, warehouse-deploy 5/5, warehouse-project 8/8, sql-exec 11/11, sql-editor 16/16. Not the whole pytest suite. Cargo not run here; #580-#636 changed no Rust. |
| Reachable where docs say; Preview behavior right; packaged into the engine | Met | Workspaces > Warehouse or SQL analytics endpoint row > SQL query (docs/warehouse.md:7); Preview-gated page. The driver goes into the release engine (ci.yml:177-178). |
| OneLake data safety | Met | No OneLake writes. Reads are rolled back; changes run in one transaction committed only when every batch succeeded (warehouse.py:293-304). |
| Authentication and distribution | Partly | Token scope documented (permissions.md:46, :69) and sent only to Fabric's host. Two gaps: the ODBC Driver 18 redistribution terms (criterion 8); permissions.md:46 writes the scope as /.default while the code asks for /user_impersonation (auth.py:74), harmless but inconsistent. |
| No unproven claim; Preview tags kept where untested | Partly | The page stays Preview. #808's and #809's commit messages say a tenant run on 2026-10-27 found #807 and the system-schema Import problem, so a live query has now run, but no doc records that run: permissions.md:46 still says "Not yet tried; the first live query checks it", warehouse.md:225 says Preview "until a query has been run on a tenant", and FEAT-FAB-11 still says "Not yet run against a live warehouse (decision D3)". I couldn't verify the run from here. |
| Docs match the code; linked; strict docs build passes | Partly | sql-execution.md:67-90 and warehouse.md match the read-only check, host rule, change gate and plan. Stale: FEAT-FAB-11 known limitations still say "Read-only: writes wait on Chris's decision D1" and "No build or deploy (WH-09..14)", both since built; PB-024's evidence still says "No TDS or ODBC client in sidecar/constraints.txt" (PRODUCT_BACKLOG.md:273). Docs build not run here. |
| Accessibility of new controls | Met (change dialog read; first-run confirm not checked) | The change dialog focuses the typed-name field or Cancel, so Enter never runs a change by itself (sqlchanges.js:74). |
Inventory and backlog updated; product_data.py consistent |
Not met | See the stale FEAT-FAB-11 limitations and PB-024 evidence above. product_data.py not run. |
Findings#
| # | Severity (blocking / should fix / note) | Finding | Where | Status |
|---|---|---|---|---|
| 1 | blocking | Fabric SQL database, named in the item's title and problem, can't be reached: only warehouse and endpoint kinds, and a host rule that only accepts *.datawarehouse.fabric.microsoft.com. Either build it (its own kind, its host suffix, tests) or split it into its own backlog item and narrow PB-024. |
sidecar/fabric_desktop/warehouse.py:57-58, :101-124; sql_exec.py:243-245 | Open: product owner and warehouse program |
| 2 | blocking | The Preview release engine ships Microsoft ODBC Driver 18 (msodbcsql18.dll etc.), mssql-auth.dll and msvcp140.dll, while the end-user terms that the ODBC licence's section 2 requires are a draft the app doesn't show. No recorded licence decision found. Needs counsel's terms shown and accepted, or a recorded owner decision to accept the risk for Preview, or the driver kept out of published builds until then. |
docs/end-user-terms.md:3, :55-63; .github/workflows/ci.yml:177-178, :308-312; quality/pr-review.md:435 | Open: product owner and counsel |
| 3 | should fix | The 2026-10-27 tenant run isn't recorded: permissions.md:46 says the Azure SQL scope is "Not yet tried", warehouse.md:225 and FEAT-FAB-11 say no live query yet. Record what ran (warehouse or endpoint, sign-in app, scope result) and what it found (#807, the system schemas), and update the verification. | docs/permissions.md:46; docs/warehouse.md:225; FEATURE_INVENTORY FEAT-FAB-11 | Open: warehouse program |
| 4 | should fix | FEAT-FAB-11 known limitations are stale ("writes wait on D1", "no build or deploy"); PB-024 evidence still says there's no ODBC client in constraints.txt. | docs/product/FEATURE_INVENTORY.json / .md:706; PRODUCT_BACKLOG.md:273 | Open: product data owner |
| 5 | note | The engine's warehouse tests use a fake connection; only import mssql_python and its connect signature are tested against the real driver (test_warehouse_driver.py). The token packing for SQL_COPT_SS_ACCESS_TOKEN and the driver's timeout are proven only by the tenant run. |
sidecar/tests/test_warehouse_driver.py; warehouse.py:236-246 | Open: covered by the live T-SQL contract job once configured (docs/live-testing.md:121-130) |
| 6 | note | A read may name another database (SELECT * FROM otherdb.dbo.t is read_only); Fabric's permissions decide, and the transaction is rolled back, so it is not a write path. Changes refuse three-part names (warehouse.py:223-225). |
warehouse.py:132-163 | No change needed |
| 7 | note | permissions.md writes the Azure SQL scope as /.default; the code asks for /user_impersonation. |
docs/permissions.md:46; auth.py:74 | Open: docs |
Inventory and backlog changes#
- Features changed: FEAT-FAB-11: refresh known limitations (findings 3 and 4); record the 2026-10-27 tenant run and its fixes (#808, #809) as verification evidence once written up.
- Backlog item state: PB-024 stays In review until findings 1 and 2 are resolved (or SQL database is split out and the licence decision recorded); evidence text to update (finding 4).
Need a hand?
Find a fix in troubleshooting, or share a reproducible issue with the community.
Get support ↗Improve this guide on GitHub ↗