0
# Testcontainers MSSQL Server
1
2
Testcontainers implementation for Microsoft SQL Server providing lightweight, throwaway database instances for Java tests using Docker containers. Supports both traditional JDBC and reactive R2DBC connectivity patterns with automatic license handling and secure configuration.
3
4
## Package Information
5
6
- **Package Name**: org.testcontainers:mssqlserver
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `implementation 'org.testcontainers:mssqlserver:1.21.3'` (Gradle) or `<dependency><groupId>org.testcontainers</groupId><artifactId>mssqlserver</artifactId><version>1.21.3</version></dependency>` (Maven)
10
11
## Core Imports
12
13
```java
14
import org.testcontainers.containers.MSSQLServerContainer;
15
import org.testcontainers.containers.MSSQLServerContainerProvider;
16
import org.testcontainers.containers.MSSQLR2DBCDatabaseContainer;
17
import org.testcontainers.containers.MSSQLR2DBCDatabaseContainerProvider;
18
```
19
20
## Basic Usage
21
22
```java
23
import org.testcontainers.containers.MSSQLServerContainer;
24
import org.testcontainers.junit.jupiter.Container;
25
import org.testcontainers.junit.jupiter.Testcontainers;
26
27
@Testcontainers
28
public class DatabaseTest {
29
30
@Container
31
static MSSQLServerContainer<?> mssqlserver = new MSSQLServerContainer<>("mcr.microsoft.com/mssql/server:2019-latest")
32
.acceptLicense()
33
.withPassword("MyStr0ngPassword!");
34
35
@Test
36
void testConnection() throws SQLException {
37
String jdbcUrl = mssqlserver.getJdbcUrl();
38
String username = mssqlserver.getUsername();
39
String password = mssqlserver.getPassword();
40
41
try (Connection conn = DriverManager.getConnection(jdbcUrl, username, password)) {
42
// Test database operations
43
}
44
}
45
}
46
```
47
48
## Architecture
49
50
The MSSQL Server module is built around several key components:
51
52
- **JDBC Container**: `MSSQLServerContainer` provides traditional JDBC database access with automatic configuration
53
- **R2DBC Container**: `MSSQLR2DBCDatabaseContainer` offers reactive database access using R2DBC drivers
54
- **Provider Pattern**: Container providers enable framework integration and factory-based container creation
55
- **License Management**: Automatic handling of Microsoft SQL Server license acceptance requirements
56
- **Security Features**: Password strength validation and secure connection configurations
57
58
## Capabilities
59
60
### JDBC Database Container
61
62
Main container class for Microsoft SQL Server providing traditional JDBC connectivity with automatic configuration and lifecycle management.
63
64
```java { .api }
65
public class MSSQLServerContainer<SELF extends MSSQLServerContainer<SELF>> extends JdbcDatabaseContainer<SELF> {
66
// Public constants
67
@Deprecated
68
public static final String DEFAULT_TAG = "2017-CU12";
69
public static final String NAME = "sqlserver";
70
public static final String IMAGE = "mcr.microsoft.com/mssql/server";
71
public static final Integer MS_SQL_SERVER_PORT = 1433;
72
73
// Package-private constants (accessible in same package)
74
static final String DEFAULT_USER = "sa";
75
static final String DEFAULT_PASSWORD = "A_Str0ng_Required_Password";
76
77
// Constructors
78
@Deprecated
79
public MSSQLServerContainer();
80
public MSSQLServerContainer(String dockerImageName);
81
public MSSQLServerContainer(DockerImageName dockerImageName);
82
83
// Configuration methods
84
public SELF acceptLicense();
85
public SELF withPassword(String password);
86
87
// Connection methods
88
public String getDriverClassName();
89
public String getJdbcUrl();
90
public String getUsername();
91
public String getPassword();
92
public String getTestQueryString();
93
public Set<Integer> getLivenessCheckPortNumbers();
94
}
95
```
96
97
**Usage Examples:**
98
99
```java
100
// Basic setup with license acceptance
101
MSSQLServerContainer<?> mssqlserver = new MSSQLServerContainer<>("mcr.microsoft.com/mssql/server:2019-latest")
102
.acceptLicense()
103
.withPassword("MyStr0ngPassword!");
104
105
mssqlserver.start();
106
107
// Get connection details
108
String jdbcUrl = mssqlserver.getJdbcUrl();
109
String username = mssqlserver.getUsername(); // Always "sa"
110
String password = mssqlserver.getPassword();
111
112
// Use with DataSource
113
HikariConfig config = new HikariConfig();
114
config.setJdbcUrl(jdbcUrl);
115
config.setUsername(username);
116
config.setPassword(password);
117
config.setDriverClassName(mssqlserver.getDriverClassName());
118
```
119
120
### JDBC Container Provider
121
122
Factory class for creating JDBC-based MS SQL Server containers, enabling framework integration and programmatic container creation.
123
124
```java { .api }
125
public class MSSQLServerContainerProvider extends JdbcDatabaseContainerProvider {
126
public boolean supports(String databaseType);
127
public JdbcDatabaseContainer<?> newInstance();
128
public JdbcDatabaseContainer<?> newInstance(String tag);
129
}
130
```
131
132
**Usage Examples:**
133
134
```java
135
// Using provider for framework integration
136
MSSQLServerContainerProvider provider = new MSSQLServerContainerProvider();
137
138
if (provider.supports("sqlserver")) {
139
JdbcDatabaseContainer<?> container = provider.newInstance("2019-latest");
140
container.start();
141
}
142
```
143
144
### R2DBC Database Container
145
146
R2DBC wrapper providing reactive database access by wrapping an existing MSSQLServerContainer with reactive connectivity options.
147
148
```java { .api }
149
public class MSSQLR2DBCDatabaseContainer implements R2DBCDatabaseContainer {
150
// Constructor
151
public MSSQLR2DBCDatabaseContainer(MSSQLServerContainer<?> container);
152
153
// Configuration methods
154
public static ConnectionFactoryOptions getOptions(MSSQLServerContainer<?> container);
155
public ConnectionFactoryOptions configure(ConnectionFactoryOptions options);
156
157
// Lifecycle methods (delegated to underlying container)
158
public void start();
159
public void stop();
160
public boolean isRunning();
161
}
162
```
163
164
**Usage Examples:**
165
166
```java
167
// Create R2DBC container from existing JDBC container
168
MSSQLServerContainer<?> jdbcContainer = new MSSQLServerContainer<>("mcr.microsoft.com/mssql/server:2019-latest")
169
.acceptLicense()
170
.withPassword("MyStr0ngPassword!");
171
172
MSSQLR2DBCDatabaseContainer r2dbcContainer = new MSSQLR2DBCDatabaseContainer(jdbcContainer);
173
r2dbcContainer.start();
174
175
// Get R2DBC connection options
176
ConnectionFactoryOptions options = r2dbcContainer.configure(
177
MSSQLR2DBCDatabaseContainer.getOptions(jdbcContainer)
178
);
179
180
// Create R2DBC connection factory
181
ConnectionFactory connectionFactory = ConnectionFactories.get(options);
182
```
183
184
### R2DBC Container Provider
185
186
Factory class for creating R2DBC-based MS SQL Server containers from connection options, enabling reactive framework integration.
187
188
```java { .api }
189
public class MSSQLR2DBCDatabaseContainerProvider implements R2DBCDatabaseContainerProvider {
190
// Package-private constants
191
static final String DRIVER = "mssql"; // R2DBC driver identifier
192
193
// Provider methods
194
public boolean supports(ConnectionFactoryOptions options);
195
public R2DBCDatabaseContainer createContainer(ConnectionFactoryOptions options);
196
public ConnectionFactoryMetadata getMetadata(ConnectionFactoryOptions options);
197
}
198
```
199
200
**Usage Examples:**
201
202
```java
203
// Using provider for R2DBC framework integration
204
ConnectionFactoryOptions options = ConnectionFactoryOptions.builder()
205
.option(DRIVER, "mssql")
206
.option(HOST, "localhost")
207
.option(DATABASE, "test")
208
.build();
209
210
MSSQLR2DBCDatabaseContainerProvider provider = new MSSQLR2DBCDatabaseContainerProvider();
211
212
if (provider.supports(options)) {
213
R2DBCDatabaseContainer container = provider.createContainer(options);
214
container.start();
215
}
216
```
217
218
## Types
219
220
```java { .api }
221
// Core types from Testcontainers framework
222
import org.testcontainers.containers.JdbcDatabaseContainer;
223
import org.testcontainers.containers.JdbcDatabaseContainerProvider;
224
import org.testcontainers.r2dbc.R2DBCDatabaseContainer;
225
import org.testcontainers.r2dbc.R2DBCDatabaseContainerProvider;
226
import org.testcontainers.utility.DockerImageName;
227
import org.testcontainers.lifecycle.Startable;
228
229
// R2DBC types
230
import io.r2dbc.spi.ConnectionFactory;
231
import io.r2dbc.spi.ConnectionFactories;
232
import io.r2dbc.spi.ConnectionFactoryOptions;
233
import io.r2dbc.spi.ConnectionFactoryMetadata;
234
235
// Standard Java types
236
import java.util.Set;
237
import java.sql.Connection;
238
import java.sql.DriverManager;
239
import java.sql.SQLException;
240
```
241
242
## Error Handling
243
244
The MSSQL Server container handles several types of errors:
245
246
- **Password Validation**: `IllegalArgumentException` thrown for passwords that don't meet SQL Server requirements (8-128 characters, 3+ character categories)
247
- **Image Compatibility**: Exceptions thrown for incompatible Docker images during validation
248
- **License Requirements**: Container startup fails if `ACCEPT_EULA=Y` is not set via `acceptLicense()` method
249
- **Connection Failures**: Standard JDBC/R2DBC connection exceptions for network or authentication issues
250
251
**Common Error Patterns:**
252
253
```java
254
try {
255
MSSQLServerContainer<?> container = new MSSQLServerContainer<>("mcr.microsoft.com/mssql/server:2019-latest")
256
.withPassword("weak"); // Will throw IllegalArgumentException
257
} catch (IllegalArgumentException e) {
258
// Handle password validation error
259
System.err.println("Password does not meet SQL Server requirements: " + e.getMessage());
260
}
261
262
// Always accept license to avoid startup failures
263
container.acceptLicense(); // Required for successful container startup
264
```