Skip to content

Commit a76d187

Browse files
crystall-bitquillcrystall-bitquill
authored
Add documentation for database dialects (#409)
Add documentation for database dialects
1 parent 3f21dfb commit a76d187

File tree

3 files changed

+47
-0
lines changed

3 files changed

+47
-0
lines changed

‎docs/Documentation.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
- [Data Sources](/docs/using-the-jdbc-driver/DataSource.md)
66
- [Logging](/docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#logging)
77
- [JDBC Wrapper Parameters](/docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#aws-advanced-jdbc-driver-parameters)
8+
- [Database Dialects](/docs/using-the-jdbc-driver/DatabaseDialects.md)
89
- [Plugins](/docs/using-the-jdbc-driver/UsingTheJdbcDriver.md#plugins)
910
- [Failover Plugin](/docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md)
1011
- [Failover Configuration Guide](/docs/using-the-jdbc-driver/FailoverConfigurationGuide.md)

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

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Database Dialects
2+
3+
## What are database dialects?
4+
The AWS Advanced JDBC Driver is a wrapper that requires an underlying driver, and it is meant to be compatible with any JDBC driver. Database dialects help the AWS JDBC Driver determine what kind of underlying database is being used. To function correctly, the AWS JDBC Driver requires details unique to specific databases such as the default port number or the method to get the current host from the database. These details can be defined and provided to the AWS JDBC Driver by using database dialects.
5+
6+
## Configuration Parameters
7+
| Name | Required | Description | Example |
8+
|------------------|----------------------|------------------------------------------------------------------------------------|-----------------------------------------------|
9+
| `wrapperDialect` | No (see notes below) | The [dialect code](#list-of-available-dialect-codes) of the desired database type. | `DialectCodes.AURORA_MYSQL` or `aurora-mysql` |
10+
11+
> **NOTES:**
12+
>
13+
> The `wrapperDialect` parameter is not required. When it is not provided by the user, the AWS JDBC Driver will attempt to determine which of the existing dialects to use based on other connection details. However, if the dialect is known by the user, it is preferable to set the `wrapperDialect` parameter because it will take time to resolve the dialect.
14+
15+
### List of Available Dialect Codes
16+
Dialect codes specify what kind of database any connections will be made to.
17+
18+
| Dialect Code Reference | Value | Database |
19+
|------------------------|----------------|------------------------------------------------------------------------------------------------|
20+
| `AURORA_MYSQL` | `aurora-mysql` | Aurora MySQL |
21+
| `RDS_MYSQL` | `rds-mysql` | Amazon RDS MySQL |
22+
| `MYSQL` | `mysql` | MySQL |
23+
| `AURORA_PG` | `aurora-pg` | Aurora PostgreSQL |
24+
| `RDS_PG` | `rds-pg` | Amazon RDS PostgreSQL |
25+
| `PG` | `pg` | PostgreSQL |
26+
| `MARIADB` | `mariadb` | MariaDB |
27+
| `CUSTOM` | `custom` | See [custom dialects](#custom-dialects). This code is not required when using custom dialects. |
28+
| `UNKNOWN` | `unknown` | Unknown. Although this code is available, do not use it as it will result in errors. |
29+
30+
## Custom Dialects
31+
If you are interested in using the AWS JDBC Driver but your desired database type is not currently supported, it is possible to create a custom dialect.
32+
33+
To create a custom dialect, implement the [`Dialect`](/wrapper/src/main/java/software/amazon/jdbc/dialect/Dialect.java) interface. For databases clusters that are aware of their topology, the [`TopologyAwareDatabaseCluster`](/wrapper/src/main/java/software/amazon/jdbc/dialect/TopologyAwareDatabaseCluster.java) interface should also be implemented. See the following classes for examples:
34+
35+
- [PgDialect](/wrapper/src/main/java/software/amazon/jdbc/dialect/PgDialect.java)
36+
- This is a generic dialect that should work with any PostgreSQL database.
37+
- [AuroraPgDialect](/wrapper/src/main/java/software/amazon/jdbc/dialect/AuroraPgDialect.java)
38+
- This dialect is an extension of PgDialect, but also implements the `TopologyAwareDatabaseCluster` interface.
39+
40+
Once the custom dialect class has been created, tell the AWS JDBC Driver to use it with the `setCustomDialect` method in the `DialectManager` class. It is not necessary to set the `wrawpperDialect` parameter. See below for an example:
41+
42+
```java
43+
Dialect myDialect = new CustomDialect();
44+
DialectManager.setCustomDialect(myDialect);
45+
```

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ These parameters are applicable to any instance of the AWS JDBC Driver.
5252
| `database` | `String` | No | Database name. | `null` |
5353
| `user` | `String` | No | Database username. | `null` |
5454
| `password` | `String` | No | Database password. | `null` |
55+
| `wrapperDialect` | `String` | No | Please see [this page on database dialects](/docs/using-the-jdbc-driver/DatabaseDialects.md), and whether you should include it. | `null` |
5556

5657
## Plugins
5758
The AWS JDBC Driver uses plugins to execute JDBC methods. You can think of a plugin as an extensible code module that adds extra logic around any JDBC method calls. The AWS JDBC Driver has a number of [built-in plugins](#list-of-available-plugins) available for use.

0 commit comments

Comments
 (0)