Skip to content

Commit 4a0d15b

Browse files
sergiyvamzsergiyvamz
authored
Configuration Profiles documentation (#738)
1 parent 65f99f9 commit 4a0d15b

File tree

5 files changed

+125
-46
lines changed

5 files changed

+125
-46
lines changed

‎README.md‎

Lines changed: 31 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -66,32 +66,37 @@ You can find our driver by searching in The Central Repository with GroupId and
6666

6767
## Properties
6868

69-
| Parameter | Reference | Documentation Link |
70-
|----------------------------------------|:--------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------------------------:|
71-
| `wrapperDialect` | `DialectManager.DIALECT` | [Dialects](/docs/using-the-jdbc-driver/DatabaseDialects.md), and whether you should include it. |
72-
| `wrapperPlugins` | `PropertyDefinition.PLUGINS` | |
73-
| `secretsManagerSecretId` | `AwsSecretsManagerConnectionPlugin.SECRET_ID_PROPERTY` | [SecretsManagerPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheAwsSecretsManagerPlugin.md) |
74-
| `secretsManagerRegion` | `AwsSecretsManagerConnectionPlugin.REGION_PROPERTY` | [SecretsManagerPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheAwsSecretsManagerPlugin.md) |
75-
| `wrapperDriverName` | `DriverMetaDataConnectionPlugin.WRAPPER_DRIVER_NAME` | [DriverMetaDataConnectionPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheDriverMetadataConnectionPlugin.md) |
76-
| `failoverMode` | `FailoverConnectionPlugin.FAILOVER_MODE` | [FailoverPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md) |
77-
| `clusterInstanceHostPattern` | `AuroraHostListProvider.CLUSTER_INSTANCE_HOST_PATTERN` | [FailoverPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md) |
78-
| `enableClusterAwareFailover` | `FailoverConnectionPlugin.ENABLE_CLUSTER_AWARE_FAILOVER` | [FailoverPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md) |
79-
| `failoverClusterTopologyRefreshRateMs` | `FailoverConnectionPlugin.FAILOVER_CLUSTER_TOPOLOGY_REFRESH_RATE_MS` | [FailoverPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md) |
80-
| `failoverReaderConnectTimeoutMs` | `FailoverConnectionPlugin.FAILOVER_READER_CONNECT_TIMEOUT_MS` | [FailoverPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md) |
81-
| `failoverTimeoutMs` | `FailoverConnectionPlugin.FAILOVER_TIMEOUT_MS` | [FailoverPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md) |
82-
| `failoverWriterReconnectIntervalMs` | `FailoverConnectionPlugin.FAILOVER_WRITER_RECONNECT_INTERVAL_MS` | [FailoverPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md) |
83-
| `failureDetectionCount` | `HostMonitoringConnectionPlugin.FAILURE_DETECTION_COUNT` | [HostMonitoringPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md) |
84-
| `failureDetectionEnabled` | `HostMonitoringConnectionPlugin.FAILURE_DETECTION_ENABLED` | [HostMonitoringPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md) |
85-
| `failureDetectionInterval` | `HostMonitoringConnectionPlugin.FAILURE_DETECTION_INTERVAL` | [HostMonitoringPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md) |
86-
| `failureDetectionTime` | `HostMonitoringConnectionPlugin.FAILURE_DETECTION_TIME` | [HostMonitoringPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md) |
87-
| `monitorDisposalTime` | `MonitorServiceImpl.MONITOR_DISPOSAL_TIME_MS` | [HostMonitoringPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md) |
88-
| `iamDefaultPort` | `IamAuthConnectionPlugin.IAM_DEFAULT_PORT` | [IamAuthenticationPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md) |
89-
| `iamHost` | `IamAuthConnectionPlugin.IAM_HOST` | [IamAuthenticationPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md) |
90-
| `iamRegion` | `IamAuthConnectionPlugin.IAM_REGION` | [IamAuthenticationPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md) |
91-
| `iamExpiration` | `IamAuthConnectionPlugin.IAM_EXPIRATION` | [IamAuthenticationPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md) |
92-
| `wrapperLogUnclosedConnections` | `PropertyDefinition.LOG_UNCLOSED_CONNECTIONS` | [LogUnclosedConnections](./docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#logging) |
93-
| `wrapperLoggerLevel` | `PropertyDefinition.LOGGER_LEVEL` | [LoggingLevel](./docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#logging) |
94-
| `wrapperProfileName` | `PropertyDefinition.PROFILE_NAME` | [ConfigurationProfiles](./docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#configuration-profiles) |
69+
| Parameter | Reference | Documentation Link |
70+
|----------------------------------------|:--------------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------------------------------------:|
71+
| `wrapperDialect` | `DialectManager.DIALECT` | [Dialects](/docs/using-the-jdbc-driver/DatabaseDialects.md), and whether you should include it. |
72+
| `wrapperPlugins` | `PropertyDefinition.PLUGINS` | |
73+
| `secretsManagerSecretId` | `AwsSecretsManagerConnectionPlugin.SECRET_ID_PROPERTY` | [SecretsManagerPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheAwsSecretsManagerPlugin.md) |
74+
| `secretsManagerRegion` | `AwsSecretsManagerConnectionPlugin.REGION_PROPERTY` | [SecretsManagerPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheAwsSecretsManagerPlugin.md) |
75+
| `wrapperDriverName` | `DriverMetaDataConnectionPlugin.WRAPPER_DRIVER_NAME` | [DriverMetaDataConnectionPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheDriverMetadataConnectionPlugin.md) |
76+
| `failoverMode` | `FailoverConnectionPlugin.FAILOVER_MODE` | [FailoverPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md) |
77+
| `clusterInstanceHostPattern` | `AuroraHostListProvider.CLUSTER_INSTANCE_HOST_PATTERN` | [FailoverPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md) |
78+
| `enableClusterAwareFailover` | `FailoverConnectionPlugin.ENABLE_CLUSTER_AWARE_FAILOVER` | [FailoverPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md) |
79+
| `failoverClusterTopologyRefreshRateMs` | `FailoverConnectionPlugin.FAILOVER_CLUSTER_TOPOLOGY_REFRESH_RATE_MS` | [FailoverPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md) |
80+
| `failoverReaderConnectTimeoutMs` | `FailoverConnectionPlugin.FAILOVER_READER_CONNECT_TIMEOUT_MS` | [FailoverPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md) |
81+
| `failoverTimeoutMs` | `FailoverConnectionPlugin.FAILOVER_TIMEOUT_MS` | [FailoverPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md) |
82+
| `failoverWriterReconnectIntervalMs` | `FailoverConnectionPlugin.FAILOVER_WRITER_RECONNECT_INTERVAL_MS` | [FailoverPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md) |
83+
| `failureDetectionCount` | `HostMonitoringConnectionPlugin.FAILURE_DETECTION_COUNT` | [HostMonitoringPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md) |
84+
| `failureDetectionEnabled` | `HostMonitoringConnectionPlugin.FAILURE_DETECTION_ENABLED` | [HostMonitoringPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md) |
85+
| `failureDetectionInterval` | `HostMonitoringConnectionPlugin.FAILURE_DETECTION_INTERVAL` | [HostMonitoringPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md) |
86+
| `failureDetectionTime` | `HostMonitoringConnectionPlugin.FAILURE_DETECTION_TIME` | [HostMonitoringPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md) |
87+
| `monitorDisposalTime` | `MonitorServiceImpl.MONITOR_DISPOSAL_TIME_MS` | [HostMonitoringPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md) |
88+
| `iamDefaultPort` | `IamAuthConnectionPlugin.IAM_DEFAULT_PORT` | [IamAuthenticationPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md) |
89+
| `iamHost` | `IamAuthConnectionPlugin.IAM_HOST` | [IamAuthenticationPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md) |
90+
| `iamRegion` | `IamAuthConnectionPlugin.IAM_REGION` | [IamAuthenticationPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md) |
91+
| `iamExpiration` | `IamAuthConnectionPlugin.IAM_EXPIRATION` | [IamAuthenticationPlugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md) |
92+
| `wrapperLogUnclosedConnections` | `PropertyDefinition.LOG_UNCLOSED_CONNECTIONS` | [AWS Advanced JDBC Driver Parameters](./docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#aws-advanced-jdbc-driver-parameters) |
93+
| `wrapperLoggerLevel` | `PropertyDefinition.LOGGER_LEVEL` | [Logging](./docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#logging) |
94+
| `wrapperProfileName` | `PropertyDefinition.PROFILE_NAME` | [Configuration Profiles](./docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#configuration-profiles) |
95+
| `autoSortWrapperPluginOrder` | `PropertyDefinition.AUTO_SORT_PLUGIN_ORDER` | [Plugins](./docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#plugins) |
96+
| `loginTimeout` | `PropertyDefinition.LOGIN_TIMEOUT` | [AWS Advanced JDBC Driver Parameters](./docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#aws-advanced-jdbc-driver-parameters) |
97+
| `connectTimeout` | `PropertyDefinition.CONNECT_TIMEOUT` | [AWS Advanced JDBC Driver Parameters](./docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#aws-advanced-jdbc-driver-parameters) |
98+
| `socketTimeout` | `PropertyDefinition.SOCKET_TIMEOUT` | [AWS Advanced JDBC Driver Parameters](./docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#aws-advanced-jdbc-driver-parameters) |
99+
| `tcpKeepAlive` | `PropertyDefinition.TCP_KEEP_ALIVE` | [AWS Advanced JDBC Driver Parameters](./docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#aws-advanced-jdbc-driver-parameters) |
95100

96101
**A Secret ARN** has the following format: `arn:aws:secretsmanager:<Region>:<AccountId>:secret:SecretName-6RandomCharacters`
97102

‎docs/files/configuration-profile-presets.pdf‎

138 KB
Binary file not shown.

‎docs/images/configuration-presets.png‎

132 KB
Loading

‎docs/using-the-jdbc-driver/ConfigurationPresets.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Configuration Presets
2+
3+
## What is a Configuration Preset?
4+
5+
A Configuration Preset is a [configuration profile](./UsingTheJdbcDriver.md#configuration-profiles) that has already been set up by the AWS JDBC Driver team. Preset configuration profiles are optimized, profiled, verified and can be used right away. If the existing presets do not cover an exact use case, users can also create their own configuration profiles based on the built-in presets.
6+
7+
## Using Configuration Presets
8+
9+
The Configuration Preset name should be specified with the [`wrapperProfileName`](#connection-plugin-manager-parameters) parameter.
10+
11+
```java
12+
properties.setProperty("wrapperProfileName", "A2");
13+
```
14+
15+
Users can create their own custom configuration profiles based on built-in configuration presets.
16+
17+
Users can not delete built-in configuration presets.
18+
19+
```java
20+
// Create a new configuration profile "myNewProfile" based on "A2" configuration preset
21+
ConfigurationProfileBuilder.from("A2")
22+
.withName("myNewProfile")
23+
.withDialect(new CustomDatabaseDialect())
24+
.buildAndSet();
25+
26+
properties.setProperty("wrapperProfileName", "myNewProfile");
27+
```
28+
29+
## Existing Configuration Presets
30+
31+
Configuration Presets are optimized for 3 main user scenarios. They are:
32+
- **No connection pool** preset family: `A`, `B`, `C`
33+
- AWS JDBC Driver **Internal connection pool** preset family: `D`, `E`, `F`
34+
- **External connection pool** preset family: `G`, `H`, `I`
35+
36+
Some preset names may include a number, like `A0`, `A1`, `A2`, `D0`, `D1`, etc. Usually, the number represent sensitivity or timing variations for the same preset. For example, `A0` is optimized for normal network outage sensitivity and normal response time, while `A1` is less sensitive. Please take into account that more aggressive presets tend to cause more false positive failure detections. More details can be found in this file: [ConfigurationProfilePresetCodes.java](./../../wrapper/src/main/java/software/amazon/jdbc/profile/ConfigurationProfilePresetCodes.java)
37+
38+
Choosing the right configuration preset for your application can be a challenging task. Many presets could potentially fit the needs of your application. Various user application requirements and goals are presented in the following table and organized to help you identify the most suitable presets for your application.
39+
40+
PDF version of the following table can be found [here](./../files/configuration-profile-presets.pdf).
41+
42+
<div style="text-align:center"><img src="../images/configuration-presets.png" /></div>

0 commit comments

Comments
 (0)