Merge pull request #35591 from MicrosoftDocs/main

Auto Publish – main to live - 2025-10-16 22:30 UTC

Author: learn-build-service-prod[bot]

docs/includes/azure-data-studio-deprecation.md

@@ -0,0 +1,12 @@
+---
+title: Deprecate Azure Data Studio
+author: croblesm
+ms.author: roblescarlos
+ms.reviewer: randolphwest, maghan
+ms.date: 10/10/2025
+ms.service: azure-data-studio
+ms.topic: include
+---
+
+> [!IMPORTANT]  
+> Azure Data Studio is [retiring on February 28, 2026](/lifecycle/definitions#retirement). We recommend that you use [Visual Studio Code](https://code.visualstudio.com/). For more information about migrating to Visual Studio Code, visit [What's happening to Azure Data Studio?](/azure-data-studio/whats-happening-azure-data-studio)

docs/t-sql/functions/vector-search-transact-sql.md

@@ -4,7 +4,7 @@ description: VECTOR_SEARCH search for vectors similar to a given query vectors u
 author: yorek
 ms.author: damauri
 ms.reviewer: mikeray, randolphwest
-ms.date: 10/14/2025
+ms.date: 10/16/2025
 ms.service: sql
 ms.subservice: t-sql
 ms.topic: reference
@@ -85,7 +85,7 @@ The result set returned by the `VECTOR_SEARCH` function includes:
 
 The distance column is generated by the `VECTOR_SEARCH` function itself, while all other columns come from the table referenced in the `TABLE` argument.
 
-If you use an alias for the table in the `TABLE` argument, you must use that same alias to reference its columns in the `SELECT` statement. You can't use the alias assigned to `VECTOR_SEARCH` to reference columns from the table specified in `TABLE`. This behavior is easier to understand if you think of the result set as a JSON object that merges the output of `VECTOR_SEARCH` with the table data.
+If you use an alias for the table in the `TABLE` argument, you must use that same alias to reference its columns in the `SELECT` statement. You can't use the alias assigned to `VECTOR_SEARCH` to reference columns from the table specified in `TABLE`. This behavior is easier to understand if you think of the result set built by taking the output of `VECTOR_SEARCH` and merging it with the table data.
 
 If the table specified in the `TABLE` argument already contains a column named `distance`, the behavior will be similar to a SQL join between two tables that share a column name. In such cases, you must use table aliases to disambiguate the column references—otherwise, an error will be raised.
 
@@ -100,9 +100,9 @@ The current preview has the following limitations:
 Vector search happens before applying any predicate. Additional predicates are applied only after the most similar vectors are returned. The following sample returns the top 10 rows with embeddings most similar to the query vector `@qv`, then applies the predicate specified in the `WHERE` clause. If none of the 10 rows associated with the vectors returned by the vector search have the `accepted` column equal to 1, the result is empty.
 
 ```sql
-SELECT s.id,
-       s.title,
-       r.distance
+SELECT TOP (10) s.id,
+                s.title,
+                r.distance
 FROM VECTOR_SEARCH(
          TABLE = dbo.sessions AS s,
          COLUMN = embedding,
@@ -126,10 +126,10 @@ The following example finds the 10 most similar articles to the `Pink Floyd musi
 
 ```sql
 DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDING(N'Pink Floyd music style' USE MODEL Ada2Embeddings);
-SELECT
-    t.id, s.distance, t.title
-FROM
-    VECTOR_SEARCH(
+SELECT TOP (10) s.id,
+                s.title,
+                r.distance
+FROM VECTOR_SEARCH(
         TABLE = [dbo].[wikipedia_articles_embeddings] as t,
         COLUMN = [content_vector],
         SIMILAR_TO = @qv,
@@ -150,17 +150,19 @@ CREATE TABLE #t
     q NVARCHAR (MAX),
     v VECTOR(1536)
 );
+
 INSERT INTO #t
 SELECT id,
        q,
        AI_GENERATE_EMBEDDINGS(q USE MODEL Ada2Embeddings)
 FROM (VALUES
         (1, N'four legged furry animal'),
         (2, N'pink floyd music style')
-) AS S(id, q);
-SELECT t.id,
-       s.distance,
-       t.title
+    ) S(id, q);
+
+SELECT TOP (10) t.id,
+                s.distance,
+                t.title
 FROM #t AS qv
 CROSS APPLY
     VECTOR_SEARCH(
@@ -169,7 +171,7 @@ CROSS APPLY
         SIMILAR_TO = qv.v,
         METRIC = 'cosine',
         TOP_N = 10
-) AS s
+    ) AS s
 WHERE qv.id = 2
 ORDER BY s.distance;
 ```
@@ -214,23 +216,23 @@ GO
 
 -- Step 3: Create a vector index on the embedding column
 CREATE VECTOR INDEX vec_idx ON Articles(embedding)
-WITH (metric = 'cosine', type = 'diskann');
+WITH (METRIC = 'cosine', TYPE = 'diskann');
 GO
 
 -- Step 4: Perform a vector similarity search
 DECLARE @qv VECTOR(5) = '[0.3, 0.3, 0.3, 0.3, 0.3]';
-SELECT
+SELECT TOP(3)
     t.id,
     t.title,
     t.content,
     s.distance
 FROM
     VECTOR_SEARCH(
-        table = Articles AS t,
-        column = embedding,
-        similar_to = @qv,
-        metric = 'cosine',
-        top_n = 3
+        TABLE = Articles AS t,
+        COLUMN = embedding,
+        SIMILAR_TO = @qv,
+        METRIC = 'cosine',
+        TOP_N = 3
     ) AS s
 ORDER BY s.distance, t.title;
 ```

docs/toc.yml

@@ -8981,6 +8981,14 @@ items:
         href: tools/visual-studio-code-extensions/sql-bindings/create-azure-function-object-explorer.md
       - name: Command Palette
         href: tools/visual-studio-code-extensions/sql-bindings/create-azure-function-command-palette.md
+    - name: SQL Database Projects
+      items:
+      - name: Overview
+        href: tools/visual-studio-code-extensions/sql-database-projects/sql-database-projects-extension.md
+      - name: Getting Started
+        href: tools/visual-studio-code-extensions/sql-database-projects/getting-started-sql-database-projects-extension.md
+      - name: Build from the Command Line
+        href: tools/visual-studio-code-extensions/sql-database-projects/build-database-project-from-command-line.md
 - name: Tutorials
   items:
   - name: SQL Server

docs/tools/sql-database-projects/concepts/database-references.md

@@ -1,23 +1,23 @@
 ---
 title: Database References Overview
-description: "Extend a SQL project with references to additional database components."
+description: Extend a SQL project with references to additional database components.
 author: dzsquared
 ms.author: drskwier
 ms.reviewer: maghan, randolphwest
-ms.date: 08/30/2024
+ms.date: 10/10/2025
 ms.service: sql
 ms.subservice: sql-database-projects
 ms.topic: concept-article
 ms.collection:
   - data-tools
+ms.custom:
+  - ignite-2024
+  - sfi-ropc-nochange
 f1_keywords:
   - "sql.data.tools.adddatabasereference.dialog"
   - "sql.data.tools.newdatabase.dialog"
   - "sql.data.tools.criticalerror.dialog"
 zone_pivot_groups: sq1-sql-projects-tools
-ms.custom:
-  - ignite-2024
-  - sfi-ropc-nochange
 ---
 
 # Database references overview
@@ -38,8 +38,10 @@ Database references are included in a project through entries in the `.sqlproj`
 Including a specific reference to the database reference in the SQL scripts use SQLCMD variables named in the project file to specify the database name. For example, the following SQL script references a table in the `Warehouse` database:
 
 ```sql
-SELECT ProductId, StorageLocation, BinNumber
-FROM [$(Warehouse)].[Production].[ProductInventory]
+SELECT ProductId,
+       StorageLocation,
+       BinNumber
+FROM [$(Warehouse)].[Production].[ProductInventory];
 ```
 
 A database reference corresponding to the `$(Warehouse)` SQLCMD variable is included in the project file and contains `<DatabaseSqlCmdVariable>Warehouse</DatabaseSqlCmdVariable>`.
@@ -213,5 +215,6 @@ sqlpackage /Action:Publish /SourceFile:AdventureWorks.dacpac /TargetConnectionSt
 
 ## Related content
 
-- [SQL projects package references overview](package-references.md)
+- [SQL projects package references](package-references.md)
+- [SQL projects system objects](system-objects.md)
 - [SQLCMD variables overview](sqlcmd-variables.md)

docs/tools/sql-database-projects/concepts/package-references.md

@@ -1,10 +1,10 @@
 ---
 title: SQL Projects Package References
-description: "Reference database objects with package references."
+description: Reference database objects with package references.
 author: dzsquared
 ms.author: drskwier
 ms.reviewer: maghan, randolphwest
-ms.date: 03/11/2025
+ms.date: 10/10/2025
 ms.service: sql
 ms.subservice: sql-database-projects
 ms.topic: concept-article
@@ -131,6 +131,7 @@ The package being referenced should be available on a [NuGet feed](/dotnet/core/
 ## Related content
 
 - [Database references overview](database-references.md)
+- [SQL projects system objects](system-objects.md)
 - [Code analysis rules extensibility overview](code-analysis-extensibility.md)
 - [Creating a package with the dotnet CLI](/nuget/create-packages/creating-a-package-dotnet-cli)
 - [Hosting with private package feeds](/nuget/hosting-packages/overview)

docs/tools/sql-database-projects/concepts/schema-comparison.md

@@ -1,10 +1,10 @@
 ---
 title: Schema Comparison Overview
-description: "Visualize the difference in database models with schema compare."
+description: Visualize the difference in database models with schema compare.
 author: dzsquared
 ms.author: drskwier
 ms.reviewer: maghan, randolphwest, tsiddique
-ms.date: 05/20/2025
+ms.date: 10/10/2025
 ms.service: sql
 ms.subservice: sql-database-projects
 ms.topic: overview
@@ -165,9 +165,9 @@ To update the schema of the target, you have two options. You can update the tar
 
 ::: zone pivot="sq1-visual-studio-code"
 
-More in-depth information about schema comparison in Visual Studio Code is available in the article [Schema Compare (Preview)](../../visual-studio-code-extensions/mssql/mssql-schema-compare.md)
+More in-depth information about schema comparison in Visual Studio Code is available in the article [Schema Compare](../../visual-studio-code-extensions/mssql/mssql-schema-compare.md)
 
-1. In Visual Studio Code in the command palette (`ctrl/cmd+shift+P`), search for and select **MSSQL: Schema Compare (Preview)**.
+1. In Visual Studio Code in the command palette (`ctrl/cmd+shift+P`), search for and select **MSSQL: Schema Compare**.
 
    Alternatively, right-click a database project in the **Database Projects** view or a database in **Object Explorer**, and select **Schema Compare**.
 

docs/tools/sql-database-projects/concepts/system-objects.md

@@ -0,0 +1,90 @@
+---
+title: SQL Projects System Objects
+description: Learn about referencing system objects in SQL projects.
+author: dzsquared
+ms.author: drskwier
+ms.reviewer: maghan, randolphwest
+ms.date: 10/10/2025
+ms.service: sql
+ms.subservice: sql-database-projects
+ms.topic: concept-article
+ms.collection:
+  - data-tools
+---
+
+# SQL projects system objects
+
+[!INCLUDE [SQL Server Azure SQL Database Azure SQL Managed Instance FabricSQLDB](../../../includes/applies-to-version/sql-asdb-asdbmi-fabricsqldb.md)]
+
+SQL projects validate database object references during the project build process. By default, SQL projects don't include system objects in the database model, which can lead to validation errors if your project contains references to system objects. To resolve these validation errors, you would include a database reference to the `master.dacpac` for the target platform of your project.
+
+The `master.dacpac` database reference can be added as a [package reference](package-references.md) in Microsoft.Build.Sql SDK-style SQL projects or as an [artifact reference](database-references.md) in both SDK-style and original SQL projects.
+
+## Add a package reference
+
+The available system database packages are:
+
+- [SQL Server `master` system database](https://www.nuget.org/packages/Microsoft.SqlServer.Dacpacs.Master)
+- [SQL Server `msdb` system database](https://www.nuget.org/packages/Microsoft.SqlServer.Dacpacs.Msdb)
+- [Azure SQL Database `master` system database](https://www.nuget.org/packages/Microsoft.SqlServer.Dacpacs.Azure.Master)
+- [SQL database in Fabric system objects](https://www.nuget.org/packages/Microsoft.SqlServer.Dacpacs.DbFabric)
+- [Azure Synapse Analytics `master` system database](https://www.nuget.org/packages/Microsoft.SqlServer.Dacpacs.Synapse.Master)
+- [Azure Synapse Analytics serverless pools `master` system database](https://www.nuget.org/packages/Microsoft.SqlServer.Dacpacs.SynapseServerless.Master)
+
+The most direct method for adding a package reference to a SQL project is to use the .NET command-line interface (CLI). The following example adds a package reference to the Azure SQL Database `master` system database to a SQL project:
+
+```bash
+dotnet add <path-to-sqlproj> package Microsoft.SqlServer.Dacpacs.Azure.Master
+```
+
+This command adds the following entry to the `.sqlproj` file (the package version will reflect the latest version available at the time the command is run):
+
+```xml
+...
+    <ItemGroup>
+        <PackageReference Include="Microsoft.SqlServer.Dacpacs.Azure.Master" Version="170.0.1" />
+    </ItemGroup>
+</Project>
+```
+
+## Add an artifact reference
+
+The VS Code and Visual Studio SQL project interfaces provide a method for adding an artifact reference to the `master.dacpac` file for the target platform of your project.
+
+The resulting edits to the `.sqlproj` file will look similar to the following example, which adds an artifact reference to the Azure SQL Database `master` system database in Visual Studio:
+
+```xml
+<ItemGroup>
+    <ArtifactReference Include="$(DacPacRootPath)\Extensions\Microsoft\SQLDB\Extensions\SqlServer\AzureV12\SqlSchemas\master.dacpac">
+      <HintPath>$(DacPacRootPath)\Extensions\Microsoft\SQLDB\Extensions\SqlServer\AzureV12\SqlSchemas\master.dacpac</HintPath>
+      <SuppressMissingDependenciesErrors>False</SuppressMissingDependenciesErrors>
+      <DatabaseVariableLiteralValue>master</DatabaseVariableLiteralValue>
+    </ArtifactReference>
+  </ItemGroup>
+```
+
+The `master.dacpac` files are referenced from the installation location of the applications, which can be fragile for some CI/CD systems. You can copy the `master.dacpac` file to a location within your solution and update the `Include` and `HintPath` attributes to point to that location if your build system doesn't include the system database files.
+
+## SQL database in Fabric
+
+The SQL database in Fabric system objects are included in the `Microsoft.SqlServer.Dacpacs.DbFabric` package, but additional steps might be required to configure the database reference correctly for the SQL database in Fabric environment.
+
+The SQL project created with the integrated source control in Fabric includes the package reference and the `DatabaseVariableLiteralValue` property set to `master`. This property is required because SQL database in Fabric doesn't provide access to the `master` database but the same system objects can be referenced in the user database.
+
+If you create a new SQL project in Visual Studio or VS Code, you must update the `DatabaseVariableLiteralValue` property to `master` to match the database name used in the SQL database in Fabric environment.
+
+```xml
+  <ItemGroup>
+    <PackageReference Include="Microsoft.SqlServer.Dacpacs.DbFabric">
+      <SuppressMissingDependenciesErrors>False</SuppressMissingDependenciesErrors>
+      <DatabaseVariableLiteralValue>master</DatabaseVariableLiteralValue>
+      <Version>170.0.0</Version>
+    </PackageReference>
+  </ItemGroup>
+```
+
+## Related content
+
+- [Database references overview](database-references.md)
+- [SQL projects package references](package-references.md)
+- [SqlPackage CLI](../../sqlpackage/sqlpackage.md)

docs/tools/visual-studio-code-extensions/sql-database-projects/build-database-project-from-command-line.md

@@ -0,0 +1,50 @@
+---
+title: Build a Project from the Command Line
+description: Build a SQL Server Database Project from the command line
+author: dzsquared
+ms.author: drskwier
+ms.reviewer: randolphwest, maghan
+ms.date: 10/10/2025
+ms.service: sql
+ms.subservice: sql-database-projects
+ms.topic: how-to
+ms.collection:
+  - data-tools
+---
+
+# Build a database project from command line
+
+[!INCLUDE [azure-data-studio-deprecation](../../../includes/azure-data-studio-deprecation.md)]
+
+While the SQL Database Project extension provides a graphical user interface to build [SQL database projects](../../sql-database-projects/sql-database-projects.md), a command line build experience is also available for Windows, macOS, and Linux environments. This article outlines the prerequisites and syntax needed to build a `.dacpac` from a Microsoft.Build.Sql SDK-style SQL project at the command line.
+
+## Microsoft.Build.Sql with .NET
+
+Using [Microsoft.Build.Sql](https://www.nuget.org/packages/Microsoft.Build.Sql) with [SDK-style SQL projects](../../sql-database-projects/sql-database-projects.md#original-projects-vs-sdk-style-projects) is the preferred method for working with SQL projects from the command line.
+
+To build an SDK-style SQL project from the command line on Windows, macOS, or Linux, use the following command:
+
+```bash
+dotnet build
+```
+
+Optionally, you can specify the project name. Specifying the project name enables building a specific project within a more complex folder structure.
+
+```bash
+dotnet build AdventureWorks/AdventureWorks.sqlproj
+```
+
+## Microsoft.Build.Sql with .NET Framework
+
+Starting with Microsoft.Build.Sql 2.0.0-preview.3, SDK-style SQL projects can be built from the command line with .NET Framework and msbuild. For SQLCLR objects, .NET Framework is required to build the SQL project.
+
+```bash
+msbuild AdventureWorks/AdventureWorks.sqlproj
+```
+
+## Related content
+
+- [SQL Database Projects extension](sql-database-projects-extension.md)
+- [Tutorial: Create and deploy a SQL project](../../sql-database-projects/tutorials/create-deploy-sql-project.md)
+- [Get help with the SQL Database Projects extension](https://github.com/microsoft/azuredatastudio/issues)
+- [Get help with SQL projects and DacFx](https://github.com/microsoft/dacfx)