教程：创建和部署 SQL 项目
适用于：
SQL Server Azure SQL 数据库 Azure SQL 托管实例 Microsoft Fabric SQL 数据库
SQL 数据库项目的开发周期使数据库开发能够集成到作为开发最佳做法所熟悉的持续集成和持续部署 (CI/CD) 工作流中。 虽然可以手动部署 SQL 数据库项目，但建议使用部署管道自动执行部署过程，以便根据持续的本地开发运行正在进行的部署，而无需额外工作。
本文逐步介绍如何创建新的 SQL 项目、向项目添加对象，以及设置持续部署管道，以便使用 GitHub Actions 生成和部署项目。 本教程是 SQL 项目入门文章内容的超集。 虽然本教程在 GitHub Actions 中实现部署管道，但相同的概念也适用于 Azure DevOps、GitLab 和其他自动化环境。
在本教程中，你将了解：
- 创建新的 SQL 项目
- 向项目添加对象
- 在本地生成项目
- 将项目签入到源控件
- 将项目生成步骤添加到持续部署管道
- 将
.dacpac部署步骤添加到持续部署管道
如果 SQL 项目入门文章中的步骤，可以跳到步骤 4。 在本教程结束时，SQL 项目将自动生成更改并将其部署到目标数据库。
先决条件
# install SqlPackage CLI
dotnet tool install -g Microsoft.SqlPackage
# install Microsoft.Build.Sql.Templates
dotnet new install Microsoft.Build.Sql.Templates
请确保具有以下项以在 GitHub 中完成管道设置：
注意
若要完成 SQL 数据库项目的部署，需要访问 Azure SQL 或 SQL Server 实例的权限。 可以在 Windows 或容器上使用 SQL Server 开发者版本在本地进行免费开发。
步骤 1：创建新项目
在手动向项目添加对象之前，我们将通过创建新的 SQL 数据库项目来启动项目。 可通过其他方法创建一个项目，以便立即使用现有数据库中的对象填充项目，例如使用架构比较工具。
依次选择“文件”、“新建”和“项目”。
在“新建项目”对话框中，在搜索框中使用术语“SQL Server”。 最匹配的结果应该是 SQL Server 数据库项目。
选择下一步以继续执行下一步。 提供不需要与数据库名称匹配的项目名称。 根据需要验证和修改项目位置。
选择“创建”来创建项目。 空项目在“解决方案资源管理器”中打开并可见，可供编辑。
依次选择“文件”、“新建”和“项目”。
在“新建项目”对话框中，在搜索框中使用术语“SQL Server”。 最匹配的结果应是“SDK 式 SQL Server 数据库项目（预览版）”。
选择下一步以继续执行下一步。 提供不需要与数据库名称匹配的项目名称。 根据需要验证和修改项目位置。
选择“创建”来创建项目。 空项目在“解决方案资源管理器”中打开并可见，可供编辑。
在 VS Code 或 Azure Data Studio 的“数据库项目”视图中，选择“新建项目”按钮。
第一个提示确定要使用哪个项目模板，主要基于目标平台是 SQL Server 还是 Azure SQL。 如果系统提示选择特定版本的 SQL，请选择与目标数据库匹配的版本，但如果目标数据库版本未知，请选择最新版本，因为稍后可以修改该值。
在出现的文本输入中输入项目名称，该名称无需与数据库名称匹配。
在出现的“选择文件夹”对话框中，选择项目文件夹的目录、.sqlproj 文件和要包含的其他内容。
当系统提示是否创建 SDK 样式项目（预览）时，请选择“是”。
一旦完成后，空项目在“数据库项目”视图中打开并可见，可供编辑。
安装适用于 Microsoft.Build.Sql 项目的 .NET 模板后，可以从命令行创建新的 SQL 数据库项目。 -n 选项指定项目的名称，-tp 选项指定项目目标平台。
使用选项 -h 查看所有可用选项。
# install Microsoft.Build.Sql.Templates
dotnet new sqlproject -n MyDatabaseProject
步骤 2：将对象添加到项目中
在“解决方案资源管理器”中，右键单击项目节点，然后依次选择“添加”、“表”。 此时会显示“添加新项”对话框，可在其中指定表名称。 选择“添加”以在 SQL 项目中创建表。
该表在 Visual Studio 表设计器中打开，其中包含模板表定义，可在该设计器中添加列、索引和其他表属性。 完成初始编辑后保存文件。
可以通过“添加新项”对话框添加更多数据库对象，例如视图、存储过程和函数。 右键单击“解决方案资源管理器”中的项目节点并选择“添加”，然后选择所需的对象类型来访问对话框。 该项目中的文件可以通过“添加”下的“新建文件夹”选项组织到文件夹中。
在“解决方案资源管理器”中，右键单击项目节点，选择“添加”，然后选择“新项”。 此时会显示“添加新项”对话框，选择“显示所有模板”，然后选择“表”。 将表名指定为文件名，然后选择“添加”以在 SQL 项目中创建表。
该表将在 Visual Studio 查询编辑器中打开，其中包含模板表定义。你可以在该编辑器中添加列、索引和其他表属性。 完成初始编辑后保存文件。
可以通过“添加新项”对话框添加更多数据库对象，例如视图、存储过程和函数。 右键单击“解决方案资源管理器”中的项目节点并选择“添加”，然后在“显示全部模板”后选择所需的对象类型。 该项目中的文件可以通过“添加”下的“新建文件夹”选项组织到文件夹中。
在 VS Code 或 Azure Data Studio 的“数据库项目”视图中，右键单击项目节点并选择“添加表”。 在出现的对话框中，指定表名称。
该表在文本编辑器中打开，其中包含模板表定义，可在该编辑器中添加列、索引和其他表属性。 完成初始编辑后保存文件。
可以通过项目节点上的上下文菜单添加更多数据库对象，例如视图、存储过程和函数。 通过右键单击 VS Code 或 Azure Data Studio 的“数据库项目”视图中的项目节点，然后选择所需的对象类型来访问对话框。 该项目中的文件可以通过“添加”下的“新建文件夹”选项组织到文件夹中。
可以通过在项目目录或嵌套文件夹中创建文件，来将文件添加到项目中。 文件扩展名应为 .sql，建议按对象类型或架构和对象类型进行组织。
表的基础模板可用作在项目中创建新表对象的起点：
CREATE TABLE [dbo].[Table1]
(
[Id] INT NOT NULL PRIMARY KEY
)
步骤 3：生成项目
生成过程针对项目文件中指定的目标平台验证对象与语法之间的关系。 生成过程的项目输出是一个 .dacpac 文件，该文件可用于将项目部署到目标数据库，并包含数据库架构的已编译模型。
在“解决方案资源管理器”中，右键单击项目，然节点后选择“生成”。
输出窗口会自动打开以显示生成过程。 如果存在错误和警告，它们会显示在“输出窗口”中。 成功生成后，将会创建生成项目（.dacpac 文件），其位置包含在生成输出（默认值为 bin\Debug\projectname.dacpac）中。
在“解决方案资源管理器”中，右键单击项目，然节点后选择“生成”。
输出窗口会自动打开以显示生成过程。 如果存在错误和警告，它们会显示在“输出窗口”中。 成功生成后，将会创建生成项目（.dacpac 文件），其位置包含在生成输出（默认值为 bin\Debug\projectname.dacpac）中。
在 VS Code 或 Azure Data Studio 的“数据库项目”视图中，右键单击项目节点并选择“生成”。
输出窗口会自动打开以显示生成过程。 如果存在错误和警告，它们会显示在“输出窗口”中。 成功生成后，将会创建生成项目（.dacpac 文件），其位置包含在生成输出（默认值为 bin/Debug/projectname.dacpac）中。
可以使用 dotnet build 命令从命令行中生成 SQL 数据库项目。
dotnet build
# optionally specify the project file
dotnet build MyDatabaseProject.sqlproj
生成输出包括任何错误或警告，以及发生错误或警告的特定文件和行号。 成功生成后，将会创建生成项目（.dacpac 文件），其位置包含在生成输出（默认值为 bin/Debug/projectname.dacpac）中。
步骤 4：将项目签入到源控件
我们将项目初始化为 Git 存储库，并将项目文件提交到源控件。 此步骤是使项目能够与他人共享并在持续部署管道中使用所必需的。
从 Visual Studio 中的 Git 菜单中，选择“创建 Git 存储库”。
在创建 Git 存储库对话框中的推送到新的远程存储库部分下，选择 GitHub。
在创建 Git 存储库对话框的创建新的 GitHub 存储库部分中，输入要创建的存储库的名称 。 （如果尚未登录到 GitHub 帐户，也可以在此屏幕中登录。）
在“初始化本地 Git 存储库”下，应使用“.gitignore 模板”选项指定任何需要 Git 忽略的有意未跟踪文件。 若要详细了解 .gitignore，请参阅忽略文件。 若要了解有关许可的详细信息，请参阅授权存储库。
登录并输入存储库信息后，选择创建并推送按钮以创建存储库并添加应用。
在“解决方案资源管理器”中，右键单击项目节点，并选择“发布...”。
此时会打开“发布”对话框，可在其中建立目标数据库连接。 如果没有用于部署的现有 SQL 实例，则 LocalDB ((localdb)\MSSQLLocalDB) 随 Visual Studio 一起安装，并且可用于测试和开发。
指定数据库名称，然后选择“发布”以将项目部署到目标数据库或生成脚本，以在执行之前生成要查看的脚本。
可以从 VS Code 或 Azure Data Studio 初始化本地存储库并将其直接发布到 GitHub。 此操作将在 GitHub 帐户上创建新的存储库，并在单个步骤中将本地代码更改推送到远程存储库。
使用 VS Code 或 Azure Data Studio 中“源控件”视图中的“发布到 GitHub”按钮。 然后，系统会提示你指定存储库的名称和说明，以及是将其设为公共还是专用。
或者，可以初始化本地存储库，并按照创建空的 GitHub 上的存储库时提供的步骤将其推送到 GitHub。
在项目目录中初始化新的 Git 存储库，并将项目文件提交到源控件。
git init
git add .
git commit -m "Initial commit"
创建新的 GitHub 上的存储库并将本地存储库推送到远程存储库。
git remote add origin <repository-url>
git push -u origin main
步骤 5：将项目生成步骤添加到持续部署管道
SQL 项目由 .NET 库提供支持，因此，该项目是使用 dotnet build 命令生成的。 此命令是最基本的持续集成和持续部署 (CI/CD) 管道的重要组成部分。 生成步骤可以添加到我们在 GitHub Actions 中创建的持续部署管道。
在存储库的根目录中，创建一个名为
.github/workflows的新目录。 此目录将包含定义持续部署管道的工作流文件。在
.github/workflows目录中，创建名为sqlproj-sample.yml的新文件。将以下内容添加到
sqlproj-sample.yml文件，编辑项目名称以匹配项目的名称和路径：name: sqlproj-sample on: push: branches: [ "main" ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup .NET uses: actions/setup-dotnet@v4 with: dotnet-version: 8.0.x - name: Build run: dotnet build MyDatabaseProject.sqlproj将工作流文件提交到存储库，并将更改推送到远程存储库。
在 GitHub.com 上，导航到存储库的主页。 在你的存储库名称下，单击“操作”。 在左侧边栏中，选择刚刚创建的工作流。 将工作流文件推送到存储库时，工作流的最新运行应显示在工作流运行所在的列表中。
有关创建第一个 GitHub Actions 工作流的基础知识的详细信息，请参阅 GitHub Actions 快速入门。
步骤 6：将 .dacpac 部署步骤添加到持续部署管道
.dacpac 文件中数据库架构的编译模型可以使用 SqlPackage 命令行工具或其他部署工具部署到目标数据库。 部署过程将确定更新目标数据库以匹配在 .dacpac 中定义的架构所需的步骤，以根据数据库中已存在的对象视需要创建或更改对象。 例如，若要基于连接字符串将 .dacpac 文件部署到目标数据库：
sqlpackage /Action:Publish /SourceFile:bin/Debug/MyDatabaseProject.dacpac /TargetConnectionString:{yourconnectionstring}
部署过程是幂等的，这意味着它可以多次运行，而不会造成问题。 我们创建的管道将在每次将更改签入存储库的 main 分支时生成和部署 SQL 项目。 我们可以使用一个部署任务来抽象命令，并提供日志记录、错误处理和任务配置等其他功能，而不是直接在部署管道中执行 SqlPackage 命令。 可以将部署任务 GitHub sql-action 添加到 GitHub Actions 中的持续部署管道。
注意
从自动化环境中运行部署需要配置数据库和环境，以便部署可以访问数据库并进行身份验证。 在虚拟机中的 Azure SQL 数据库或 SQL Server 中，这可能需要设置防火墙规则，以允许自动化环境连接到数据库，并提供具有所需凭证的连接字符串。 GitHub sql-action 文档中提供了指导。
打开
.github/workflows目录中的sqlproj-sample.yml文件。在生成步骤之后，将以下步骤添加到
sqlproj-sample.yml文件：- name: Deploy uses: azure/sql-action@v2 with: connection-string: ${{ secrets.SQL_CONNECTION_STRING }} action: 'publish' path: 'bin/Debug/MyDatabaseProject.dacpac'在提交更改之前，请将机密添加到包含目标数据库的连接字符串的存储库。 在 GitHub.com 上的存储库中，依次导航到“设置”、“机密”。 选择“新建存储库机密”，并将具有连接字符串值的名为
SQL_CONNECTION_STRING的机密添加到目标数据库。
将更改从
sqlproj-sample.yml提交到存储库，并将更改推送到远程存储库。导航回到 GitHub.com 上的工作流历史记录，然后选择工作流的最新运行。 部署步骤应在工作流运行的步骤列表中可见，且工作流将返回成功代码。
通过连接到目标数据库并检查项目中的对象是否存在于数据库中来验证部署。
GitHub 部署可以通过在工作流中建立环境关系并要求在运行部署之前进行批准来进一步保护这些部署。 Github Actions 文档中提供了有关环境保护和保护机密的详细信息。