Udostępnij za pomocą

SqlPackage

SqlPackage to narzędzie wiersza polecenia, które automatyzuje zadania programistyczne bazy danych przez uwidacznianie niektórych publicznych interfejsów API platformy Data-Tier Application Framework (DacFx). Podstawowe przypadki użycia pakietu SqlPackage koncentrują się na przenośności i wdrożeniach bazy danych dla rodziny baz danych sql Server, Azure SQL i Azure Synapse Analytics. Pakiet SqlPackage można zautomatyzować przy użyciu usług Azure Pipelines i GitHub actions lub innych narzędzi ciągłej integracji/ciągłego wdrażania.

Pobierz najnowszą wersję. Aby uzyskać szczegółowe informacje o najnowszej wersji, zobacz informacje o wersji.

Uwaga / Notatka

Chociaż identyfikator Entra firmy Microsoft to nowa nazwa usługi Azure Active Directory (Azure AD), aby zapobiec zakłócaniu działania istniejących środowisk, usługa Azure AD nadal pozostaje w niektórych zakodowanych na stałe elementach, takich jak pola interfejsu użytkownika, dostawcy połączeń, kody błędów i polecenia cmdlet. W tym artykule dwie nazwy są wymienne.

Przenośność

Przenośność bazy danych to możliwość przenoszenia schematu bazy danych i danych między różnymi wystąpieniami programu SQL Server, usługi Azure SQL i usługi Azure Synapse Analytics. Eksportowanie bazy danych z usługi Azure SQL Database do lokalnego wystąpienia programu SQL Server lub z programu SQL Server do usługi Azure SQL Database to przykłady przenośności bazy danych. Pakiet SqlPackage obsługuje przenośność bazy danych za pomocą akcji Eksportowanie i importowanie , które tworzą i zużywają pliki BACPAC. Pakiet SqlPackage obsługuje również przenośność bazy danych za pośrednictwem akcji Wyodrębnianie i publikowanie , które tworzą i zużywają pliki DACPAC, które mogą zawierać dane bezpośrednio lub odwoływać się do danych przechowywanych w usłudze Azure Blob Storage.

  • Export: eksportuje połączoną bazę danych SQL Database — w tym schemat bazy danych i dane użytkownika — do pliku BACPAC (bacpac).

  • Import: importuje dane schematu i tabeli z pliku BACPAC do nowej bazy danych użytkownika.

Wdrożenia

Wdrożenia bazy danych to proces aktualizowania schematu bazy danych w celu dopasowania do żądanego stanu, takiego jak dodawanie kolumn do tabeli lub zmienianie zawartości procedury składowanej. Pakiet SqlPackage obsługuje wdrożenia bazy danych za pomocą akcji Publikowanie i wyodrębnianie . Akcja Publikuj aktualizuje schemat bazy danych, aby był zgodny z zawartością źródłowego pliku dacpac, podczas gdy akcja Wyodrębnij tworzy plik aplikacji warstwy danych (dacpac) zawierający schemat lub schemat i dane użytkownika z połączonej bazy danych SQL. Pakiet SqlPackage umożliwia wdrażanie nowych i istniejących baz danych z tego samego pakietu wdrożeniowego (.dacpac), automatycznie tworząc plan wdrożenia, który wprowadza niezbędne zmiany do docelowej bazy danych. Plan wdrożenia można przejrzeć przed zastosowaniem zmian w docelowej bazie danych za pomocą akcji Script lub DeployReport .

  • Wyodrębnij: Tworzy plik aplikacji warstwy danych (.dacpac) zawierający schemat lub schemat i dane użytkownika z połączonej bazy danych SQL.

  • Publikuj: przyrostowo aktualizuje schemat bazy danych, aby był zgodny ze schematem źródłowego pliku dacpac. Jeśli baza danych nie istnieje na serwerze, operacja publikowania go tworzy. W przeciwnym razie istniejąca baza danych zostanie zaktualizowana.

  • DeployReport: tworzy raport XML reprezentujący zmiany, które zostaną wprowadzone przez akcję publikowania.

  • DriftReport: tworzy raport XML reprezentujący zmiany zastosowane do zarejestrowanej bazy danych od czasu ostatniego zarejestrowania.

  • Skrypt: Tworzy skrypt aktualizacji przyrostowej Transact-SQL, który zmienia schemat obiektu docelowego, aby pasował do schematu źródła.

Składnia wiersza poleceń

Pakiet SqlPackage inicjuje akcje określone przy użyciu parametrów, właściwości i zmiennych SQLCMD określonych w wierszu polecenia.

SqlPackage {parameters} {properties} {SQLCMD variables}

Więcej informacji na temat składni wiersza polecenia sqlPackage znajduje się w dokumentacji interfejsu wiersza polecenia sqlPackage i poszczególnych stronach akcji.

Polecenia narzędzia

wersja

Wyświetla wersję sqlpackage jako numer kompilacji. Może być używany w monitach interakcyjnych i w zautomatyzowanych potokach.

SqlPackage /Version

Pomoc

Informacje o użyciu pakietu SqlPackage można wyświetlić przy użyciu /? lub /help:True.

SqlPackage /?

Aby uzyskać informacje o parametrach i właściwościach specyficznych dla konkretnej akcji, użyj parametru pomocy oprócz parametru tej akcji.

SqlPackage /Action:Publish /?

Uwierzytelnianie

Pakiet SqlPackage uwierzytelnia się przy użyciu metod dostępnych w programie SqlClient. Skonfigurowanie typu uwierzytelniania można wykonać za pomocą parametrów połączenia dla każdej akcji SqlPackage (/SourceConnectionString i /TargetConnectionString) lub poszczególnych parametrów dla właściwości połączenia. Następujące metody uwierzytelniania są obsługiwane w parametrach połączenia:

  • Uwierzytelnianie programu SQL Server
  • Uwierzytelnianie usługi Active Directory (Windows)
  • Uwierzytelnianie Microsoft Entra
    • Nazwa użytkownika/hasło
    • Zintegrowane uwierzytelnianie
    • Uwierzytelnianie uniwersalne
    • Tożsamość zarządzana
    • Główny identyfikator usługi

Tożsamość zarządzana

Uwaga / Notatka

Microsoft Entra ID był wcześniej znany jako Azure Active Directory (Azure AD).

W środowiskach zautomatyzowanych tożsamość zarządzana firmy Microsoft Entra jest zalecaną metodą uwierzytelniania. Ta metoda nie wymaga przekazywania poświadczeń do pakietu SqlPackage w czasie wykonywania, ponieważ pakiet SqlPackage używa tożsamości zarządzanych do łączenia się z bazami danych, które obsługują uwierzytelnianie firmy Microsoft Entra, oraz uzyskiwania tokenów firmy Microsoft Entra bez zarządzania poświadczeniami. Po skonfigurowaniu tożsamości zarządzanej dla środowiska, w którym jest uruchamiana akcja SqlPackage, akcja SqlPackage może używać tej tożsamości do uwierzytelniania w usłudze Azure SQL. Aby uzyskać więcej informacji na temat konfigurowania tożsamości zarządzanej dla środowiska, zobacz dokumentację tożsamości zarządzanej.

Przykładowe parametry połączenia korzystające z tożsamości zarządzanej przypisanej przez system to:

Server=sampleserver.database.windows.net; Authentication=Active Directory Managed Identity; Database=sampledatabase;

Tożsamości zarządzane są obsługiwane zarówno w potokach CI/CD Azure DevOps, jak i GitHub Actions.

Główny identyfikator usługi

Uwaga / Notatka

Microsoft Entra ID był wcześniej znany jako Azure Active Directory (Azure AD).

Główne jednostki usługowe aplikacji Microsoft Entra to obiekty zabezpieczeń w aplikacji Microsoft Entra, które określają, co aplikacja może robić w danej dzierżawie. Są one konfigurowane w witrynie Azure Portal podczas procesu rejestracji aplikacji i skonfigurowane do uzyskiwania dostępu do zasobów platformy Azure, takich jak Azure SQL. Aby uzyskać więcej informacji na temat konfigurowania jednostki usługi dla danego środowiska, zobacz dokumentację jednostki usługi.

Podczas korzystania z SqlPackage z użyciem service principal, można pobrać token dostępu i przekazać go do SqlPackage. Token dostępu można pobrać przy użyciu modułu Azure PowerShell lub interfejsu wiersza polecenia platformy Azure. W tym procesie wywoływany system utrzymuje kontrolę nad odświeżaniem lub unieważnieniem tokenu. Token dostępu można przekazać do pakietu SqlPackage przy użyciu parametru /at .

# example export connecting using an access token associated with a service principal
$Account = Connect-AzAccount -ServicePrincipal -Tenant $Tenant -Credential $Credential
$AccessToken_Object = (Get-AzAccessToken -Account $Account -ResourceUrl "https://database.windows.net/")
$AccessToken = $AccessToken_Object.Token

SqlPackage /at:$AccessToken /Action:Export /TargetFile:"C:\AdventureWorksLT.bacpac" \
    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
# OR
SqlPackage /at:$($AccessToken_Object.Token) /Action:Export /TargetFile:"C:\AdventureWorksLT.bacpac" \
    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"

Alternatywnie możesz przekazać identyfikator klienta jednostki usługi i wpis tajny do pakietu SqlPackage w parametrach połączenia. Format parametrów połączenia zawiera Authentication=Active Directory Service Principal; i User Id=AppId; Password=<password>. Po przekazaniu poświadczeń jednostki usługi w ciągu połączenia, parametr /at nie jest wymagany, a pakiet SqlPackage odświeża uwierzytelnianie zgodnie z potrzebami podczas operacji.

Jednostki usługi są obsługiwane zarówno w potokach ciągłej integracji/ciągłego wdrażania usługi Azure DevOps , jak i GitHub Actions .

Zmienne środowiskowe

Buforowanie połączeń

Buforowanie połączeń można włączyć dla wszystkich połączeń wykonanych przez pakiet SqlPackage, ustawiając zmienną środowiskową CONNECTION_POOLING_ENABLED na True. To ustawienie jest zalecane dla operacji z połączeniami nazwy użytkownika i hasła Microsoft Entra, aby uniknąć ograniczenia przez bibliotekę Microsoft Authentication Library (MSAL).

Pliki tymczasowe

Podczas operacji SqlPackage dane tabeli są zapisywane w plikach tymczasowych przed kompresją lub po dekompresji. W przypadku dużych baz danych te pliki tymczasowe mogą zająć znaczną ilość miejsca na dysku, ale można określić ich lokalizację. Operacje eksportowania i wyodrębniania zawierają opcjonalną właściwość określającą /p:TempDirectoryForTableData , aby zastąpić wartość domyślną programu SqlPackage.

Funkcja GetTempPath interfejsu API platformy .NET służy do określania wartości domyślnej w programie SqlPackage.

W przypadku systemu Windows następujące zmienne środowiskowe są sprawdzane w następującej kolejności i jest używana pierwsza ścieżka:

  1. Ścieżka określona przez zmienną środowiskową TMP .
  2. Ścieżka określona przez zmienną środowiskową TEMP .
  3. Ścieżka określona przez zmienną środowiskową USERPROFILE .
  4. Katalog systemu Windows.

W przypadku systemów Linux i macOS, jeśli ścieżka nie jest określona w zmiennej środowiskowej TMPDIR , używana jest ścieżka /tmp/ domyślna.

SqlPackage i użytkownicy bazy danych

Użytkownicy zawartej bazy danych są uwzględniani w operacjach SqlPackage. Jednak część hasła definicji jest ustawiona na losowy ciąg wygenerowany przez pakiet SqlPackage, istniejąca wartość nie jest przesyłana. Zaleca się zresetowanie hasła nowego użytkownika do bezpiecznej wartości po zaimportowaniu .bacpac elementu lub wdrożenia elementu .dacpac. W zautomatyzowanym środowisku wartości haseł można pobrać z bezpiecznego magazynu kluczy, takiego jak Azure Key Vault, w kroku następującym po wykonaniu SqlPackage.

Rozszerzalność

Pakiet SqlPackage obsługuje rozszerzalność za pośrednictwem programu Managed Extensibility Framework (MEF), umożliwiając zaawansowane scenariusze za pośrednictwem składników niestandardowych nazywanych współautorami. Te rozszerzenia mogą dostosowywać sposób publikowania .dacpac plików przez pakiet SqlPackage, umożliwiając zespołom wymuszanie standardów lub automatyzowanie logiki specyficznej dla projektu. Składniki wdrożeniowe są uruchamiane w ramach procesu publikowania po tym jak plan wdrożenia został wygenerowany, ale przed jego wykonaniem. Ci współautorzy mogą uzyskiwać dostęp do planu wdrożenia i modyfikować go przy użyciu DeploymentPlanModifier obiektu klasy, aby dodawać, usuwać lub zmieniać kolejność kroków. Aby rozpocząć pracę z rozszerzalnością wdrożenia, zobacz Dostosowywanie kompilacji i wdrażania bazy danych za pomocą współautorów wdrażania.

Pakiet SqlPackage odnajduje i ładuje zestawy rozszerzeń poprzez skanowanie bibliotek łącz dynamicznych (.dll plików) w tym samym katalogu co plik wykonywalny SqlPackage oraz lokalizacje określone za pomocą opcjonalnej właściwości wiersza polecenia /p:AdditionalDeploymentContributorPaths. Chociaż umożliwia to elastyczne dostosowywanie, wprowadza również ważne zagadnienia dotyczące zabezpieczeń.

Ważne

Ponieważ pakiet SqlPackage używa narzędzia MEF do dynamicznego ładowania bibliotek (.dll plików) w czasie wykonywania, wszystkie zestawy umieszczone obok pliku wykonywalnego SqlPackage mogą być wykonywane w ramach procesu wdrażania. Złośliwy aktor może wykorzystać to zachowanie, wprowadzając naruszone lub nieautoryzowane rozszerzenia, które wykonują dowolny kod.

Twoim zadaniem jest upewnienie się, że wszystkie skompilowane pliki rozszerzeń używane z pakietem SqlPackage są bezpieczne i pochodzą z zaufanych źródeł. Zalecamy kontrolowanie dostępu do folderu SqlPackage i weryfikowanie integralności wszystkich komponentów niestandardowych lub pochodzących od innych firm.

Zbieranie danych użycia

Pakiet SqlPackage zawiera funkcje obsługujące Internet, które mogą zbierać i wysyłać anonimowe dane użycia funkcji i danych diagnostycznych do firmy Microsoft.

Pakiet SqlPackage może zbierać standardowe informacje o komputerze, użyciu i wydajności, które mogą być przesyłane do firmy Microsoft i analizowane w celu poprawy jakości, bezpieczeństwa i niezawodności pakietu SqlPackage.

Pakiet SqlPackage nie zbiera informacji osobistych ani specyficznych dla użytkownika. Aby ułatwić przybliżenie pojedynczego użytkownika do celów diagnostycznych, pakiet SqlPackage generuje losowy identyfikator GUID dla każdego uruchomionego komputera i używa tej wartości dla wszystkich wysyłanych zdarzeń.

Aby uzyskać szczegółowe informacje, zobacz Zasady zachowania poufności informacji firmy Microsofti Dodatek dotyczący ochrony prywatności programu SQL Server.

Wyłączanie raportowania telemetrii

Aby wyłączyć zbieranie i raportowanie danych telemetrycznych, zaktualizuj zmienną środowiskową DACFX_TELEMETRY_OPTOUT na true lub 1.

Wsparcie

Biblioteka DacFx i narzędzie interfejsu wiersza polecenia SqlPackage są zgodne z zasadami nowoczesnego cyklu życia firmy Microsoft. Wszystkie aktualizacje zabezpieczeń, poprawki i nowe funkcje są wydawane tylko w najnowszej podwersji wersji głównej. Utrzymywanie instalacji DacFx lub SqlPackage w bieżącej wersji pomaga zapewnić, że wszystkie odpowiednie poprawki usterek są odbierane w odpowiednim czasie.

Uzyskaj pomoc dotyczącą pakietu SqlPackage, przesyłania żądań funkcji i zgłaszania problemów w repozytorium GitHub DacFx.

Obsługiwane rozwiązania SQL

Programy SqlPackage i DacFx obsługują wszystkie obsługiwane wersje SQL w momencie wydania SqlPackage/DacFx. Na przykład wersja sqlPackage z 14 stycznia 2022 r. obsługuje wszystkie obsługiwane wersje programu SQL w styczniu 14 2022 r. Aby uzyskać więcej informacji na temat zasad pomocy technicznej sql, zobacz zasady pomocy technicznej SQL.

Oprócz programu SQL Server pakiet SqlPackage i narzędzie DacFx obsługują usługi Azure SQL Managed Instance, Azure SQL Database, Azure Synapse Analytics i Fabric Data Warehouse.

Dalsze kroki

  • Last updated on