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
```