0
# Driver Registration and Connection Management
1

2
Comprehensive JDBC driver functionality for connecting to Apache Flink SQL Gateway, including automatic driver registration, URL parsing, and connection lifecycle management with catalog and schema support.
3

4
## Capabilities
5

6
### Driver Registration
7

8
The Flink JDBC driver automatically registers itself with the JDBC DriverManager through the standard META-INF/services mechanism, enabling standard JDBC connection patterns.
9

10
```java { .api }
11
public class FlinkDriver implements Driver {
12
    // Automatic registration via static block
13
    static {
14
        try {
15
            DriverManager.registerDriver(new FlinkDriver());
16
        } catch (SQLException e) {
17
            throw new RuntimeException(e);
18
        }
19
    }
20
    
21
    public Connection connect(String url, Properties driverProperties) throws SQLException;
22
    public boolean acceptsURL(String url) throws SQLException;
23
    public DriverPropertyInfo[] getPropertyInfo(String url, Properties info) throws SQLException;
24
    public int getMajorVersion();
25
    public int getMinorVersion();
26
    public boolean jdbcCompliant(); // Returns false - not fully JDBC compliant
27
    public java.util.logging.Logger getParentLogger() throws SQLFeatureNotSupportedException;
28
}
29
```
30

31
**Usage Example:**
32
```java
33
// Driver is automatically registered - no manual registration needed
34
String url = "jdbc:flink://localhost:8083";
35
Connection conn = DriverManager.getConnection(url);
36
```
37

38
### DataSource Implementation
39

40
FlinkDataSource provides a DataSource implementation for connection pooling scenarios and framework integration.
41

42
```java { .api }
43
public class FlinkDataSource implements DataSource {
44
    public FlinkDataSource(String url, Properties properties);
45
    
46
    public Connection getConnection() throws SQLException;
47
    public Connection getConnection(String username, String password) throws SQLException; // Not supported
48
    
49
    // Standard DataSource methods (most not supported)
50
    public <T> T unwrap(Class<T> iface) throws SQLException; // Not supported
51
    public boolean isWrapperFor(Class<?> iface) throws SQLException; // Not supported
52
    public PrintWriter getLogWriter() throws SQLException; // Not supported
53
    public void setLogWriter(PrintWriter out) throws SQLException; // Not supported
54
    public void setLoginTimeout(int seconds) throws SQLException; // Not supported
55
    public int getLoginTimeout() throws SQLException; // Not supported
56
    public Logger getParentLogger() throws SQLFeatureNotSupportedException; // Not supported
57
}
58
```
59

60
**Usage Example:**
61
```java
62
Properties props = new Properties();
63
props.setProperty("catalog", "my_catalog");
64
props.setProperty("database", "my_database");
65

66
FlinkDataSource dataSource = new FlinkDataSource(
67
    "jdbc:flink://localhost:8083", 
68
    props
69
);
70

71
Connection connection = dataSource.getConnection();
72
```
73

74
### Connection Implementation
75

76
FlinkConnection provides the core connection functionality to Flink SQL Gateway with catalog and schema management.
77

78
```java { .api }
79
public class FlinkConnection extends BaseConnection {
80
    public FlinkConnection(DriverUri driverUri);
81
    
82
    // Statement creation
83
    public Statement createStatement() throws SQLException;
84
    
85
    // Transaction management (limited support)
86
    public void setAutoCommit(boolean autoCommit) throws SQLException; // No-op for compatibility
87
    public boolean getAutoCommit() throws SQLException; // Always returns true
88
    public void setTransactionIsolation(int level) throws SQLException; // No-op for compatibility
89
    public int getTransactionIsolation() throws SQLException; // Returns TRANSACTION_NONE
90
    
91
    // Connection lifecycle
92
    public void close() throws SQLException;
93
    public boolean isClosed() throws SQLException;
94
    
95
    // Metadata access
96
    public DatabaseMetaData getMetaData() throws SQLException;
97
    
98
    // Catalog and schema management
99
    public void setCatalog(String catalog) throws SQLException;
100
    public String getCatalog() throws SQLException;
101
    public void setSchema(String schema) throws SQLException;
102
    public String getSchema() throws SQLException;
103
    
104
    // Client information
105
    public void setClientInfo(String name, String value) throws SQLClientInfoException;
106
    public void setClientInfo(Properties properties) throws SQLClientInfoException;
107
    public String getClientInfo(String name) throws SQLException;
108
    public Properties getClientInfo() throws SQLException;
109
    
110
    // Warnings (not supported)
111
    public SQLWarning getWarnings() throws SQLException; // Returns null
112
    public void clearWarnings() throws SQLException; // No-op
113
}
114
```
115

116
**Important**: FlinkConnection is NOT thread-safe. Use separate connections for each thread.
117

118
**Usage Example:**
119
```java
120
String url = "jdbc:flink://localhost:8083/my_catalog/my_database";
121
Connection connection = DriverManager.getConnection(url);
122

123
// Set catalog and schema
124
connection.setCatalog("production_catalog");
125
connection.setSchema("analytics_schema");
126

127
// Get current catalog and schema
128
String currentCatalog = connection.getCatalog();
129
String currentSchema = connection.getSchema();
130
```
131

132
### URL Parsing and Configuration
133

134
DriverUri handles parsing and validation of Flink JDBC URLs with comprehensive property support.
135

136
```java { .api }
137
public class DriverUri {
138
    public static DriverUri create(String url, Properties properties) throws SQLException;
139
    public static boolean acceptsURL(String url);
140
    
141
    public InetSocketAddress getAddress();
142
    public Properties getProperties();
143
    public Optional<String> getCatalog();
144
    public Optional<String> getDatabase();
145
    public String getURL();
146
}
147
```
148

149
**URL Format**: `jdbc:flink://host:port[/catalog[/database]][?param=value&...]`
150

151
**URL Examples:**
152
- `jdbc:flink://localhost:8083` - Basic connection
153
- `jdbc:flink://flink-gateway:8083/my_catalog` - With catalog
154
- `jdbc:flink://flink-gateway:8083/my_catalog/my_database` - With catalog and database
155
- `jdbc:flink://localhost:8083?timeout=30000&retries=3` - With query parameters
156

157
**Usage Example:**
158
```java
159
String url = "jdbc:flink://localhost:8083/production/analytics?timeout=30000";
160
Properties props = new Properties();
161
props.setProperty("user", "analytics_user");
162

163
DriverUri driverUri = DriverUri.create(url, props);
164
InetSocketAddress address = driverUri.getAddress(); // localhost:8083
165
Optional<String> catalog = driverUri.getCatalog(); // "production"
166
Optional<String> database = driverUri.getDatabase(); // "analytics"
167
Properties allProps = driverUri.getProperties(); // Includes timeout and user
168
```
169

170
### Unsupported Connection Features
171

172
The following standard JDBC connection features are not supported and will throw `SQLFeatureNotSupportedException`:
173

174
- **Prepared Statements**: `prepareStatement()` methods
175
- **Callable Statements**: `prepareCall()` methods  
176
- **Transactions**: `commit()`, `rollback()`, `setSavepoint()`, `releaseSavepoint()`
177
- **Type Maps**: `setTypeMap()`, `getTypeMap()`
178
- **Holdability**: `setHoldability()`, `getHoldability()`
179
- **Network Timeout**: `setNetworkTimeout()`, `getNetworkTimeout()`
180
- **Abort**: `abort()`
181
- **Array/Struct/Blob/Clob Creation**: `createArrayOf()`, `createStruct()`, etc.
182

183
### Connection Properties
184

185
Supported connection properties can be passed via the Properties parameter or as URL query parameters:
186

187
- **catalog**: Default catalog to use
188
- **database**: Default database/schema to use  
189
- Custom properties are passed through to the underlying Flink SQL Gateway connection
190

191
**Example with Properties:**
192
```java
193
Properties props = new Properties();
194
props.setProperty("catalog", "production");
195
props.setProperty("database", "analytics");
196
props.setProperty("timeout", "30000");
197

198
Connection conn = DriverManager.getConnection(
199
    "jdbc:flink://localhost:8083", 
200
    props
201
);
202
```
203

204
### Error Handling
205

206
Connection-related operations may throw:
207

208
- **SQLException**: For general connection errors, invalid URLs, or connection failures
209
- **SQLFeatureNotSupportedException**: For unsupported JDBC features
210
- **SQLClientInfoException**: For client info operations that cannot be applied
211

212
Common error scenarios:
213
- Invalid URL format: `jdbc:invalid://localhost:8083`
214
- Connection timeout: Server not responding
215
- Authentication failures: Invalid credentials
216
- Network connectivity issues: Host unreachable