Local SQL Server via Docker — WebhookFlow

🧠

Concept

Why run SQL Server locally in Docker?

Fast inner loop — no internet required, instant reset

Analogy: Azure SQL Database is your production filing cabinet in the cloud. The Docker container is an identical filing cabinet in your room — same make, same model, works without Wi-Fi, and if you spill coffee on it you just spin up a new one.

Option	Internet needed	Speed	Reset	Use when
Azure SQL Database	Yes	Slight network latency	Drop + recreate DB in portal	Shared dev, staging, production
Local Docker SQL Server ✓	No (after image pulled)	Fastest — localhost	`docker rm` then re-run	Individual dev, offline, rapid iteration

Identical engine: The Docker image is mcr.microsoft.com/mssql/server:2022-latest — the same SQL Server 2022 engine that powers Azure SQL Database. Your queries, stored procedures, and JDBC driver are 100% compatible. Switching between local and Azure is a one-line change in application.properties.

✅

Before You Start

Prerequisites

1

Docker Desktop running on Windows

Open Docker Desktop and confirm the whale icon in the taskbar shows Docker Desktop is running. If not set up yet, see the Docker Desktop Setup guide.

2

At least 2 GB RAM available

SQL Server requires a minimum of 2 GB RAM. In Docker Desktop → Settings → Resources, ensure at least 3 GB is allocated to Docker.

3

Port 1433 free

Check nothing else is using port 1433 (the default SQL Server port). In PowerShell: netstat -ano | findstr :1433. If it shows a process, stop it first.

🐳

Step 1

Start the SQL Server Container

One command — downloads the image and starts SQL Server

PowerShell — run once (pulls image ~1.5 GB on first run)

docker run `
  -e "ACCEPT_EULA=Y" `
  -e "SA_PASSWORD=Webhook@1234" `
  -p 1433:1433 `
  --name webhookflow-sql `
  -v webhookflow-data:/var/opt/mssql `
  -d `
  mcr.microsoft.com/mssql/server:2022-latest

Flag	What it does
-e "ACCEPT_EULA=Y"	Accept the SQL Server licence agreement (required)
-e "SA_PASSWORD=..."	Set the `sa` (system administrator) password — must be 8+ chars, mixed case, number, symbol
-p 1433:1433	Map container port 1433 to your Windows localhost:1433
--name webhookflow-sql	Give the container a friendly name so you can start/stop by name
-v webhookflow-data:...	Named Docker volume — your data survives container restarts and recreates
-d	Run in background (detached)
mcr.microsoft.com/...	Official Microsoft SQL Server 2022 image from Microsoft Container Registry

✓

Confirm it started

docker ps

You should see a row with webhookflow-sql and status Up. Wait ~10 seconds after starting before connecting — SQL Server takes a moment to initialise.

🗄️

Step 2

Create the webhookflow Database

Run sqlcmd inside the container — takes 30 seconds

1

Open a shell inside the running container

docker exec -it webhookflow-sql /opt/mssql-tools18/bin/sqlcmd `
  -S localhost -U sa -P "Webhook@1234" -No

2

Create the database, then exit

CREATE DATABASE webhookflow;
GO
EXIT

Spring Boot auto-creates the tables. You only need to create the database once. On first startup, JPA reads your @Entity classes and runs CREATE TABLE for webhook_event, webhook_subscription, delivery_log, and event_source automatically.

Optional — connect with Azure Data Studio (GUI)

Field	Value
Server	`localhost,1433`
Authentication type	SQL Login
User name	`sa`
Password	`Webhook@1234`
Database	`webhookflow`
Encrypt connection	Optional (or False)
Trust server certificate	Yes

☕

Step 3

Update application.properties for Local Docker

localhost instead of Azure hostname — no env vars needed

pom.xml is already correct. mssql-jdbc works for both local Docker SQL Server and Azure SQL Database — no dependency change needed.

File: webhook/src/main/resources/application.properties

application.properties — local Docker SQL Server

spring.application.name=webhook

# ── Local SQL Server (Docker) ─────────────────────────────────────────────────
spring.datasource.url=jdbc:sqlserver://localhost:1433;databaseName=webhookflow;encrypt=false;trustServerCertificate=true
spring.datasource.driver-class-name=com.microsoft.sqlserver.jdbc.SQLServerDriver
spring.datasource.username=sa
spring.datasource.password=Webhook@1234

# ── JPA / Hibernate ───────────────────────────────────────────────────────────
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

spring.jpa.open-in-view=false

# ── Server ────────────────────────────────────────────────────────────────────
server.port=8080

Do not commit SA password to git. This config is fine for local development, but before pushing to a shared repo, move the password to a .env file and reference it as ${SA_PASSWORD}, or add application.properties to .gitignore.

✅

Step 4

Verify Connection

1

Start the app

mvn spring-boot:run

2

Watch the log for table creation

HikariPool-1 - Start completed.
Hibernate: create table webhook_event (...
Hibernate: create table webhook_subscription (...
Hibernate: create table delivery_log (...
Hibernate: create table event_source (...
Started WebhookApplication in 3.8 seconds

3

Call the health endpoint

curl http://localhost:8080/health

Expected: {"status":"UP","totalEvents":0}

4

Confirm tables via sqlcmd

docker exec -it webhookflow-sql /opt/mssql-tools18/bin/sqlcmd `
  -S localhost -U sa -P "Webhook@1234" -No `
  -Q "USE webhookflow; SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES;"

Should list 4 tables: webhook_event, webhook_subscription, delivery_log, event_source.

⚡

Reference

Daily Commands

Start, stop, and reset your local SQL Server

Start docker start webhookflow-sql Resume after PC restart

Stop docker stop webhookflow-sql Data is preserved in the volume

Status docker ps Check if container is running

Logs docker logs webhookflow-sql See SQL Server startup messages

Full reset — wipe all data and start clean

Warning: This deletes all tables and data in the local database. Useful when you want a clean slate during development.

# 1. Stop the container
docker stop webhookflow-sql

# 2. Remove the container
docker rm webhookflow-sql

# 3. Remove the data volume
docker volume rm webhookflow-data

# 4. Re-run the original docker run command (recreates everything)
docker run `
  -e "ACCEPT_EULA=Y" `
  -e "SA_PASSWORD=Webhook@1234" `
  -p 1433:1433 `
  --name webhookflow-sql `
  -v webhookflow-data:/var/opt/mssql `
  -d `
  mcr.microsoft.com/mssql/server:2022-latest

# 5. Re-create the database
docker exec -it webhookflow-sql /opt/mssql-tools18/bin/sqlcmd `
  -S localhost -U sa -P "Webhook@1234" -No `
  -Q "CREATE DATABASE webhookflow;"

☁️

Reference

Switch Between Local Docker and Azure SQL

One line change — same driver, same engine

The only difference between local Docker SQL Server and Azure SQL Database is the connection URL in application.properties. Everything else — the JDBC driver, JPA config, entity classes — stays identical.

Local Docker SQL Server

spring.datasource.url=
  jdbc:sqlserver://localhost:1433;
  databaseName=webhookflow;
  encrypt=false;
  trustServerCertificate=true

spring.datasource.username=sa
spring.datasource.password=Webhook@1234

Azure SQL Database

spring.datasource.url=
  jdbc:sqlserver://${AZURE_SQL_SERVER}
  .database.windows.net:1433;
  databaseName=webhookflow;
  encrypt=true;
  trustServerCertificate=false;
  hostNameInCertificate=
  *.database.windows.net;
  loginTimeout=30

spring.datasource.username=sqladmin
spring.datasource.password=
  ${AZURE_SQL_PASSWORD}

Spring profiles tip (advanced): Create application-local.properties with the Docker URL and application-azure.properties with the Azure URL. Switch with -Dspring.profiles.active=local or =azure. This way the main application.properties stays clean with only shared config.

🔧

Reference

Troubleshooting

Error	Cause	Fix
`Connection refused localhost:1433`	Container not running or still starting	Run `docker ps` — if not running, `docker start webhookflow-sql`. Wait 10 sec after start.
`Login failed for user 'sa'`	Wrong password in properties	Password in `application.properties` must match `SA_PASSWORD` used in `docker run`
`Database 'webhookflow' not found`	Database not created inside container	Run the `docker exec ... CREATE DATABASE webhookflow` command from Step 2
Docker Desktop not starting	WSL2 or virtualisation issue	See the Docker Desktop Setup guide for Windows troubleshooting
`Insufficient memory` in Docker logs	Docker has less than 2 GB RAM	Docker Desktop → Settings → Resources → increase Memory to 3 GB
Port 1433 already in use	Another SQL Server instance running on Windows	Stop the other instance, or map to a different port: change `-p 1433:1433` to `-p 1434:1433` and update the JDBC URL to `localhost,1434`
`sqlcmd: command not found` inside container	Tools path changed in newer images	Try `/opt/mssql-tools/bin/sqlcmd` (without the `18`) as the fallback path

Local SQL Server via Dockerfor WebhookFlow

Docker Desktop running on Windows

At least 2 GB RAM available

Port 1433 free

Confirm it started

Open a shell inside the running container

Create the database, then exit

Optional — connect with Azure Data Studio (GUI)

Start the app

Watch the log for table creation

Call the health endpoint

Confirm tables via sqlcmd

Full reset — wipe all data and start clean

Local Docker SQL Server

Azure SQL Database

Local SQL Server via Docker
for WebhookFlow