Bangun secara lokal dengan wadah Azure SQL Database dan kontainer SQL Server

Buat dan kelola database lokal tanpa menulis perintah kontainer dengan menggunakan ekstensi MSSQL untuk Visual Studio Code. Pilih wadah Azure SQL Database (Pratinjau) untuk dibangun melawan mesin Azure SQL Database di komputer Anda sendiri, atau kontainer SQL Server untuk pengembangan SQL Server. Mulai, berhenti, sambungkan kembali, dan hapus kontainer Anda dari ekstensi.

Untuk aplikasi baru yang menargetkan Azure SQL Database, mulai dengan kontainer Azure SQL Database. Aplikasi ini gratis untuk pengembangan dan pengujian lokal, tidak memerlukan langganan Azure atau kartu kredit, dan bekerja dengan driver serta object-relational mapper (ORM) yang Anda gunakan untuk Azure SQL Database.

Nota

kontainer Azure SQL Database berada dalam pratinjau publik. Mendukung perangkat x64 dan ARM.

Apa itu kontainer Azure SQL Database?

Sebuah kontainer mengemas mesin basis data sehingga runtime kontainer dapat menjalankannya di komputer Anda. Ekstensi MSSQL membimbing Anda melalui pengaturan, mengunduh gambar, memulai mesin, dan menyimpan koneksi. Aplikasi Anda terhubung ke alamat lokal seperti localhost,1433, bukan server logis Azure SQL.

Kontainer Azure SQL Database menjalankan mesin Azure SQL Database, bukan image kontainer SQL Server. Ini mendukung Azure SQL Database T-SQL dan protokol Aliran Data Tabular (TDS) yang digunakan oleh driver SQL. Misalnya, SERVERPROPERTY('EngineEdition') mengembalikan 5, mengidentifikasi mesin Azure SQL Database. vektor native, pencarian vektor, dan JSON membantu Anda menjelajahi skenario data siap AI secara lokal.

Kontainer tidak menyediakan layanan cloud terkelola. pencadangan yang dikelola Azure, ketersediaan tinggi, kumpulan elastis, dan jeda otomatis serverless adalah kemampuan cloud, bukan fitur kontainer lokal. Sebelum penerapan, uji dengan Azure SQL Database di Azure: pembatasan pratinjau, default, dan dukungan fitur bisa berbeda-beda. Lihat batasan yang diketahui.

Pilih database pengembangan Anda

Gunakan opsi yang sesuai dengan target aplikasi Anda, daripada memperlakukan dua gambar kontainer sebagai saling menggantikan.

Option Pilih saat Persyaratan biaya dan akun
Kontainer Azure SQL Database (Pratinjau) Anda ingin belajar SQL atau membangun dan menguji aplikasi yang menargetkan Azure SQL Database secara lokal. Mendukung X64 dan ARM. Direkomendasikan untuk alur kerja pengembangan lokal ini. Gratis untuk pengembangan dan pengujian lokal. Tidak diperlukan langganan Azure atau kartu kredit.
Kontainer SQL Server Aplikasi Anda menargetkan SQL Server atau membutuhkan perilaku khusus SQL Server. Hanya mendukung X64. Gunakan edisi yang dilisensikan untuk skenario Anda. Tidak diperlukan langganan Azure untuk pengembangan lokal.
Azure SQL Database tingkat gratis Anda menginginkan database terkelola di Azure, integrasi cloud, atau lingkungan validasi cloud. Memerlukan langganan Azure. Tunjangan bulanan, persyaratan kelayakan, serta perilaku jeda atau kelebihan penggunaan berbayar berlaku.

Penting

Azure SQL Database kontainer adalah untuk pengembangan, pengujian, CI, dan demo, bukan produksi. Untuk produksi, terapkan aplikasi Anda dan tempatkan database Anda di Azure SQL Database di Azure. Kontainer lokal gratis dan Azure SQL Database tingkat gratis merupakan dua opsi yang terpisah.

Prerequisites

Untuk kontainer Azure SQL Database, Anda membutuhkan:

  • Visual Studio Code.
  • Rilis ekstensi MSSQL terkini yang mencakup kontainer Azure SQL Database (Preview).
  • Runtime kontainer yang didukung terinstal dan menjalankan kontainer Linux. Wizard Azure SQL Database mendeteksi engine yang tersedia dan memeriksa prasyaratnya. Opsi termasuk Docker, Podman, containerd dengan nerdctl, dan kontainer WSL di Windows.
  • Sumber daya yang cukup untuk mesin database. Alokasikan setidaknya 4 GB memori dan dua inti CPU ke runtime kontainer, dan pertahankan setidaknya 10 GB ruang disk kosong untuk image dan database kecil. Dataset yang lebih besar membutuhkan ruang disk yang lebih besar.
  • Akses internet untuk unduhan gambar awal. Setelah Anda cache gambar, kueri lokal tidak memerlukan database cloud. Titik akhir AI eksternal dan layanan online lainnya masih memerlukan konektivitas.

Image Azure SQL Database menyediakan varian native linux/amd64 dan linux/arm64 untuk host x64 dan ARM64. Anda dapat mengembangkan di macOS, Linux, atau Windows dengan WSL2. Kontainer SQL Server memiliki persyaratan image dan runtime yang terpisah.

Membuat kontainer Azure SQL Database

  1. Di tampilan Connections ekstensi MSSQL, pilih New Deployment dan Azure SQL Database container (Preview).

    Tangkapan layar tampilan Connections dengan aksi toolbar New Deployment disorot.

    Tangkapan layar halaman SQL database Baru dengan opsi pratinjau kontainer lokal Azure SQL Database yang disorot.

  2. Tinjau gambaran kontainer pengembang, lalu pilih Berikutnya. Wizard memeriksa mesin yang Anda pasang. Jika wizard tidak menemukan engine, gunakan tautan instalasi yang disediakan untuk menginstal engine, lalu coba ulang pemeriksaan. Setelah pemeriksaan prasyarat berhasil, pilih Berikutnya.

    Tangkapan layar ikhtisar kontainer Azure SQL Database yang menjelaskan pengembangan lokal, gambar native ARM dan x64, serta opsi mesin kontainer.

    Tangkapan layar halaman prasyarat mesin kontainer yang menunjukkan Docker terdeteksi dan pemeriksaan instalasi, startup, dan konfigurasi selesai.

  3. Konfigurasikan koneksi Anda dengan kata sandi kuat minimal delapan karakter (huruf besar, huruf kecil, angka, dan simbol). Tinjau dan terima Syarat & Ketentuan, lalu pilih Next untuk memprovisikan kontainer.

    Tangkapan layar konfigurasi kontainer dengan SQL Login, kata sandi tersembunyi, nama profil, opsi lanjutan, port 1436, dan kotak centang syarat lisensi.

  4. Tunggu hingga unduhan gambar, pembuatan kontainer, kesiapan mesin, dan koneksi selesai.

    Tangkapan layar penyediaan dengan unduhan image, pembuatan kontainer, kesiapan, dan langkah koneksi selesai.

  5. Temukan koneksi yang disimpan di Object Explorer pada tampilan Koneksi.

    Tangkapan layar koneksi kontainer Azure SQL DB yang berjalan di Object Explorer dengan node Database dan Keamanan.

Ekstensi membuat profil koneksi yang disimpan. Kontainer, profil koneksi, dan basis data aplikasi adalah sumber daya yang berbeda: memulai mesin tidak berarti basis data aplikasi Anda sudah ada. Lanjutkan dengan langkah-langkah berikut untuk membuatnya secara eksplisit.

Wizard ini juga menawarkan autentikasi Microsoft Entra untuk skenario yang lebih lanjut. Ini memerlukan konfigurasi identitas dan sertifikat tambahan.

Buat database dan jalankan kueri pertama Anda

Gunakan appdb sebagai contoh nama database. Ganti nama database proyek Anda secara konsisten jika Anda memilih nama lain.

  1. Di Object Explorer, klik kanan koneksi kontainer Anda dan pilih Create Database.

  2. Dalam dialog Buat Database, masukkan appdb di Nama Database.

    Tangkapan layar dialog Create Database untuk kontainer lokal Azure SQL Database, dengan Nama Database dan pengaturan lanjutan.

  3. Gunakan Add Connection untuk terhubung ke server lokal dan port yang sama dengan Database diatur ke appdb. Buka editor kueri baru dengan koneksi ini dan jalankan:

    SELECT DB_NAME() AS current_database,
        SERVERPROPERTY('EngineEdition') AS engine_edition,
        SERVERPROPERTY('Edition') AS edition;
    

    Harapkan current_database untuk menjadi appdb, engine_edition menjadi 5, dan edition menjadi SQL Azure. Jika edisinya berbeda, periksa apakah Anda memilih kontainer Azure SQL Database, bukan SQL Server. Pilih database di pengaturan koneksi, bukan dengan USE appdb. Sesi user-database Azure SQL Database tidak mendukung pergantian database dengan USE.

  4. Jalankan masing-masing pernyataan ini secara terpisah di appdb. Berhenti jika pernyataan gagal. Jika dbo.Tasks sudah ada, pilih nama tabel yang berbeda secara konsisten atau database pengembangan yang berbeda; jangan menimpanya.

    CREATE TABLE dbo.Tasks
    (
        TaskId INT IDENTITY (1, 1) NOT NULL PRIMARY KEY,
        Title NVARCHAR (200) NOT NULL,
        IsComplete BIT NOT NULL DEFAULT (0)
    );
    
    INSERT INTO dbo.Tasks (Title)
    VALUES (N'Create a local Azure SQL Database'),
           (N'Connect an application');
    
    SELECT TaskId, Title, IsComplete
    FROM dbo.Tasks
    ORDER BY TaskId;
    

    Setelah satu operasi insert berhasil, akan ada dua baris dengan TaskId nilai 1 dan 2, dan IsComplete disetel ke 0.

Jika Anda lebih suka SQL untuk pembuatan database, hubungkan editor kueri ke master dan jalankan CREATE DATABASE appdb; daripada menggunakan dialog Create Database.

Gunakan master untuk provisi database dan database pengguna Anda untuk kueri aplikasi. Menghubungkan ke database yang tidak ada tidak membuatnya tidak tercipta, dan container tidak secara otomatis menjalankan skrip inisialisasi dari /docker-entrypoint-initdb.d.

Mengimpor skema dan data Anda

Jika Anda sudah memiliki paket database, gunakan operasi DACPAC dan BACPAC milik ekstensi tersebut alih-alih membangun ulang skema secara manual.

Package Isinya Operation
.dacpac Skema database. Itu tidak termasuk data tabel Anda. Publikasikan DACPAC untuk mendistribusikan skema ke database pengembangan baru atau yang sudah ada.
.bacpac Skema database dan data tabel. Impor BACPAC ke dalam database pengembangan baru atau kosong.
  1. Klik kanan koneksi kontainer Anda di Object Explorer, lalu pilih DACPAC/BACPAC Operations....

    Tangkapan layar menu koneksi kontainer dengan Operasi DACPAC/BACPAC yang disorot dan tindakan Stop SQL Container serta Delete SQL Container terlihat.

  2. Pilih operasi yang sesuai dengan paket Anda, pilih file paket, dan konfirmasi koneksi kontainer target serta basis data.

  3. Tinjau target dan perubahan yang diusulkan sebelum melanjutkan. Tunggu hingga operasi selesai, lalu segarkan Database dan hubungkan langsung ke database pengguna target untuk memeriksa skema dan datanya.

Jangan impor BACPAC ke appdb setelah membuat tabel contoh dbo.Tasks: database tersebut tidak kosong. Pilih database pengembangan yang baru atau yang kosong sebagai gantinya. Publikasikan hanya skema yang kompatibel dengan Azure SQL Database, dan tinjau perubahan sebelum menerapkannya ke database dengan data yang Anda butuhkan.

Nota

File SQL Server .bak bukanlah file BACPAC; BACKUP DATABASE dan RESTORE DATABASE tidak didukung oleh kontainer Azure SQL Database.

Hubungkan aplikasi Anda

Gunakan alamat server lokal, port host yang dipilih oleh wizard, nama database Anda, dan kredensial Anda dengan driver yang kompatibel dengan Azure SQL. Misalnya, string koneksi bergaya ADO.NET ini menargetkan appdb:

Server=localhost,<host-port>;Database=appdb;User ID=sa;Password=<your-password>;Encrypt=True;TrustServerCertificate=True;

Ganti kedua placeholder sebelum menghubungkan. TrustServerCertificate=True adalah untuk sertifikat kontainer lokal yang ditandatangani sendiri saja. Gunakan validasi sertifikat dan metode autentikasi yang sesuai, seperti autentikasi Microsoft Entra, untuk Azure SQL Database di Azure.

Simpan string koneksi dalam variabel lingkungan atau penyimpanan rahasia pengembangan, bukan repositori kode sumber atau prompt AI. Driver lain menggunakan sintaks connection-string yang berbeda; lihat quickstart untuk Python dan .NET.

Mengembangkan dengan AI

Anda dapat menggunakan GitHub Copilot di ekstensi MSSQL untuk menjelaskan SQL, membuat draf kueri, dan merencanakan perubahan skema terhadap database lokal Anda. Tinjau SQL yang dihasilkan dan database yang dipilih sebelum menjalankannya. Penggunaan kontainer gratis; GitHub Copilot dan layanan model eksternal memiliki persyaratan akses dan harga masing-masing.

Misalnya, setelah membuat dbo.Tasks, berikan prompt ini pada Copilot:

I'm developing against an Azure SQL Database container, not SQL Server.
Use my existing appdb connection. First confirm the active database and
EngineEdition = 5. Explain the dbo.Tasks schema, then draft a parameterized
query to insert a task and a query to list incomplete tasks.
Don't execute changes, delete data, or create cloud resources.
Don't request or display passwords. Don't use USE to switch databases.

Untuk alur kerja code-first, keterampilan agen kontainer Azure SQL Database menyediakan penyiapan, koneksi, migrasi, dan panduan lokal ke cloud untuk agen pengodean AI yang didukung.

Coba kesamaan vektor tanpa layanan embedding

Jalankan contoh ini pada koneksi Anda appdb untuk mengeksplorasi native vectors dan pencarian kesamaan yang tepat. Aplikasi ini menggunakan vektor tiga dimensi ilustratif, tidak membuat tabel, dan tidak memanggil endpoint model berbayar.

DECLARE @query VECTOR(3) = '[1.0, 0.0, 0.0]';

SELECT TOP (2)
       v.Label,
       VECTOR_DISTANCE('cosine', CAST(v.Embedding AS VECTOR(3)), @query) AS distance
FROM (VALUES
    (N'Closest', '[1.0, 0.0, 0.0]'),
    (N'Perpendicular', '[0.0, 1.0, 0.0]')
) AS v(Label, Embedding)
ORDER BY distance;

Harapkan Closest terlebih dahulu dengan jarak 0, diikuti dengan Perpendicular jarak 1. Dalam aplikasi nyata, hasilkan embedding dengan model yang sama untuk data dan query yang tersimpan, lalu gunakan dimensi embedding model tersebut. VECTOR_DISTANCE melakukan pencarian tepat; tidak menggunakan indeks vektor. Tinjau batasan pratinjau sebelum memilih strategi pengindeksan atau penyematan.

Fitur

Pengalaman kontainer lokal menyediakan kemampuan berikut:

  • Buat kontainer Azure SQL Database atau SQL Server melalui panduan wizard.
  • Sesuaikan nama kontainer, nama host, dan port.
  • Periksa prasyarat runtime kontainer sebelum deployment.
  • Tetapkan port yang tersedia secara otomatis jika 1433 sudah digunakan.
  • Simpan pengaturan koneksi untuk disambungkan kembali.
  • Kelola siklus hidup kontainer dari tampilan Koneksi .

Buat kontainer SQL Server

Tangkapan layar berikut menggambarkan wizard SQL Server, bukan wizard Azure SQL Database.

  1. Buka wizard penyebaran dan pilih kontainer SQL Server di bawah Jalankan secara lokal. Anda juga dapat menggunakan Create Local SQL Container dari menu Connections .

    Tangkapan layar yang menunjukkan opsi pembuatan kontainer SQL Server di ekstensi MSSQL.

  2. Tinjau layar ikhtisar dan pilih Mulai.

    Tangkapan layar layar ikhtisar untuk penerapan kontainer SQL Server lokal dengan tautan yang membantu dan tombol Mulai.

  3. Ekstensi MSSQL secara otomatis memeriksa Docker sebelum penyebaran:

    • Jika Docker tidak diinstal, pesan dengan tautan penginstalan akan muncul. Anda harus menginstalnya sebelum melanjutkan.
    • Jika Docker diinstal tetapi tidak berjalan, Anda akan diminta untuk memulainya. Jika memulai Docker gagal, coba lagi atau batalkan.

    Saat semua prasyarat terpenuhi, pilih Berikutnya.

    Tangkapan layar pemeriksaan prasyarat Docker wizard SQL Server di ekstensi MSSQL.

  4. Di panel Pengaturan penyebaran :

    1. Pilih versi SQL Server (SQL Server 2025 (17.x) dipilih secara default).
    2. Masukkan kata sandi untuk akun tersebut sa .
    3. Masukkan nama untuk profil koneksi Anda (opsional).
    4. Secara opsional, atur nama kontainer, port, dan nama host di bawah opsi lanjutan.
    5. Terima persyaratan lisensi.
    6. Pilih Buat Kontainer.

    Tangkapan layar formulir konfigurasi pengaturan kontainer.

Cara kerja penyebaran kontainer SQL

Untuk SQL Server, setelah Anda memilih Create Container, ekstensinya:

  • Menarik gambar SQL Server yang dipilih (jika belum di-cache).
  • Membuat kontainer SQL Server dengan pengaturan yang dipilih.
  • Memantau log untuk memverifikasi bahwa semua database sepenuhnya pulih dan siap.
  • Membuat profil koneksi dan menyambungkan ke kontainer Anda.

Setelah deployment selesai, ekstensi MSSQL tersambung ke kontainer. Buat atau pilih database pengguna sebelum menjalankan query aplikasi.

Mengelola kontainer Anda

Untuk kedua jenis kontainer, klik kanan profil koneksi yang disimpan di tampilan Connections untuk mengelola siklus hidupnya.

Tangkapan layar berikut menunjukkan kontainer Azure SQL Database yang dihentikan. Menu ini menawarkan Start SQL Container dan Delete SQL Container. Saat kontainer berjalan, menu menawarkan Stop SQL Container sebagai gantinya.

Tangkapan layar dari kontainer Azure SQL Database yang dihentikan dengan Start SQL Container dan Hapus SQL Container di menu koneksinya.

Memulai kontainer yang dihentikan

Pilih Mulai Kontainer SQL. Ekstensi memeriksa runtime terkait dan memulai kontainer sebelum terhubung. Jika runtime tidak berjalan, ikuti prompt untuk memulainya.

Menghentikan kontainer yang sedang berjalan

Pilih Stop SQL Container untuk melepaskan sumber daya kontainer yang berjalan tanpa menghapusnya. File database tetap tersedia saat Anda memulai ulang kontainer yang sama. Tindakan ini menghentikan container, bukan jeda otomatis serverless Azure SQL Database.

Menghapus kontainer

Pilih Hapus Kontainer SQL, dan tinjau konfirmasi sebelum melanjutkan. Penghapusan akan menghapus kontainer dan profil koneksi yang dipilih. Data yang hanya disimpan di dalam kontainer hilang; volume yang dikelola secara terpisah memiliki siklus hidup sendiri. Simpan data yang Anda butuhkan sebelum penghapusan.

Penting

Jangan hapus wadah atau penyimpanannya untuk memecahkan masalah koneksi kecuali Anda bisa membuang datanya. Jika Anda hanya ingin menjeda pengembangan, hentikan saja.

Skenario yang didukung

Gunakan kontainer Azure SQL Database untuk membuat prototipe aplikasi, menguji migrasi, mempelajari T-SQL, dan mengeksplorasi vektor serta JSON sebelum deployment ke cloud. Anda juga dapat menggunakan citra kontainer di CI, sidecar aplikasi, atau lab offline; alur kerja yang khusus untuk runtime tersebut tidak dikonfigurasi oleh wizard VS Code.

Gunakan kontainer SQL Server untuk menguji skema dan fitur SQL Server. Jangan berasumsi bahwa fitur khusus SQL Server berfungsi di Azure SQL Database hanya karena fitur tersebut berfungsi di kontainer SQL Server.

Memecahkan masalah pengembangan lokal

Gejala Apa yang harus diperiksa
Opsi kontainer Azure SQL Database tidak ada. Perbarui ekstensi MSSQL ke rilis yang menyertakan panduan pratinjau publik, lalu pilih New Deployment lagi.
Pemeriksaan prasyarat runtime gagal. Pastikan runtime yang dipilih sudah terpasang, berjalan, dan dikonfigurasi untuk kontainer Linux. Perbaiki masalah yang dilaporkan dan coba ulang.
Unduhan gambar gagal. Tinjau kesalahan registry dan periksa konektivitas dan konfigurasi runtime. Jangan mengganti citra SQL Server dengan Azure SQL Database.
Kontainer menyala tetapi koneksi gagal. Tunggu kesiapan mesin, lalu periksa detail kesalahan dan log kontainer. Periksa kompleksitas kata sandi dan alokasi memori. Proses kontainer yang berjalan tidak membuktikan bahwa database sudah siap.
Sebuah aplikasi tidak dapat mengakses database. Gunakan port host yang sebenarnya dipilih oleh wizard, bukan asumsi 1433. localhost mengacu pada host aplikasi itu sendiri; sebuah aplikasi di kontainer lain membutuhkan alamat jaringan kontainer yang sesuai.
Database tidak ada. Hubungkan ke master, buat database, dan sambungkan kembali langsung ke sana.
USE appdb gagal. Pilih appdb di pengaturan koneksi. Jangan beralih database dalam sesi user-database Azure SQL Database dengan USE.
Operasi manajemen SQL Server gagal. Periksa apakah operasi didukung oleh Azure SQL Database. Misalnya, BACKUP DATABASE dan RESTORE DATABASE tidak didukung.

Lihat keterbatasan yang diketahui untuk kekurangan pada pratinjau dan solusi sementara saat ini.

Membersihkan data sampel

Pada koneksi Anda appdb, konfirmasi SELECT DB_NAME() mengembalikan appdb. Jika Anda membuat dbo.Tasks di panduan ini dan tidak lagi membutuhkannya, hapus hanya tabel contoh tersebut:

DROP TABLE dbo.Tasks;

Jangan jalankan pernyataan ini pada tabel dari proyek lain. Hentikan kontainer agar dapat terus menggunakannya nanti, atau hapus hanya ketika Anda tidak lagi membutuhkan datanya.

Berpindah dari lokal ke cloud

  • Dengan menggunakan ekstensi MSSQL, Anda dapat men-deploy database lokal Anda ke cloud. Pelajari lebih lanjut dari Local ke Cloud.