0
# Configuration and Connection URLs
1

2
Connection URL parsing, property management, and host information for configuring database connections. These classes handle connection string parsing and property validation.
3

4
## Capabilities
5

6
### Connection URL Parsing
7

8
Parse and manage MySQL connection URLs.
9

10
```java { .api }
11
package com.mysql.cj.conf;
12

13
public class ConnectionUrl {
14
    // Create ConnectionUrl from connection string
15
    public static ConnectionUrl getConnectionUrlInstance(String connString, Properties info);
16

17
    // Get connection type
18
    public Type getType();
19

20
    // Database information
21
    public String getDatabase();
22

23
    // Default connection settings
24
    public int getDefaultPort();
25
    public String getDefaultHost();
26

27
    // Host information
28
    public List<HostInfo> getHostsList();
29
    public HostInfo getMainHost();
30

31
    // Properties
32
    public Properties getOriginalProperties();
33
    public Properties getConnectionArgumentsAsProperties();
34

35
    // URL types
36
    public enum Type {
37
        SINGLE_CONNECTION("jdbc:mysql:", HostsCardinality.SINGLE),
38
        FAILOVER_CONNECTION("jdbc:mysql:", HostsCardinality.MULTIPLE),
39
        LOADBALANCE_CONNECTION("jdbc:mysql:loadbalance:", HostsCardinality.ONE_OR_MORE),
40
        REPLICATION_CONNECTION("jdbc:mysql:replication:", HostsCardinality.ONE_OR_MORE),
41
        XDEVAPI_SESSION("mysqlx:", HostsCardinality.ONE_OR_MORE);
42

43
        private final String protocol;
44
        private final HostsCardinality cardinality;
45

46
        Type(String protocol, HostsCardinality cardinality) {
47
            this.protocol = protocol;
48
            this.cardinality = cardinality;
49
        }
50

51
        public String getProtocol() { return protocol; }
52
        public HostsCardinality getCardinality() { return cardinality; }
53
    }
54

55
    public enum HostsCardinality {
56
        SINGLE,
57
        MULTIPLE,
58
        ONE_OR_MORE;
59
    }
60
}
61

62
public class ConnectionUrlParser {
63
    // Parse connection URL string
64
    public static ConnectionUrl parseConnectionString(String connString);
65

66
    // Validate URL format
67
    public static boolean isConnectionStringSupported(String connString);
68
}
69
```
70

71
Usage:
72

73
```java
74
// Parse JDBC URL
75
String url = "jdbc:mysql://localhost:3306/mydb?useSSL=true&serverTimezone=UTC";
76
ConnectionUrl connUrl = ConnectionUrl.getConnectionUrlInstance(url, new Properties());
77

78
System.out.println("Type: " + connUrl.getType());
79
System.out.println("Database: " + connUrl.getDatabase());
80
System.out.println("Default port: " + connUrl.getDefaultPort());
81

82
// Get host information
83
List<HostInfo> hosts = connUrl.getHostsList();
84
for (HostInfo host : hosts) {
85
    System.out.println("Host: " + host.getHost() + ":" + host.getPort());
86
}
87

88
// Parse load-balanced URL
89
String lbUrl = "jdbc:mysql:loadbalance://server1:3306,server2:3306/mydb";
90
ConnectionUrl lbConnUrl = ConnectionUrl.getConnectionUrlInstance(lbUrl, new Properties());
91

92
// Parse replication URL
93
String replUrl = "jdbc:mysql:replication://source:3306,replica1:3306,replica2:3306/mydb";
94
ConnectionUrl replConnUrl = ConnectionUrl.getConnectionUrlInstance(replUrl, new Properties());
95

96
// Parse X DevAPI URL
97
String xUrl = "mysqlx://root:password@localhost:33060/mydb";
98
ConnectionUrl xConnUrl = ConnectionUrl.getConnectionUrlInstance(xUrl, new Properties());
99
```
100

101
### Host Information
102

103
Detailed information about database hosts.
104

105
```java { .api }
106
package com.mysql.cj.conf;
107

108
public class HostInfo {
109
    // Constructor
110
    public HostInfo(ConnectionUrl connUrl, String host, int port, String user, String password);
111
    public HostInfo(ConnectionUrl connUrl, String host, int port, String user, String password,
112
                   Map<String, String> properties);
113

114
    // Host connection details
115
    public String getHost();
116
    public int getPort();
117
    public String getHostPortPair();
118

119
    // Authentication
120
    public String getUser();
121
    public String getPassword();
122

123
    // Database
124
    public String getDatabase();
125

126
    // Properties
127
    public Map<String, String> getHostProperties();
128
    public String getProperty(String key);
129

130
    // Expand host info (for DNS SRV records)
131
    public boolean isPasswordless();
132

133
    // String representation
134
    public String toString();
135
}
136
```
137

138
Usage:
139

140
```java
141
ConnectionUrl connUrl = ConnectionUrl.getConnectionUrlInstance(
142
    "jdbc:mysql://user:pass@localhost:3306/mydb",
143
    new Properties()
144
);
145

146
HostInfo hostInfo = connUrl.getMainHost();
147
System.out.println("Host: " + hostInfo.getHost());
148
System.out.println("Port: " + hostInfo.getPort());
149
System.out.println("User: " + hostInfo.getUser());
150
System.out.println("Database: " + hostInfo.getDatabase());
151

152
// Get host properties
153
Map<String, String> props = hostInfo.getHostProperties();
154
for (Map.Entry<String, String> entry : props.entrySet()) {
155
    System.out.println(entry.getKey() + " = " + entry.getValue());
156
}
157
```
158

159
### Property Keys
160

161
Enumeration of all connection properties.
162

163
```java { .api }
164
package com.mysql.cj.conf;
165

166
public enum PropertyKey {
167
    // Connection basics
168
    USER("user"),
169
    PASSWORD("password"),
170
    DBNAME("dbname"),
171
    HOST("host"),
172
    PORT("port"),
173
    PROTOCOL("protocol"),
174

175
    // SSL/TLS
176
    useSSL("useSSL"),
177
    requireSSL("requireSSL"),
178
    verifyServerCertificate("verifyServerCertificate"),
179
    trustCertificateKeyStoreUrl("trustCertificateKeyStoreUrl"),
180
    trustCertificateKeyStorePassword("trustCertificateKeyStorePassword"),
181
    trustCertificateKeyStoreType("trustCertificateKeyStoreType"),
182
    clientCertificateKeyStoreUrl("clientCertificateKeyStoreUrl"),
183
    clientCertificateKeyStorePassword("clientCertificateKeyStorePassword"),
184
    clientCertificateKeyStoreType("clientCertificateKeyStoreType"),
185
    sslMode("sslMode"),
186
    enabledSSLCipherSuites("enabledSSLCipherSuites"),
187
    enabledTLSProtocols("enabledTLSProtocols"),
188

189
    // Performance
190
    cachePrepStmts("cachePrepStmts"),
191
    prepStmtCacheSize("prepStmtCacheSize"),
192
    prepStmtCacheSqlLimit("prepStmtCacheSqlLimit"),
193
    useServerPrepStmts("useServerPrepStmts"),
194
    useLocalSessionState("useLocalSessionState"),
195
    rewriteBatchedStatements("rewriteBatchedStatements"),
196
    cacheResultSetMetadata("cacheResultSetMetadata"),
197
    cacheServerConfiguration("cacheServerConfiguration"),
198
    elideSetAutoCommits("elideSetAutoCommits"),
199
    maintainTimeStats("maintainTimeStats"),
200

201
    // Timeouts
202
    connectTimeout("connectTimeout"),
203
    socketTimeout("socketTimeout"),
204

205
    // Character encoding
206
    characterEncoding("characterEncoding"),
207
    connectionCollation("connectionCollation"),
208
    useUnicode("useUnicode"),
209

210
    // Logging
211
    logger("logger"),
212
    profileSQL("profileSQL"),
213
    useUsageAdvisor("useUsageAdvisor"),
214
    logSlowQueries("logSlowQueries"),
215
    slowQueryThresholdMillis("slowQueryThresholdMillis"),
216

217
    // Load balancing
218
    loadBalanceStrategy("loadBalanceStrategy"),
219
    loadBalanceExceptionChecker("loadBalanceExceptionChecker"),
220
    loadBalanceAutoCommitStatementThreshold("loadBalanceAutoCommitStatementThreshold"),
221
    loadBalanceConnectionGroup("loadBalanceConnectionGroup"),
222

223
    // Replication
224
    replicationConnectionGroup("replicationConnectionGroup"),
225

226
    // High availability
227
    autoReconnect("autoReconnect"),
228
    autoReconnectForPools("autoReconnectForPools"),
229
    failOverReadOnly("failOverReadOnly"),
230
    maxReconnects("maxReconnects"),
231
    retriesAllDown("retriesAllDown"),
232

233
    // Transaction
234
    autoCommit("autoCommit"),
235
    defaultTransactionIsolation("defaultTransactionIsolation"),
236

237
    // Result sets
238
    defaultFetchSize("defaultFetchSize"),
239
    maxRows("maxRows"),
240
    useCursorFetch("useCursorFetch"),
241

242
    // Server configuration
243
    connectionTimeZone("connectionTimeZone", "serverTimezone"),  // serverTimezone is an alias
244
    forceConnectionTimeZoneToSession("forceConnectionTimeZoneToSession"),
245

246
    // Metadata
247
    useInformationSchema("useInformationSchema"),
248
    getProceduresReturnsFunctions("getProceduresReturnsFunctions"),
249

250
    // Interceptors
251
    queryInterceptors("queryInterceptors"),
252
    connectionLifecycleInterceptors("connectionLifecycleInterceptors"),
253
    exceptionInterceptors("exceptionInterceptors"),
254

255
    // Authentication
256
    authenticationPlugins("authenticationPlugins"),
257
    defaultAuthenticationPlugin("defaultAuthenticationPlugin"),
258
    disabledAuthenticationPlugins("disabledAuthenticationPlugins"),
259

260
    // Other
261
    allowLoadLocalInfile("allowLoadLocalInfile"),
262
    allowMultiQueries("allowMultiQueries"),
263
    allowPublicKeyRetrieval("allowPublicKeyRetrieval"),
264
    connectionAttributes("connectionAttributes"),
265
    propertiesTransform("propertiesTransform"),
266
    zeroDateTimeBehavior("zeroDateTimeBehavior");
267

268
    private final String keyName;
269

270
    PropertyKey(String keyName) {
271
        this.keyName = keyName;
272
    }
273

274
    public String getKeyName() {
275
        return keyName;
276
    }
277

278
    public static PropertyKey fromKeyName(String keyName);
279
}
280
```
281

282
### Property Set
283

284
Interface for managing connection properties.
285

286
```java { .api }
287
package com.mysql.cj.conf;
288

289
import java.util.Properties;
290

291
public interface PropertySet {
292
    void addProperty(RuntimeProperty<?> prop);
293

294
    void removeProperty(String name);
295

296
    void removeProperty(PropertyKey key);
297

298
    <T> RuntimeProperty<T> getProperty(String name);
299

300
    <T> RuntimeProperty<T> getProperty(PropertyKey key);
301

302
    RuntimeProperty<Boolean> getBooleanProperty(String name);
303

304
    RuntimeProperty<Boolean> getBooleanProperty(PropertyKey key);
305

306
    RuntimeProperty<Integer> getIntegerProperty(String name);
307

308
    RuntimeProperty<Integer> getIntegerProperty(PropertyKey key);
309

310
    RuntimeProperty<Long> getLongProperty(String name);
311

312
    RuntimeProperty<Long> getLongProperty(PropertyKey key);
313

314
    RuntimeProperty<Integer> getMemorySizeProperty(String name);
315

316
    RuntimeProperty<Integer> getMemorySizeProperty(PropertyKey key);
317

318
    RuntimeProperty<String> getStringProperty(String name);
319

320
    RuntimeProperty<String> getStringProperty(PropertyKey key);
321

322
    <T extends Enum<T>> RuntimeProperty<T> getEnumProperty(String name);
323

324
    <T extends Enum<T>> RuntimeProperty<T> getEnumProperty(PropertyKey key);
325

326
    /**
327
     * Initializes the property set with driver properties that come from URL or passed to
328
     * the driver manager.
329
     *
330
     * @param props properties
331
     */
332
    void initializeProperties(Properties props);
333

334
    void postInitialization();
335

336
    Properties exposeAsProperties();
337

338
    /**
339
     * Reset all properties to their initial values.
340
     */
341
    void reset();
342
}
343
```
344

345
### Property Definition
346

347
Interface for property metadata.
348

349
```java { .api }
350
package com.mysql.cj.conf;
351

352
import com.mysql.cj.exceptions.ExceptionInterceptor;
353

354
public interface PropertyDefinition<T> {
355
    /**
356
     * Does the property have fixed values based constraints.
357
     *
358
     * @return true if property has fixed values based constraints
359
     */
360
    boolean hasValueConstraints();
361

362
    /**
363
     * Returns true if property has range-based constraints
364
     *
365
     * @return true if property has range-based constraints
366
     */
367
    boolean isRangeBased();
368

369
    /**
370
     * Get the property key.
371
     *
372
     * @return PropertyKey or null if it's a custom property
373
     */
374
    PropertyKey getPropertyKey();
375

376
    /**
377
     * Returns the property name.
378
     *
379
     * @return the property name
380
     */
381
    String getName();
382

383
    /**
384
     * Returns the property camel-case alias.
385
     *
386
     * @return the property camel-case alias
387
     */
388
    String getCcAlias();
389

390
    /**
391
     * Returns true if property has a camel-case alias.
392
     *
393
     * @return true if property has a camel-case alias
394
     */
395
    boolean hasCcAlias();
396

397
    /**
398
     * Returns the default value.
399
     *
400
     * @return default value
401
     */
402
    T getDefaultValue();
403

404
    /**
405
     * May the property be changed after initialization.
406
     *
407
     * @return true if the property value may be changed after initialization
408
     */
409
    boolean isRuntimeModifiable();
410

411
    /**
412
     * Returns the property description. Used for documentation.
413
     *
414
     * @return property description
415
     */
416
    String getDescription();
417

418
    /**
419
     * Returns the driver version where the property was introduced first. Used for documentation.
420
     *
421
     * @return the driver version where the property was introduced first
422
     */
423
    String getSinceVersion();
424

425
    /**
426
     * Returns the property category.
427
     *
428
     * @return property category
429
     */
430
    String getCategory();
431

432
    /**
433
     * Returns the property order. Used as preferred property position in properties table in documentation.
434
     *
435
     * @return property order
436
     */
437
    int getOrder();
438

439
    /**
440
     * Returns the list of allowable values.
441
     *
442
     * @return the list of allowable values
443
     */
444
    String[] getAllowableValues();
445

446
    /**
447
     * The lowest possible value of range-based property
448
     *
449
     * @return the lowest possible value of range-based property
450
     */
451
    int getLowerBound();
452

453
    /**
454
     * The highest possible value of range-based property
455
     *
456
     * @return the highest possible value of range-based property
457
     */
458
    int getUpperBound();
459

460
    /**
461
     * Returns the value object parsed from its string representation and checked against allowable values.
462
     *
463
     * @param value value
464
     * @param exceptionInterceptor exception interceptor
465
     * @return the value object
466
     */
467
    T parseObject(String value, ExceptionInterceptor exceptionInterceptor);
468

469
    /**
470
     * Creates instance of ReadableProperty or ModifiableProperty depending on isRuntimeModifiable() result.
471
     *
472
     * @return RuntimeProperty instance
473
     */
474
    RuntimeProperty<T> createRuntimeProperty();
475
}
476
```
477

478
### Runtime Property
479

480
Interface for runtime property values.
481

482
```java { .api }
483
package com.mysql.cj.conf;
484

485
import java.util.Properties;
486
import javax.naming.Reference;
487
import com.mysql.cj.exceptions.ExceptionInterceptor;
488

489
public interface RuntimeProperty<T> {
490
    PropertyDefinition<T> getPropertyDefinition();
491

492
    /**
493
     * Explicitly set value of this RuntimeProperty according to the self-titled property value contained in extractFrom.
494
     * This method is called during PropertySet initialization thus ignores the RUNTIME_NOT_MODIFIABLE flag.
495
     * This value will also be the initial one, i.e. resetValue() will reset to this value, not the default one.
496
     * If extractFrom does not contain such property then this RuntimeProperty remains unchanged.
497
     *
498
     * @param extractFrom Properties object containing key-value pairs usually passed from connection string
499
     * @param exceptionInterceptor exception interceptor
500
     */
501
    void initializeFrom(Properties extractFrom, ExceptionInterceptor exceptionInterceptor);
502

503
    void initializeFrom(Reference ref, ExceptionInterceptor exceptionInterceptor);
504

505
    /**
506
     * Reset to initial value (default or defined in connection string/Properties)
507
     */
508
    void resetValue();
509

510
    boolean isExplicitlySet();
511

512
    /**
513
     * Add listener for this property changes.
514
     *
515
     * @param l RuntimePropertyListener
516
     */
517
    void addListener(RuntimePropertyListener l);
518

519
    void removeListener(RuntimePropertyListener l);
520

521
    @FunctionalInterface
522
    public static interface RuntimePropertyListener {
523
        void handlePropertyChange(RuntimeProperty<?> prop);
524
    }
525

526
    /**
527
     * Get internal value representation as Object.
528
     *
529
     * @return value
530
     */
531
    T getValue();
532

533
    /**
534
     * Get initial value (default or defined in connection string/Properties)
535
     *
536
     * @return value
537
     */
538
    T getInitialValue();
539

540
    /**
541
     * Get internal value representation as String.
542
     *
543
     * @return value
544
     */
545
    String getStringValue();
546

547
    /**
548
     * Set the object value of a property directly. Validation against allowable values will be performed.
549
     *
550
     * @param value value
551
     */
552
    void setValue(T value);
553

554
    /**
555
     * Set the object value of a property directly. Validation against allowable values will be performed.
556
     *
557
     * @param value value
558
     * @param exceptionInterceptor exception interceptor
559
     */
560
    void setValue(T value, ExceptionInterceptor exceptionInterceptor);
561
}
562
```
563

564
Usage:
565

566
```java
567
// Get property from property set
568
PropertySet propSet = // ... obtained from connection
569
RuntimeProperty<Boolean> useSSL = propSet.getBooleanProperty(PropertyKey.useSSL);
570

571
System.out.println("useSSL: " + useSSL.getValue());
572
System.out.println("Explicitly set: " + useSSL.isExplicitlySet());
573

574
// Modify property
575
useSSL.setValue(true);
576

577
// Add listener
578
useSSL.addListener(new RuntimePropertyListener() {
579
    public void handlePropertyChange(RuntimeProperty<?> prop) {
580
        System.out.println("useSSL changed to " + prop.getValue());
581
    }
582
});
583

584
// Get property definition
585
PropertyDefinition<Boolean> def = useSSL.getPropertyDefinition();
586
System.out.println("Property: " + def.getName());
587
System.out.println("Default: " + def.getDefaultValue());
588
System.out.println("Description: " + def.getDescription());
589
```
590

591
### Connection Properties Transform
592

593
Interface for transforming connection properties.
594

595
```java { .api }
596
package com.mysql.cj.conf;
597

598
public interface ConnectionPropertiesTransform {
599
    // Transform properties before connection
600
    Properties transformProperties(Properties props);
601
}
602
```
603

604
Usage:
605

606
```java
607
// Implement custom transform
608
public class MyPropertiesTransform implements ConnectionPropertiesTransform {
609
    public Properties transformProperties(Properties props) {
610
        // Modify properties as needed
611
        props.setProperty("useSSL", "true");
612
        return props;
613
    }
614
}
615

616
// Use in connection URL
617
String url = "jdbc:mysql://localhost:3306/mydb" +
618
             "?propertiesTransform=com.mycompany.MyPropertiesTransform";
619
Connection conn = DriverManager.getConnection(url, "user", "pass");
620
```
621

622
### JDBC Property Set
623

624
JDBC-specific extension of PropertySet interface.
625

626
```java { .api }
627
package com.mysql.cj.jdbc;
628

629
import java.sql.DriverPropertyInfo;
630
import java.sql.SQLException;
631
import java.util.List;
632
import com.mysql.cj.conf.PropertySet;
633

634
public interface JdbcPropertySet extends PropertySet {
635
    /**
636
     * Exposes all ConnectionPropertyInfo instances as DriverPropertyInfo
637
     *
638
     * @return a List of all ConnectionPropertyInfo instances, as DriverPropertyInfo
639
     * @throws SQLException if an error occurs
640
     */
641
    List<DriverPropertyInfo> exposeAsDriverPropertyInfo() throws SQLException;
642
}
643
```
644

645
### Database URL Container
646

647
Interface for objects that provide database URLs.
648

649
```java { .api }
650
package com.mysql.cj.conf;
651

652
public interface DatabaseUrlContainer {
653
    // Get database URL
654
    String getDatabase();
655
}
656
```
657

658
### Hosts List View
659

660
Enumeration for different views of host lists.
661

662
```java { .api }
663
package com.mysql.cj.conf;
664

665
public enum HostsListView {
666
    // All hosts
667
    ALL,
668
    // Sources only (for replication)
669
    SOURCES,
670
    // Replicas only (for replication)
671
    REPLICAS;
672
}
673
```
674