Edit

Share via

Local SQL Server container (Preview)

The Local SQL Server container feature in the MSSQL extension for Visual Studio Code simplifies local development by allowing developers to spin up fully configured SQL Server containers without writing a single Docker command. You can deploy and manage containers directly from the Connections view. This new capability is perfect for prototyping, developing, or testing workloads using the same database engine available in production environments.

Screenshot showing animation of Local Container wizard part one.

By default, the container wizard uses SQL Server 2025 (17.x) Preview, which includes AI-ready capabilities such as vector data types and JSON functions. You can also choose from SQL Server 2022 (16.x), SQL Server 2019 (15.x), or SQL Server 2017 (14.x), depending on your testing needs.

Screenshot showing animation of Local Container wizard part two.

Note

The Local SQL Server container experience works on macOS, Windows, and Linux, as long as Docker Desktop (or an equivalent) is running in Linux container mode.

Features

Local SQL Server container in the MSSQL extension provides the following capabilities:

  • Create a local SQL Server container without writing Docker commands.
  • Choose from multiple SQL Server versions (SQL Server 2025 (17.x) Preview (default), SQL Server 2022 (16.x), SQL Server 2019 (15.x)), and SQL Server 2017 (14.x)).
  • Customize the container name, hostname, and port.
  • Automatically check Docker installation and running status before deployment.
  • Automatically assign an available port if 1433 is already in use.
  • Autoconnect and persist connection settings across container restarts.
  • Manage the container lifecycle (start, stop, delete) from the context menu in the Connections view.
  • Use with all core MSSQL extension features, including Object Explorer, Table Designer, Schema Designer, Query Editor, and GitHub Copilot.

Important

Local containers are intended for development only. Production deployments aren't supported.

Create a local container

To create a local SQL Server container:

  1. In the Connections view, select the Create local SQL Container option from the menu.

    Screenshot showing how to create local SQL Server container option in the MSSQL extension.

  2. Review the Overview screen, which highlights what you can expect from the local SQL Server container experience.

    When you're ready, select Get Started to continue.

    Screenshot of the overview screen for local SQL Server container deployment with helpful links and Get Started button.

  3. The MSSQL extension automatically checks for Docker before deployment:

    • If Docker isn't installed, a message with an install link appears. You must install it before continuing.
    • If Docker is installed but not running, you're prompted to start it. If starting Docker fails, retry or cancel.

    Once all prerequisites are met, select Next to continue with deployment.

    Screenshot of Docker prerequisite check-in MSSQL extension.

  4. In the Deployment settings panel:

    1. Select the SQL Server version (SQL Server 2025 (17.x) Preview is selected by default).
    2. Enter a password for the sa account.
    3. Enter a name for your connection profile (optional).
    4. Optionally complete the advanced options:
      • Container name
      • Port
      • Hostname
    5. Accept the license terms.
    6. Select Create Container.

    Screenshot of container setup configuration form.

How SQL container deployment works

After you select Create Container, the extension handles everything for you:

  • Pulls the selected SQL Server image (if not already cached)
  • Creates a SQL Server container with the chosen settings
  • Monitors the logs to verify that all databases are fully recovered and ready
  • Creates a connection profile and connects to your container

After deployment completes, the container starts, and the MSSQL extension autoconnects to the new database.

Manage your container

To manage the container, right-click the connection profile name in the Connections view. From the context menu, you can:

Start a stopped container

The extension checks if Docker is running before starting the container. If Docker isn't running, you're prompted to start it.

Stop a running container

This option shuts down the container while preserving your database state. You can restart it anytime from the same menu.

Delete the container

This option permanently removes the container and its data. You're asked to confirm before proceeding.

Screenshot showing how to manage container lifecycle in the MSSQL extension.

Important

Deleting a container also removes its associated connection profile.

Automatic reconnect experience

If your container or Docker isn't running when you reconnect, the extension prompts you to start them. There's no need to troubleshoot manually.

Supported scenarios

You can use local SQL Server container with all core features of the MSSQL extension:

  • Query Editor and IntelliSense
  • Table Designer and Schema Designer
  • GitHub Copilot
  • Object Explorer and connection management

This feature makes local SQL Server container ideal for:

  • Prototyping new features
  • Testing schema changes
  • Running automated tests in isolated environments
  • Experimenting with SQL Server 2025 (17.x) Preview features

Limitations

  • Requires Docker Desktop (or equivalent) to be installed and running.
  • Only Linux-based SQL Server containers are supported (SQL Server 2017 (14.x) and later versions).
  • No support for Podman.
  • Backup/restore, clustering, script initialization, and Docker Compose aren't supported via the built-in wizard, but you can perform these tasks manually using external tools or commands.
  • Designed strictly for local development—not for production use.
  • Issues with Docker installation, configuration, or runtime must be resolved by the user.
  • Make sure your computer has sufficient resources, or adjust Docker's memory allocation and the container's resource limits via Docker settings to ensure stable performance.
  • Memory requirements:
    • SQL Server needs at least 2 GB of memory to start a Linux-based container.
    • By default, SQL Server on Linux will use approximately 80% of the memory available to the container.

Related content