DBGateway FAQ

DBGateway directory structure

dbgateway
|-- bin
|   |-- dbgateway
|   \-- dbgateway-manager
|-- conf
|   |-- dbgateway.conf
|   \-- server.crt
\-- log
    |-- dbgateway.err
    |-- dbgateway.log
    \-- dbgateway_manager.log    

Basic operations

• View the DBGateway log

  • The full path to the DBGateway log file is /opt/dbgateway/log/dbgateway.log.

  • The log file is a plain text file that you can view with standard tools such as vim, tail, cat, and less.

  If Database Autonomy Service (DAS) support staff request the DBGateway log for troubleshooting, log on to the server where DBGateway is deployed. Run the following command to retrieve the last 200 log entries and provide the output to them.

  tail -n 200 /opt/dbgateway/log/dbgateway.log

• Check if the DBGateway process is running

  1. Log on to the DAS console.

  2. In the left-side navigation pane, click Resource Management > DBGateways.

  3. On the DBGateways page, check the Current Status of the DBGateway.

     If the Current Status is Normal, the DBGateway process is running. Otherwise, run the following command on the server where DBGateway is deployed:

     /opt/dbgateway/bin/dbgateway-manager -d status

     • If the DBGateway process is running, the command returns:

       DBGateway is running.

     • If the DBGateway process is not running, the command returns:

       DBGateway is dead.

     Note

     This check only confirms that the DBGateway process exists, not that it is functioning correctly.

• Restart DBGateway

  1. Check if the DBGateway process is running as described in the previous section.

  2. Restart DBGateway.

     • If the DBGateway process is running:

       • On the DBGateways page, find the DBGateway and click Management > Restart in the Actions column.

         

       • Alternatively, run the following command on the server where DBGateway is deployed:

         /opt/dbgateway/bin/dbgateway-manager -d restart

     • If the DBGateway process is not running:

       This operation is unavailable in the DAS console. You must restart the process from the command line. Run the following command on the server where DBGateway is deployed:

       /opt/dbgateway/bin/dbgateway-manager -d restart

• Upgrade DBGateway

  On the DBGateways page, find the DBGateway and click Management > Upgrade in the Actions column.

• Stop DBGateway

  • On the DBGateways page, find the DBGateway and click Management > Stop in the Actions column.

  • Alternatively, run the following command on the server where DBGateway is deployed:

     /opt/dbgateway/bin/dbgateway-manager -d stop

• Delete DBGateway

  Note

  • After you delete a DBGateway, all DAS features for the associated database instances become unavailable.

  • You cannot delete a DBGateway whose Current Status is Normal. You must stop the DBGateway first.

  1. On the DBGateways page, find the DBGateway and click Management > Delete in the Actions column.

  2. Optional: Run the following command on the server where DBGateway is deployed to delete the installation directory.

     rm -rf /opt/dbgateway

• Reinstall DBGateway

  After you delete DBGateway, you can redeploy it on the same server. Use the deployment command provided in the DAS console when you add the database instance.

Deployment troubleshooting

When you connect a database instance by using a database gateway in centralized mode or a database gateway in host mode, you receive a deployment command. The following command is an example. The id and token are for demonstration only. Use the values from your deployment command.

sudo wget -O install-dbgateway http://hdm-dbgateway-cn-hangzhou.oss-cn-hangzhou-internal.aliyuncs.com/DBGateway/install/install-dbgateway && sudo /bin/bash install-dbgateway --id xxx --token xxx --endpoint master-hdm-cn-hangzhou-inner.aliyuncs.com --region cn-hangzhou

• Cannot download the DBGateway deployment script

  • If you see a wget command not found message, the wget utility is not installed. Run one of the following commands to install wget:

    sudo apt-get install wget

    or

    yum -y install wget

  • Check if your server can connect to the Object Storage Service (OSS) network.

    On your server, ping the OSS domain. In this example, the domain is hdm-dbgateway-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com. Use the domain from your deployment command.

    ping hdm-dbgateway-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com

    • If the command returns the following message, the domain cannot be resolved. Check your DNS server settings and ensure the DNS service is working correctly.

      ping: unknown host hdm-dbgateway-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com  

    • If the ping command hangs with no output, the network connection has failed. Check the following:

      • The server's network configuration.

      • The server's network access type (Internet or VPC).

      • If the network access type is VPC, the selected region.

• Test connectivity to the DAS server

  Run the following command on the server where you want to deploy DBGateway. In this example, the DAS server domain is master-hdm-cn-hangzhou.aliyuncs.com. Use the domain from your deployment command.

  telnet master-hdm-cn-hangzhou.aliyuncs.com 80

  • If the command returns Name or service not known, the domain cannot be resolved. Check your DNS server settings and ensure the DNS service is working correctly.

  • If the command returns Trying followed by an IP address, such as Trying 10.0.XX.XX, and then hangs, the network is unreachable. Check the following:

    • The server's network configuration.

    • The server's network access type (Internet or VPC).

    • If the network access type is VPC, the selected region.

  • If the command returns the following output:

    Connected to master-hdm-cn-hangzhou.aliyuncs.com.  Escape character is '^]'.

    The connection to the DAS server is successful. If DBGateway still fails to start, refer to the previous sections and view the DBGateway log for further troubleshooting.

Runtime troubleshooting

• Authentication failed or insufficient permissions

  • Ensure that the authorized account has the required permissions. The following examples use an authorized account named das_test.

    • MySQL

      CREATE USER 'das_test'@'%' IDENTIFIED BY 'password';
      GRANT SHOW DATABASES, PROCESS, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'das_test'@'%';
      GRANT SELECT ON *.*  TO 'das_test'@'%';

    • PostgreSQL

      CREATE USER das_test PASSWORD 'password';
      GRANT SELECT ON ALL TABLES IN SCHEMA PUBLIC TO das_test;
      /* Optional. This permission is required to collect slow query logs and SQL statements. */ 
      ALTER USER das_test WITH SUPERUSER;

    • MongoDB

      use admin;
      db.createUser({user:'das_test',pwd:'password',roles:[{role:'readAnyDatabase', db:'admin'}, {role:'clusterMonitor', db:'admin'}, {role: 'hostManager', db: 'admin'}]})

      If you receive an (Unauthorized) not authorized on admin to execute command error, grant the following permissions to the authorized account:

      db.grantRolesToUser("das_test", [{db: "local", role: "dbAdmin"},{db: "config", role: "dbAdmin"},{db: "admin", role: "dbAdminAnyDatabase"}])

    • Redis

      Redis does not have an account system. Ensure that the password is correct. To change the Redis password, modify the requirepass option in its configuration file and restart the Redis service. For more information, see Redis configuration.

  • Ensure that the account and password are correct. We recommend that you test the credentials by connecting to the database instance remotely from the DBGateway server.

  • Restart DBGateway and check if the instance is authorized successfully.

  • Upgrade DBGateway to the latest version.

• Connection failure

  A connection failure occurs when DBGateway cannot connect to a database instance. Check the following possible causes:

  • Check if the database instance is running properly.

    If a database instance such as MySQL, PostgreSQL, MongoDB, or Redis is not running, check if its process exists.

  • Check the network connectivity between the DBGateway server and the database instance (for example, MySQL, PostgreSQL, MongoDB, or Redis). Run the following command to confirm:

    telnet <database_instance_IP_or_domain> <database_instance_port>  

    Example:

    telnet 192.168.XX.XX 3306

    • If the command returns the following message, the network connection is normal. View the DBGateway log for further investigation.

      Connected to 192.168.XX.XX
      Escape character is '^]'.

    • If the preceding message is not returned, a network connectivity issue exists. This issue is often caused by network isolation between servers, routing settings, a firewall, or a database instance configured to deny remote connections.

• Monitoring issues

  • Check the running status of DBGateway.

  • Restart DBGateway and check if monitoring resumes.

  • Upgrade DBGateway to the latest version.

• Status is stuck at Authorized. Verifying

  After successful authorization, the instance status should change to Normal Connection within one to two minutes. If the status remains Authorized. Verifying for longer than two minutes, perform the following steps:

  • Check the running status of DBGateway.

  • Restart DBGateway and check if the instance is authorized successfully.

  • Upgrade DBGateway to the latest version.