0
# JDBC Connectivity
1

2
Standard JDBC database connectivity with Oracle-specific connection URLs, driver management, and database operations. Provides seamless integration with JUnit testing frameworks and connection pooling libraries.
3

4
## Capabilities
5

6
### Connection Information
7

8
Provides Oracle-specific JDBC connection details including driver class names, connection URLs, and authentication credentials with support for both PDB and SID connection modes.
9

10
```java { .api }
11
public String getDriverClassName();
12
public String getJdbcUrl();
13
public String getUsername();
14
public String getPassword();
15
public String getTestQueryString();
16
```
17

18
**Returns:**
19
- `String`: Oracle JDBC driver class name ("oracle.jdbc.OracleDriver" or "oracle.jdbc.driver.OracleDriver")
20
- `String`: Complete JDBC connection URL with host, port, and database/SID
21
- `String`: Database username (application user or system user based on connection mode)
22
- `String`: Database password
23
- `String`: Test query for connection validation ("SELECT 1 FROM DUAL")
24

25
**Usage Example:**
26
```java
27
OracleContainer container = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim")
28
    .withUsername("appuser")
29
    .withPassword("apppass");
30
container.start();
31

32
// Get connection details
33
String driverClass = container.getDriverClassName();
34
String jdbcUrl = container.getJdbcUrl();
35
String username = container.getUsername();
36
String password = container.getPassword();
37

38
// Example URLs:
39
// PDB mode: jdbc:oracle:thin:@localhost:32768/xepdb1
40
// SID mode: jdbc:oracle:thin:@localhost:32768:xe
41

42
// Test query
43
String testQuery = container.getTestQueryString(); // "SELECT 1 FROM DUAL"
44
```
45

46
### Direct Connection Management
47

48
Creates and manages JDBC connections with automatic driver loading, connection parameter handling, and query string support for connection customization.
49

50
```java { .api }
51
public Connection createConnection(String queryString) throws SQLException, NoDriverFoundException;
52
public Connection createConnection(String queryString, Properties info) throws SQLException, NoDriverFoundException;
53
public Driver getJdbcDriverInstance() throws NoDriverFoundException;
54
```
55

56
**Parameters:**
57
- `queryString (String)`: Additional query parameters for connection URL
58
- `info (Properties)`: JDBC connection properties
59

60
**Returns:**
61
- `Connection`: Active JDBC database connection
62
- `Driver`: Oracle JDBC driver instance
63

64
**Throws:**
65
- `SQLException`: Database connection errors
66
- `NoDriverFoundException`: JDBC driver loading failures
67

68
**Usage Example:**
69
```java
70
OracleContainer container = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim");
71
container.start();
72

73
// Create basic connection
74
try (Connection conn = container.createConnection("")) {
75
    Statement stmt = conn.createStatement();
76
    ResultSet rs = stmt.executeQuery("SELECT SYSDATE FROM DUAL");
77
    if (rs.next()) {
78
        System.out.println("Current time: " + rs.getTimestamp(1));
79
    }
80
}
81

82
// Create connection with properties
83
Properties props = new Properties();
84
props.setProperty("oracle.net.CONNECT_TIMEOUT", "10000");
85
props.setProperty("oracle.jdbc.ReadTimeout", "30000");
86

87
try (Connection conn = container.createConnection("", props)) {
88
    // Use connection with custom properties
89
    DatabaseMetaData meta = conn.getMetaData();
90
    System.out.println("Database: " + meta.getDatabaseProductName());
91
}
92

93
// Get driver instance
94
Driver oracleDriver = container.getJdbcDriverInstance();
95
```
96

97
### Container Provider Integration
98

99
Service Provider Interface (SPI) implementation for automatic container discovery and creation in testing frameworks and dependency injection containers.
100

101
```java { .api }
102
public class OracleContainerProvider extends JdbcDatabaseContainerProvider {
103
    public boolean supports(String databaseType);
104
    public JdbcDatabaseContainer newInstance();
105
    public JdbcDatabaseContainer newInstance(String tag);
106
}
107
```
108

109
**Parameters:**
110
- `databaseType (String)`: Database type identifier ("oracle")
111
- `tag (String)`: Docker image tag for container creation
112

113
**Returns:**
114
- `boolean`: Whether provider supports the database type
115
- `JdbcDatabaseContainer`: New Oracle container instance
116

117
**Usage Example:**
118
```java
119
// SPI automatic discovery (used by testing frameworks)
120
ServiceLoader<JdbcDatabaseContainerProvider> providers = 
121
    ServiceLoader.load(JdbcDatabaseContainerProvider.class);
122

123
for (JdbcDatabaseContainerProvider provider : providers) {
124
    if (provider.supports("oracle")) {
125
        JdbcDatabaseContainer container = provider.newInstance("21.3.0-slim");
126
        // Use container
127
        break;
128
    }
129
}
130

131
// Direct provider usage
132
OracleContainerProvider provider = new OracleContainerProvider();
133
boolean supportsOracle = provider.supports("oracle"); // true
134
JdbcDatabaseContainer container1 = provider.newInstance(); // default tag
135
JdbcDatabaseContainer container2 = provider.newInstance("21.3.0-slim"); // custom tag
136
```
137

138
### Connection URL Formats
139

140
Oracle XE Testcontainers supports two connection URL formats depending on the connection mode:
141

142
**PDB (Pluggable Database) Mode (Default):**
143
```
144
jdbc:oracle:thin:@<host>:<port>/<database_name>
145
```
146

147
**SID (System Identifier) Mode:**
148
```
149
jdbc:oracle:thin:@<host>:<port>:<sid>
150
```
151

152
**Usage Example:**
153
```java
154
// PDB mode (default)
155
OracleContainer pdbContainer = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim")
156
    .withDatabaseName("testdb");
157
pdbContainer.start();
158
String pdbUrl = pdbContainer.getJdbcUrl();
159
// Result: jdbc:oracle:thin:@localhost:32768/testdb
160

161
// SID mode
162
OracleContainer sidContainer = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim")
163
    .usingSid();
164
sidContainer.start();
165
String sidUrl = sidContainer.getJdbcUrl();
166
// Result: jdbc:oracle:thin:@localhost:32768:xe
167
String sidUser = sidContainer.getUsername(); // "system" (not app user)
168
```
169

170
## Integration Patterns
171

172
### JUnit 5 Integration
173

174
```java
175
@Testcontainers
176
class OracleJdbcTest {
177
    
178
    @Container
179
    static OracleContainer oracle = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim")
180
        .withDatabaseName("testdb")
181
        .withUsername("testuser")
182
        .withPassword("testpass")
183
        .withInitScript("classpath:init.sql");
184
    
185
    @Test
186
    void testDatabaseConnection() throws SQLException {
187
        String jdbcUrl = oracle.getJdbcUrl();
188
        try (Connection conn = DriverManager.getConnection(
189
                jdbcUrl, oracle.getUsername(), oracle.getPassword())) {
190
            
191
            // Test connection
192
            assertTrue(conn.isValid(30));
193
            
194
            // Execute test query
195
            try (Statement stmt = conn.createStatement()) {
196
                ResultSet rs = stmt.executeQuery(oracle.getTestQueryString());
197
                assertTrue(rs.next());
198
                assertEquals(1, rs.getInt(1));
199
            }
200
        }
201
    }
202
}
203
```
204

205
### Spring Boot Integration
206

207
```java
208
@SpringBootTest
209
@Testcontainers
210
class SpringOracleTest {
211
    
212
    @Container
213
    static OracleContainer oracle = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim");
214
    
215
    @DynamicPropertySource
216
    static void configureProperties(DynamicPropertyRegistry registry) {
217
        registry.add("spring.datasource.url", oracle::getJdbcUrl);
218
        registry.add("spring.datasource.username", oracle::getUsername);
219
        registry.add("spring.datasource.password", oracle::getPassword);
220
        registry.add("spring.datasource.driver-class-name", oracle::getDriverClassName);
221
    }
222
    
223
    @Autowired
224
    private JdbcTemplate jdbcTemplate;
225
    
226
    @Test
227
    void testSpringDataSource() {
228
        Integer result = jdbcTemplate.queryForObject("SELECT 1 FROM DUAL", Integer.class);
229
        assertEquals(1, result);
230
    }
231
}
232
```