0
# Database Connection and Management
1

2
Core database abstraction and connection management providing the entry point for all metadata operations in jOOQ-meta.
3

4
## Capabilities
5

6
### Database Factory
7

8
Creates database instances using factory methods for type-safe database abstraction.
9

10
```java { .api }
11
/**
12
 * Creates a Database instance for the specified SQL dialect
13
 * Uses reflection to instantiate the appropriate Database class
14
 * and sets the dialect on the created instance
15
 * @param dialect - SQL dialect (POSTGRES, MYSQL, H2, etc.)
16
 * @returns Database instance for the specified dialect
17
 * @throws IllegalArgumentException if Database cannot be created
18
 */
19
static Database database(SQLDialect dialect);
20

21
/**
22
 * Gets the Database implementation class for a dialect
23
 * Maps SQL dialects to their corresponding Database implementation classes
24
 * Falls back to JDBCDatabase.class for unsupported dialects
25
 * 
26
 * Supported dialects include:
27
 * - CLICKHOUSE: ClickHouseDatabase
28
 * - CUBRID: CUBRIDDatabase  
29
 * - DERBY: DerbyDatabase
30
 * - DUCKDB: DuckDBDatabase
31
 * - FIREBIRD: FirebirdDatabase
32
 * - H2: H2Database
33
 * - HSQLDB: HSQLDBDatabase
34
 * - IGNITE: IgniteDatabase
35
 * - MARIADB: MariaDBDatabase
36
 * - MYSQL: MySQLDatabase
37
 * - POSTGRES: PostgresDatabase
38
 * - SQLITE: SQLiteDatabase
39
 * - TRINO: TrinoDatabase
40
 * - YUGABYTEDB: YugabyteDBDatabase
41
 * - DEFAULT: JDBCDatabase (fallback)
42
 * 
43
 * @param dialect - SQL dialect
44
 * @returns Class object for database implementation
45
 */
46
static Class<? extends Database> databaseClass(SQLDialect dialect);
47
```
48

49
**Usage Examples:**
50

51
```java
52
import org.jooq.meta.Database;
53
import org.jooq.meta.Databases;
54
import org.jooq.SQLDialect;
55
import java.sql.Connection;
56

57
// Create database for PostgreSQL
58
Database database = Databases.database(SQLDialect.POSTGRES);
59

60
// Create and set connection separately
61
Connection conn = DriverManager.getConnection("jdbc:postgresql://localhost/db", "user", "pass");
62
Database database = Databases.database(SQLDialect.POSTGRES);
63
database.setConnection(conn);
64

65
// Get implementation class
66
Class<? extends Database> dbClass = Databases.databaseClass(SQLDialect.MYSQL);
67
```
68

69
### Connection Management
70

71
Manages database connections for metadata extraction with proper resource handling.
72

73
```java { .api }
74
/**
75
 * Sets the database connection for metadata operations
76
 * @param connection - JDBC connection to the database
77
 */
78
void setConnection(Connection connection);
79

80
/**
81
 * Gets the current database connection
82
 * @returns Current JDBC connection or null if not set
83
 */
84
Connection getConnection();
85

86
/**
87
 * Creates a jOOQ DSL context using the current connection
88
 * @returns DSLContext for executing queries
89
 */
90
DSLContext create();
91

92
/**
93
 * Closes the database and releases all resources
94
 * Must be called to prevent resource leaks
95
 */
96
void close();
97
```
98

99
**Usage Examples:**
100

101
```java
102
import org.jooq.meta.Database;
103
import org.jooq.meta.postgres.PostgresDatabase;
104
import java.sql.Connection;
105
import java.sql.DriverManager;
106

107
try (Database database = new PostgresDatabase()) {
108
    // Set up connection
109
    Connection connection = DriverManager.getConnection(
110
        "jdbc:postgresql://localhost:5432/mydb", "username", "password");
111
    database.setConnection(connection);
112
    
113
    // Use database for metadata operations
114
    List<SchemaDefinition> schemas = database.getSchemata();
115
    
116
    // Database connection is available
117
    Connection conn = database.getConnection();
118
    
119
    // Create DSL context for queries
120
    DSLContext dsl = database.create();
121
    
122
} // Automatically closes and releases resources
123
```
124

125
### Dialect Configuration
126

127
Configures database-specific behavior and SQL dialect handling.
128

129
```java { .api }
130
/**
131
 * Gets the SQL dialect for this database
132
 * @returns Current SQL dialect
133
 */
134
SQLDialect getDialect();
135

136
/**
137
 * Sets the SQL dialect for this database
138
 * @param dialect - SQL dialect to use
139
 */
140
void setDialect(SQLDialect dialect);
141

142
/**
143
 * Checks if database supports unsigned types
144
 * @returns true if unsigned types are supported
145
 */
146
boolean supportsUnsignedTypes();
147

148
/**
149
 * Sets unsigned type support flag
150
 * @param supportsUnsignedTypes - Whether unsigned types are supported
151
 */
152
void setSupportsUnsignedTypes(boolean supportsUnsignedTypes);
153
```
154

155
### Database Properties
156

157
Configuration of database-specific properties and options.
158

159
```java { .api }
160
/**
161
 * Sets database properties for implementation-specific configuration
162
 * @param properties - Properties object with configuration
163
 */
164
void setProperties(Properties properties);
165

166
/**
167
 * Gets database properties
168
 * @returns Properties object with current configuration
169
 */
170
Properties getProperties();
171

172
/**
173
 * Sets base directory for file-based implementations
174
 * @param basedir - Base directory path
175
 */
176
void setBasedir(String basedir);
177

178
/**
179
 * Gets base directory for file-based implementations
180
 * @returns Base directory path
181
 */
182
String getBasedir();
183
```
184

185
### Error Handling Configuration
186

187
Configures error handling behavior during metadata extraction.
188

189
```java { .api }
190
/**
191
 * Sets error handling behavior
192
 * @param onError - Error handling strategy (FAIL, LOG, SILENT)
193
 */
194
void setOnError(OnError onError);
195

196
/**
197
 * Gets current error handling behavior
198
 * @returns Current error handling strategy
199
 */
200
OnError onError();
201

202
/**
203
 * Sets slow query logging threshold
204
 * @param logSlowQueriesAfterSeconds - Threshold in seconds
205
 */
206
void setLogSlowQueriesAfterSeconds(int logSlowQueriesAfterSeconds);
207

208
/**
209
 * Gets slow query logging threshold
210
 * @returns Threshold in seconds
211
 */
212
int getLogSlowQueriesAfterSeconds();
213
```
214

215
## Types
216

217
```java { .api }
218
enum OnError {
219
    /** Fail immediately on any error */
220
    FAIL,
221
    /** Log errors and continue processing */
222
    LOG,
223
    /** Ignore errors silently */
224
    SILENT
225
}
226

227
interface Database extends AutoCloseable {
228
    void setConnection(Connection connection);
229
    Connection getConnection();
230
    SQLDialect getDialect();
231
    void setDialect(SQLDialect dialect);
232
    DSLContext create();
233
    void setProperties(Properties properties);
234
    Properties getProperties();
235
    void close();
236
}
237
```
238

239
**Usage Examples:**
240

241
```java
242
import org.jooq.meta.Database;
243
import org.jooq.meta.postgres.PostgresDatabase;
244
import org.jooq.meta.jaxb.OnError;
245
import java.util.Properties;
246

247
Database database = new PostgresDatabase();
248

249
// Configure error handling
250
database.setOnError(OnError.LOG);
251

252
// Set up properties
253
Properties props = new Properties();
254
props.setProperty("key", "value");
255
database.setProperties(props);
256

257
// Configure dialect-specific options
258
database.setSupportsUnsignedTypes(false);
259
database.setLogSlowQueriesAfterSeconds(5);
260
```