Skip to content

Commit 9a2ca9b

Browse files
CopilotMohabMohie
Copilot
and
MohabMohie
authored
Add DB section to user guide (#367)
* Initial plan * Add DB section to user guide with actions, connection strings, and Oracle JDBC setup Co-authored-by: MohabMohie <19201898+MohabMohie@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: MohabMohie <19201898+MohabMohie@users.noreply.github.com>
1 parent 43fd5f7 commit 9a2ca9b

File tree

4 files changed

+928
-0
lines changed

4 files changed

+928
-0
lines changed

‎docs/Keywords/DB/Connection_Strings.md‎

Lines changed: 372 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,372 @@
1+
---
2+
id: Connection_Strings
3+
title: Database Connection Strings
4+
sidebar_label: Connection Strings
5+
---
6+
7+
## JDBC Connection Strings
8+
9+
SHAFT uses JDBC (Java Database Connectivity) to connect to various databases. Each database type requires a specific connection string format.
10+
11+
## Standard Connection String Patterns
12+
13+
### MySQL
14+
MySQL is a popular open-source relational database.
15+
16+
#### Basic Connection
17+
```java
18+
SHAFT.DB db = new SHAFT.DB(
19+
"jdbc:mysql://localhost:3306/database_name",
20+
"username",
21+
"password"
22+
);
23+
```
24+
25+
#### With SSL
26+
```java
27+
SHAFT.DB db = new SHAFT.DB(
28+
"jdbc:mysql://localhost:3306/database_name?useSSL=true&requireSSL=true",
29+
"username",
30+
"password"
31+
);
32+
```
33+
34+
#### With Additional Parameters
35+
```java
36+
SHAFT.DB db = new SHAFT.DB(
37+
"jdbc:mysql://localhost:3306/database_name?useUnicode=true&characterEncoding=UTF-8&serverTimezone=UTC",
38+
"username",
39+
"password"
40+
);
41+
```
42+
43+
**Connection String Pattern:**
44+
```
45+
jdbc:mysql://[host]:[port]/[database]?[parameters]
46+
```
47+
48+
**Default Port:** 3306
49+
50+
---
51+
52+
### PostgreSQL
53+
PostgreSQL is a powerful open-source object-relational database.
54+
55+
#### Basic Connection
56+
```java
57+
SHAFT.DB db = new SHAFT.DB(
58+
"jdbc:postgresql://localhost:5432/database_name",
59+
"username",
60+
"password"
61+
);
62+
```
63+
64+
#### With SSL
65+
```java
66+
SHAFT.DB db = new SHAFT.DB(
67+
"jdbc:postgresql://localhost:5432/database_name?ssl=true&sslmode=require",
68+
"username",
69+
"password"
70+
);
71+
```
72+
73+
#### With Schema
74+
```java
75+
SHAFT.DB db = new SHAFT.DB(
76+
"jdbc:postgresql://localhost:5432/database_name?currentSchema=myschema",
77+
"username",
78+
"password"
79+
);
80+
```
81+
82+
**Connection String Pattern:**
83+
```
84+
jdbc:postgresql://[host]:[port]/[database]?[parameters]
85+
```
86+
87+
**Default Port:** 5432
88+
89+
---
90+
91+
### Oracle
92+
Oracle Database is a multi-model database management system.
93+
94+
#### Basic Connection (SID)
95+
```java
96+
SHAFT.DB db = new SHAFT.DB(
97+
"jdbc:oracle:thin:@localhost:1521:ORCL",
98+
"username",
99+
"password"
100+
);
101+
```
102+
103+
#### Service Name
104+
```java
105+
SHAFT.DB db = new SHAFT.DB(
106+
"jdbc:oracle:thin:@//localhost:1521/service_name",
107+
"username",
108+
"password"
109+
);
110+
```
111+
112+
#### TNS Names
113+
```java
114+
SHAFT.DB db = new SHAFT.DB(
115+
"jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=ORCL)))",
116+
"username",
117+
"password"
118+
);
119+
```
120+
121+
**Connection String Patterns:**
122+
- **SID:** `jdbc:oracle:thin:@[host]:[port]:[SID]`
123+
- **Service Name:** `jdbc:oracle:thin:@//[host]:[port]/[service_name]`
124+
125+
**Default Port:** 1521
126+
127+
**Note:** Oracle JDBC driver requires additional setup. See [Oracle JDBC Setup](Oracle_JDBC_Setup.md) for detailed instructions.
128+
129+
---
130+
131+
### Microsoft SQL Server
132+
Microsoft SQL Server is a relational database management system.
133+
134+
#### Basic Connection
135+
```java
136+
SHAFT.DB db = new SHAFT.DB(
137+
"jdbc:sqlserver://localhost:1433;databaseName=database_name",
138+
"username",
139+
"password"
140+
);
141+
```
142+
143+
#### Windows Authentication
144+
```java
145+
SHAFT.DB db = new SHAFT.DB(
146+
"jdbc:sqlserver://localhost:1433;databaseName=database_name;integratedSecurity=true",
147+
"",
148+
""
149+
);
150+
```
151+
152+
#### With Encryption
153+
```java
154+
SHAFT.DB db = new SHAFT.DB(
155+
"jdbc:sqlserver://localhost:1433;databaseName=database_name;encrypt=true;trustServerCertificate=false",
156+
"username",
157+
"password"
158+
);
159+
```
160+
161+
**Connection String Pattern:**
162+
```
163+
jdbc:sqlserver://[host]:[port];databaseName=[database];[parameters]
164+
```
165+
166+
**Default Port:** 1433
167+
168+
---
169+
170+
### MariaDB
171+
MariaDB is a community-developed fork of MySQL.
172+
173+
#### Basic Connection
174+
```java
175+
SHAFT.DB db = new SHAFT.DB(
176+
"jdbc:mariadb://localhost:3306/database_name",
177+
"username",
178+
"password"
179+
);
180+
```
181+
182+
**Connection String Pattern:**
183+
```
184+
jdbc:mariadb://[host]:[port]/[database]?[parameters]
185+
```
186+
187+
**Default Port:** 3306
188+
189+
---
190+
191+
### SQLite
192+
SQLite is a lightweight, file-based database.
193+
194+
#### Basic Connection
195+
```java
196+
SHAFT.DB db = new SHAFT.DB(
197+
"jdbc:sqlite:/path/to/database.db",
198+
"",
199+
""
200+
);
201+
```
202+
203+
#### In-Memory Database
204+
```java
205+
SHAFT.DB db = new SHAFT.DB(
206+
"jdbc:sqlite::memory:",
207+
"",
208+
""
209+
);
210+
```
211+
212+
**Connection String Pattern:**
213+
```
214+
jdbc:sqlite:[path_to_database_file]
215+
```
216+
217+
**Note:** SQLite doesn't require username and password.
218+
219+
---
220+
221+
### IBM DB2
222+
IBM DB2 is a family of data management products.
223+
224+
#### Basic Connection
225+
```java
226+
SHAFT.DB db = new SHAFT.DB(
227+
"jdbc:db2://localhost:50000/database_name",
228+
"username",
229+
"password"
230+
);
231+
```
232+
233+
**Connection String Pattern:**
234+
```
235+
jdbc:db2://[host]:[port]/[database]
236+
```
237+
238+
**Default Port:** 50000
239+
240+
---
241+
242+
## Custom Connection String Patterns
243+
244+
### Using Properties File
245+
You can externalize connection strings using SHAFT properties:
246+
247+
```properties
248+
# shaft.properties
249+
db.url=jdbc:mysql://localhost:3306/mydb
250+
db.username=testuser
251+
db.password=testpass
252+
```
253+
254+
```java
255+
String dbUrl = System.getProperty("db.url");
256+
String dbUser = System.getProperty("db.username");
257+
String dbPass = System.getProperty("db.password");
258+
259+
SHAFT.DB db = new SHAFT.DB(dbUrl, dbUser, dbPass);
260+
```
261+
262+
### Environment Variables
263+
Using environment variables for sensitive data:
264+
265+
```java
266+
String dbUrl = System.getenv("DB_URL");
267+
String dbUser = System.getenv("DB_USERNAME");
268+
String dbPass = System.getenv("DB_PASSWORD");
269+
270+
SHAFT.DB db = new SHAFT.DB(dbUrl, dbUser, dbPass);
271+
```
272+
273+
### Connection String Builder
274+
Create a helper method for building connection strings:
275+
276+
```java
277+
public class DBHelper {
278+
public static String buildConnectionString(
279+
String dbType,
280+
String host,
281+
int port,
282+
String database
283+
) {
284+
switch (dbType.toLowerCase()) {
285+
case "mysql":
286+
return String.format("jdbc:mysql://%s:%d/%s", host, port, database);
287+
case "postgresql":
288+
return String.format("jdbc:postgresql://%s:%d/%s", host, port, database);
289+
case "oracle":
290+
return String.format("jdbc:oracle:thin:@//%s:%d/%s", host, port, database);
291+
case "sqlserver":
292+
return String.format("jdbc:sqlserver://%s:%d;databaseName=%s", host, port, database);
293+
default:
294+
throw new IllegalArgumentException("Unsupported database type: " + dbType);
295+
}
296+
}
297+
}
298+
299+
// Usage
300+
String connectionString = DBHelper.buildConnectionString("mysql", "localhost", 3306, "mydb");
301+
SHAFT.DB db = new SHAFT.DB(connectionString, "user", "pass");
302+
```
303+
304+
### Multiple Database Connections
305+
Managing multiple database connections in your tests:
306+
307+
```java
308+
// Source database
309+
SHAFT.DB sourceDb = new SHAFT.DB(
310+
"jdbc:mysql://source-host:3306/source_db",
311+
"source_user",
312+
"source_pass"
313+
);
314+
315+
// Target database
316+
SHAFT.DB targetDb = new SHAFT.DB(
317+
"jdbc:postgresql://target-host:5432/target_db",
318+
"target_user",
319+
"target_pass"
320+
);
321+
322+
// Perform operations
323+
ResultSet sourceData = sourceDb.executeSelectQuery("SELECT * FROM products");
324+
// ... process and insert into target ...
325+
326+
sourceDb.closeConnection();
327+
targetDb.closeConnection();
328+
```
329+
330+
## Connection Parameters Reference
331+
332+
### Common JDBC Parameters
333+
334+
| Parameter | Description | Example |
335+
|-----------|-------------|---------|
336+
| `useSSL` | Enable SSL connection | `?useSSL=true` |
337+
| `serverTimezone` | Set server timezone | `?serverTimezone=UTC` |
338+
| `characterEncoding` | Character encoding | `?characterEncoding=UTF-8` |
339+
| `autoReconnect` | Auto reconnect on connection loss | `?autoReconnect=true` |
340+
| `maxReconnects` | Maximum reconnection attempts | `?maxReconnects=3` |
341+
| `connectTimeout` | Connection timeout in milliseconds | `?connectTimeout=30000` |
342+
343+
### Combining Multiple Parameters
344+
Multiple parameters are separated by `&`:
345+
346+
```java
347+
SHAFT.DB db = new SHAFT.DB(
348+
"jdbc:mysql://localhost:3306/mydb?useSSL=true&serverTimezone=UTC&characterEncoding=UTF-8",
349+
"username",
350+
"password"
351+
);
352+
```
353+
354+
## Best Practices
355+
356+
### Security
357+
- **Never hardcode credentials** in your test code
358+
- Use environment variables or secure vaults for sensitive data
359+
- Use SSL/TLS connections when available
360+
- Implement least privilege access for test database users
361+
362+
### Connection Management
363+
- Always close connections after use
364+
- Use try-with-resources for automatic connection management
365+
- Consider connection pooling for performance-intensive tests
366+
- Set appropriate timeout values
367+
368+
### Configuration
369+
- Externalize connection strings using properties files
370+
- Use different configurations for different environments (dev, test, prod)
371+
- Document required JDBC drivers and their versions
372+
- Keep JDBC drivers up to date for security and bug fixes

0 commit comments

Comments
 (0)