Development Tools

DBeaver User Guide

| Product: DBeaver

Overview

This guide provides comprehensive instructions for deploying and using the cloudimg DBeaver AMI on Amazon Web Services. The AMI delivers a fully preconfigured Windows Server instance with DBeaver installed and ready to use, enabling you to connect to and manage databases immediately after launch.

DBeaver is a free, universal database management tool that supports all popular databases including MySQL, PostgreSQL, MariaDB, SQLite, Oracle, SQL Server, Amazon Redshift, Amazon Aurora, and many more. It provides a powerful SQL editor, data visualization tools, ER diagram generation, data export and import capabilities, and an intuitive interface for browsing database objects.

This AMI is ideal for database administrators who need a centralized management workstation, developers who work with multiple database engines, or teams that require a shared database administration environment accessible via remote desktop. Running DBeaver on an AWS instance provides low latency connections to databases hosted on AWS services such as Amazon RDS, Amazon Aurora, and Amazon Redshift.

For any issues encountered while following this guide, please contact support@cloudimg.co.uk.

Prerequisites

Before launching the DBeaver AMI, ensure you have the following in place.

AWS Account You need an active AWS account with permissions to launch EC2 instances, manage security groups, and access the AWS Marketplace.

EC2 Key Pair Create or identify an existing EC2 key pair in the region where you plan to launch the instance. This key pair is required to decrypt the Windows Administrator password after launch.

Security Group Prepare a security group that allows inbound RDP access. The required rule is outlined below.

Protocol Type Port Description
RDP TCP 3389 Remote Desktop Access

It is strongly recommended to restrict the source IP range for RDP access to your known IP addresses or corporate CIDR blocks rather than allowing access from 0.0.0.0/0.

Remote Desktop Client Install a Remote Desktop Protocol client on your local machine. Options include Microsoft Remote Desktop (available for Windows and macOS), Remmina (Linux), or any other RDP compatible client.

Minimum Instance Requirements

Minimum CPU Minimum RAM Required Disk Space
1 vCPU 1 GB 30 GB

A t3.small or larger instance type is recommended for comfortable use. If you plan to work with large datasets or complex queries, a t3.medium or larger will provide a better experience.

Step by Step Setup

Follow the steps below to launch and connect to your DBeaver instance.

Step 1: Launch the Instance

  1. Log in to your AWS account and navigate to the AWS Marketplace.
  2. Search for the cloudimg DBeaver AMI.
  3. Select your desired instance type (t3.small or larger is recommended).
  4. Choose your preferred region and VPC configuration.
  5. Select the EC2 key pair you created in the prerequisites.
  6. Assign the security group with RDP access on port 3389.
  7. Configure storage (30 GB minimum on the root volume).
  8. Launch the instance.

Step 2: Wait for Status Checks

After launching the instance, navigate to the EC2 console and wait for the instance to show 2/2 status checks passing. This ensures the instance has fully booted and Windows has completed its initial setup. This process typically takes between 3 and 10 minutes.

Step 3: Retrieve the Administrator Password

  1. Open the EC2 console in the AWS region where you launched the instance.
  2. Select Instances from the left navigation panel.
  3. Locate and select your newly launched instance.
  4. Click Actions at the top of the page.
  5. Navigate to Security and then select Get Windows password.
  6. Click Browse and upload the private key file (.pem) from the key pair you selected during launch.
  7. Click Decrypt password.
  8. Copy the decrypted password and store it securely. This is your Administrator password.

Step 4: Connect via Remote Desktop

  1. Open your Remote Desktop client application.
  2. Create a new connection using the public IP address of your EC2 instance (or the private IP if connecting through a VPN or from within the same VPC).
  3. Enter the following credentials when prompted:
  4. Username: Administrator
  5. Password: The decrypted value from Step 3
  6. If a certificate warning appears, click Continue to proceed. This is expected for new connections.
  7. You will be connected to the Windows Server desktop.

Step 5: Launch DBeaver

Once connected to the desktop, locate the DBeaver shortcut icon on the desktop and double click it to launch the application. DBeaver is preinstalled and ready for use immediately.

Server Components

The following software components are preinstalled on this AMI.

Component Version
DBeaver Latest

The AMI is built on Windows Server and includes the base operating system along with DBeaver Community Edition preinstalled and configured. DBeaver ships with JDBC drivers for most popular databases and can download additional drivers on demand when you create a new connection.

Filesystem Layout

The instance uses a single volume configuration.

Drive Purpose Minimum Size
C:\ Operating system and application 30 GB

Key directory locations on the instance:

Path Description
C:\Program Files\DBeaver\ DBeaver installation directory
C:\Users\Administrator\Desktop\ Desktop with DBeaver shortcut
C:\Users\Administrator\AppData\Roaming\DBeaverData\ User workspace, connections, and preferences
C:\Users\Administrator.dbeaver\ Driver cache and configuration files

If you plan to export large datasets or work with data intensive operations, consider attaching an additional EBS volume through the AWS console and using it as the output directory.

Managing the Application

Creating a New Database Connection

  1. Launch DBeaver from the desktop shortcut.
  2. Click the New Database Connection button in the toolbar (or navigate to Database then New Database Connection).
  3. Select your database type from the list (MySQL, PostgreSQL, Oracle, SQL Server, and many more are supported).
  4. Enter the connection details including hostname, port, database name, username, and password.
  5. Click Test Connection to verify connectivity. DBeaver will automatically download the required JDBC driver if it is not already present.
  6. Click Finish to save the connection.

Connecting to Amazon RDS

To connect to an Amazon RDS database, use the RDS endpoint as the hostname. The endpoint can be found in the RDS console under the instance details. Ensure that the security group on the RDS instance allows inbound connections from this EC2 instance's security group or private IP address.

Connecting to Amazon Aurora

For Aurora clusters, use the cluster endpoint for read/write operations or the reader endpoint for read only connections. These endpoints are available in the RDS console under your Aurora cluster details.

Connecting to Amazon Redshift

Select Amazon Redshift from the database type list when creating a new connection. Enter the cluster endpoint, port (default 5439), database name, and credentials. Ensure the Redshift cluster's security group allows inbound access from this instance.

Using the SQL Editor

  1. Open a database connection by double clicking it in the Database Navigator panel.
  2. Right click on the connection and select SQL Editor then Open SQL Script.
  3. Type your SQL queries in the editor window.
  4. Press Ctrl+Enter to execute the current query, or Ctrl+Alt+Shift+Enter to execute the entire script.
  5. Results appear in the panel below the editor.

Browsing Database Objects

Expand a database connection in the Database Navigator to browse schemas, tables, views, stored procedures, functions, and other database objects. Double click on any table to view its data, structure, or DDL.

Exporting Data

  1. Right click on a table or query result set.
  2. Select Export Data.
  3. Choose the export format (CSV, JSON, XML, SQL inserts, Excel, and more).
  4. Configure the export options and destination file path.
  5. Click Proceed to export the data.

Generating ER Diagrams

Right click on a schema or a set of tables and select View Diagram to generate an Entity Relationship diagram. DBeaver will automatically create a visual representation of the table relationships, foreign keys, and column types.

Scripts and Logs

DBeaver Log Files

DBeaver generates log files that are useful for diagnosing application issues.

Log Location Description
C:\Users\Administrator\AppData\Roaming\DBeaverData.metadata.log Main DBeaver workspace log
C:\Users\Administrator.dbeaver\drivers\ Downloaded JDBC driver cache

Query History

DBeaver maintains a query execution history. Access it through Window then Query Manager to review previously executed queries, their execution times, and results.

Windows Event Logs

For system level diagnostics, use the Windows Event Viewer. Press the Windows key, search for Event Viewer, and open it to review application and system logs.

Troubleshooting

Cannot connect via RDP

  • Verify that the instance has passed 2/2 status checks in the EC2 console.
  • Confirm that your security group allows inbound TCP traffic on port 3389 from your IP address.
  • Ensure you are using the correct public IP address. If the instance was stopped and started, the public IP may have changed unless you are using an Elastic IP.
  • Check that your local firewall or corporate network is not blocking outbound RDP connections.

Password decryption fails

  • Ensure you are uploading the correct .pem file that matches the key pair selected during instance launch.
  • The password may take up to 15 minutes to become available after the first launch. Wait and try again if the option is greyed out.

DBeaver cannot connect to a database

  • Verify the database hostname, port, username, and password are correct.
  • Ensure the security group on the target database allows inbound connections from this EC2 instance.
  • If connecting to an RDS instance, confirm the database is in an Available state.
  • Check that outbound traffic is allowed from this instance on the database port (3306 for MySQL, 5432 for PostgreSQL, 1521 for Oracle, 1433 for SQL Server, 5439 for Redshift).
  • Use the Test Connection button in DBeaver to diagnose connectivity issues.

JDBC driver download fails

  • Ensure the instance has outbound internet access so DBeaver can download drivers from its repository.
  • If the instance is in a private subnet, configure a NAT gateway or manually download and install the JDBC driver.
  • You can manually add drivers through Database then Driver Manager and specifying a local driver JAR file.

DBeaver runs slowly or freezes

  • Consider upgrading to a larger instance type with more CPU and RAM.
  • Increase the heap memory allocated to DBeaver by editing the dbeaver.ini file in the installation directory. Modify the -Xmx parameter to allocate more memory.
  • Close unused database connections and SQL editor tabs to free up resources.
  • For large result sets, use query limits or pagination to avoid loading millions of rows at once.

Insufficient disk space

  • Monitor C: drive usage through Windows Explorer.
  • Attach an additional EBS volume for data exports and temporary files.
  • Clear the DBeaver log files and driver cache periodically.

RDP session disconnects frequently

  • Check your network connection stability.
  • Adjust the RDP client settings to reduce bandwidth requirements by lowering the display quality or disabling visual effects.
  • Ensure the instance is not running out of memory, which could cause Windows to become unresponsive.

Security Recommendations

Change the Administrator Password

After your first login, change the default Administrator password to a strong, unique password. Open the Windows command prompt or PowerShell and run:

net user Administrator YourNewStrongPassword

Note that once you change the password, the original decrypted password from the AWS console will no longer be valid.

Restrict RDP Access

Limit the security group rule for port 3389 to only your specific IP addresses or a trusted CIDR range. Avoid using 0.0.0.0/0, which would expose the instance to RDP brute force attacks from the entire internet.

Secure Database Credentials

DBeaver stores connection credentials locally. Consider using the built in master password feature (accessible via Window then Preferences then General then Security) to encrypt saved database passwords.

Use IAM Database Authentication

For Amazon RDS and Aurora databases, consider using IAM database authentication instead of static database passwords. This approach generates temporary authentication tokens and eliminates the need to store long term database credentials.

Network Security for Database Connections

Launch this instance in the same VPC as your database servers whenever possible. Use security group rules to restrict database access to only this instance's security group, and keep database connections on private subnets that are not accessible from the internet.

Enable Windows Firewall Rules

Review and configure the Windows Firewall to restrict inbound and outbound traffic to only what is necessary for your database management workflows.

Keep Software Updated

Regularly update DBeaver and Windows Server to ensure you have the latest security patches and bug fixes. DBeaver includes a built in update checker accessible from the Help menu.

Use an Elastic IP

Assign an Elastic IP to your instance to maintain a consistent IP address across stop and start cycles. This also allows you to maintain consistent security group rules on your database instances.

Enable CloudWatch Monitoring

Configure Amazon CloudWatch to monitor your instance metrics such as CPU utilization, memory usage, and disk space. Set up alarms to notify you if resources are running low.

Backup Connection Configurations

Regularly export your DBeaver connection configurations using File then Export so that they can be restored if the instance needs to be recreated.

Support

If you encounter any issues not covered in this guide, the cloudimg support team is available to help.

  • Email: support@cloudimg.co.uk
  • Phone: (+44) 02045382725
  • Website: www.cloudimg.co.uk
  • Address: 3rd Floor, 86 90 Paul Street, London, EC2A 4NE

Support is available for any issues related to the AMI, including connectivity problems, software configuration, and general guidance on using the preconfigured environment.

When contacting support, please include your EC2 instance ID, the AWS region, and a description of the issue along with any relevant error messages or screenshots.