Key Management Service:Secret JDBC client

Usage notes

• Supported secret types: generic secrets and RDS secrets.

  • If you use an RDS secret, we recommend that you use a dual-account managed RDS secret.

  • If you use a generic secret, the secret value must be in the following JSON format.

    {
        "AccountName":"<your_database_account_username>",
        "AccountPassword":"<your_database_account_password>"
    }

• Supported programming language: Java 8 or later.

• Supported database connection pools: c3p0, DBCP, and Druid.

  Important

  The default HikariCP connection pool in Spring Boot does not handle JDBC error codes in a standard way. This may cause the KMS secret refresh to fail.

Scenario 1: Retrieve secret values using a shared gateway

You can use the Internet or a virtual private cloud (VPC). Supported RAM-based authentication methods include instance RAM roles for Elastic Compute Service (ECS) instances, RamRoleArn, Security Token Service (STS) tokens, and AccessKeys. For more information, see Manage access credentials.

Scenario 2: Retrieve secret values using a dedicated gateway (not recommended)

This scenario uses a KMS private network. Only a ClientKey can be used as the access credential.

• Method 1: Quick creation

  Suitable for quick testing and development scenarios. This method uses a default permission policy that cannot be modified. Your application will have access to all keys and secrets in the specified KMS instance.

• Method 2: Standard creation

  Use this method to configure fine-grained access permissions for resources.

Connect to a database using JDBC

• MySQL database

  Note

  Replace #your-mysql-secret-name#, <your-mysql-ip>, <your-mysql-port>, and <your-database-name> in the sample code with the actual secret name, server IP address, port, and database name.

  import java.sql.Connection;
  import java.sql.DriverManager;
  import java.sql.SQLException;
  
  public class SecretManagerJDBCSample {
      public static void main(String[] args) throws Exception {
          // Load the Alibaba Cloud secrets JDBC client, com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver.
          Class.forName("com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver");
          Connection connect = null;
          try {
              connect = DriverManager.getConnection("secrets-manager:mysql://<your-mysql-ip>:<your-mysql-port>/<your-database-name>", "#your-mysql-secret-name#","");
          } catch(SQLException e) {
              e.printStackTrace();
          }
      }
  }

• SQL Server database

  Note

  Replace #your-sqlserver-secret-name#, <your-sqlserver-ip>, <your-sqlserver-port>, and <your-database-name> in the sample code with your secret name, server IP address, port, and database name.

  import java.sql.Connection;
  import java.sql.DriverManager;
  import java.sql.SQLException;
  
  public class SecretManagerJDBCSqlServerSample {
  
      public static void main(String[] args) throws Exception{
          // Load the Alibaba Cloud secrets JDBC client, com.aliyun.kms.secretsmanager.MssqlSecretsManagerSimpleDriver.
          Class.forName("com.aliyun.kms.secretsmanager.MssqlSecretsManagerSimpleDriver");
          Connection connect = null;
          try {
              connect = DriverManager.getConnection("secrets-manager:sqlserver://<your-sqlserver-ip>:<your-sqlserver-port>;databaseName=<your-database-name>", "#your-sqlserver-secret-name#", "");
          }  catch (SQLException e) {
              e.printStackTrace();
          }
      }
  }

• PostgreSQL database

  Note

  Replace #your-postgresql-secret-name#, <your-postgresql-ip>, <your-postgresql-port>, and <your-database-name> in the sample code with the actual secret name, server IP address, port, and database name.

  import java.sql.Connection;
  import java.sql.DriverManager;
  import java.sql.SQLException;
  
  public class SecretManagerJDBCPostgreSQLSample {
      public static void main(String[] args) throws Exception {
          // Load the Alibaba Cloud secrets JDBC client, com.aliyun.kms.secretsmanager.PostgreSQLSecretManagerSimpleDriver.
          Class.forName("com.aliyun.kms.secretsmanager.PostgreSQLSecretManagerSimpleDriver");
          Connection connect = null;
          try {
              connect = DriverManager.getConnection("secrets-manager:postgresql://<your-postgresql-ip>:<your-postgresql-port>/<your-database-name>", "#your-postgresql-secret-name#", "");
          } catch (SQLException e) {
              e.printStackTrace();
          }
      }
  }

• MariaDB database

  Note

  Replace #your-mariadb-secret-name#, <your-mariadb-ip>, <your-mariadb-port>, and <your-database-name> in the sample code with the actual secret name, server IP address, port, and database name.

  import java.sql.Connection;
  import java.sql.DriverManager;
  import java.sql.SQLException;
  
  public class SecretManagerJDBCMarialDBSample {
  
  	public static void main(String[] args) throws Exception{
  		// Load the Alibaba Cloud secrets JDBC client, com.aliyun.kms.secretsmanager.MariaDBSecretManagerSimpleDriver.
  		Class.forName("com.aliyun.kms.secretsmanager.MariaDBSecretManagerSimpleDriver");
  		Connection connect = null;
  		try {
  			connect = DriverManager.getConnection("secrets-manager:mariadb://<your-mariadb-ip>:<your-mariadb-port>/<your-database-name>", "#your-mariadb-secret-name#", "");
  		}  catch (SQLException e) {
  			e.printStackTrace();
  		}
  	}
  }

Connect to a database using a connection pool

Configure c3p0.user, c3p0.driverClass, and c3p0.jdbcUrl in the c3p0.properties configuration file. Set c3p0.user to the name of the secret and c3p0.driverClass to the name of the Alibaba Cloud secrets JDBC driver class. The value of c3p0.jdbcUrl must start with secrets-manager.

• MySQL database

  Note

  Replace #your-mysql-secret-name#, <your-mysql-ip>, <your-mysql-port>, and <your-database-name> in the sample code with the actual secret name, server IP address, port, and database name.

  c3p0.user=#your-mysql-secret-name#
  c3p0.driverClass=com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver
  c3p0.jdbcUrl=secrets-manager:mysql://<your-mysql-ip>:<your-mysql-port>/<your-database-name>

• SQL Server database

  Note

  Replace #your-sqlserver-secret-name#, <your-sqlserver-ip>, <your-sqlserver-port>, and <your-database-name> in the sample code with the actual secret name, server IP address, port, and database name.

  c3p0.user=#your-sqlserver-secret-name#
  c3p0.driverClass=com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver
  c3p0.jdbcUrl=secrets-manager:sqlserver://<your-sqlserver-ip>:<your-sqlserver-port>/<your-database-name>

• PostgreSQL database

  Note

  Replace #your-postgresql-secret-name#, <your-postgresql-ip>, <your-postgresql-port>, and <your-database-name> in the sample code with the actual secret name, server IP address, port, and database name.

  c3p0.user=#your-postgresql-secret-name#
  c3p0.driverClass=com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver
  c3p0.jdbcUrl=secrets-manager:postgresql://<your-postgresql-ip>:<your-postgresql-port>/<your-database-name>

• MariaDB database

  Note

  Replace #your-mariadb-secret-name#, <your-mariadb-ip>, <your-mariadb-port>, and <your-database-name> in the sample code with the actual secret name, server IP address, port, and database name.

  c3p0.user=#your-mariadb-secret-name#
  c3p0.driverClass=com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver
  c3p0.jdbcUrl=secrets-manager:mariadb://<your-mariadb-ip>:<your-mariadb-port>/<your-database-name>

Connect to a database using a data source

This example uses a c3p0 ComboPooledDataSource and a MySQL database. Add the following configuration to the Spring configuration file.

<bean id="dataSource" class="com.mchange.v2.c3p0.ComboPooledDataSource" >
      <property name="driverClass" value="com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver" />
      <property name="user" value="#your-mysql-secret-name#" />
      <property name="jdbcUrl" value="secrets-manager:mysql://<your-mysql-ip>:<your-mysql-port>/<your-database-name>" />
      <property name="maxPoolSize" value="***" />
      <property name="minPoolSize" value="***" />
      <property name="initialPoolSize" value="***" />
  </bean>
  <bean id="jdbcTemplate" class="org.springframework.jdbc.core.JdbcTemplate" >
      <property name="dataSource" ref="dataSource" />
  </bean>

Connect to a database using a Druid connection pool

This example uses a MySQL database. You must modify the following properties in the configuration file.

• Using a properties configuration file

  username=#your-mysql-secret-name#
  driverClassName=com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver
  url=secrets-manager:mysql://<your-mysql-ip>:<your-mysql-port>/<your-database-name>

• Using bean configuration

  • Method 1: XML configuration file

    <bean id="dataSource" class="com.alibaba.druid.pool.DruidDataSource" init-method="init" destroy-method="close"> 
         <property name="username" value="${your-mysql-secret-name}" />
         <property name="driverClassName" value="com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver" />
         <property name="url" value="secrets-manager:mysql://<your-mysql-ip>:<your-mysql-port>/<your-database-name>" />
    </bean>
    

  • Method 2: Property injection

    Create a driver class in the application to load database connection information.

    @Configuration
    public class DataConfig {
    
        @Value("${your-mysql-secret-name}")
        private String username;
    
        @Value("com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver")
        private String driverClassName;
    
        @Value("secrets-manager:mysql://<your-mysql-ip>:<your-mysql-port>/<your-database-name>")
        private String url;
    
        @Bean(name = "dataSource",initMethod = "init",destroyMethod = "close")
        public DruidDataSource dataSource(){
            DruidDataSource druidDataSource = new DruidDataSource();
            druidDataSource.setUsername(username);
            druidDataSource.setDriverClassName(driverClassName);
            druidDataSource.setUrl(url);
            return druidDataSource;
        }
    }