How to get started

Step 1: Create an account

Visit app.dbtune.com and create an account. After creating an account, you will receive an email to confirm your email address.

Step 2: Create a database instance to be tuned

After logging in for the first time, you'll land on a screen specifically designed to help you add your database instance for tuning.

The tooltips can help you through the process:

Select the database management system and the database hosting:

First, choose the type of database management system you're using (currently only PostgreSQL is supported). Next, indicate how your database is hosted/managed.

There are two main options:

• Self-hosted: This means you manage the database yourself, either on your own hardware or on a cloud instance like EC2.
• Managed Database Service: This is a cloud-based option where the database provider handles the infrastructure (e.g., Amazon RDS, Azure SQL Database).

Choose if the database can be restarted:

There are a number of parameters that can not be changed unless there is a restart of the database itself. The tuning session benefits from allowing the DB instance to restart as a greater number of parameters can be included. These cannot be changed and tuned if the option of no restart is selected. In the case restart is enabled, the database instance will be unavailable for a short period of time when each new configuration is deployed at each restart about every 5 minutes during the tuning session. The instance will be unavailable for a few seconds up to a few minutes depending on the user application.

Step 3: Download and run the DBtune Python agent

Prepare a shell on your server machine:

1. Since DBtune will be running for a few hours, it is recommended to use a terminal multiplexer such as screen so as not to accidentally disconnect the tuning session if the CLI is closed. Type the command screen on the terminal of your agent machine, you will get the following output:

2. Login as root user or use the command sudo su

3. Download the DBtune agent using the wget, curl or download command on the web interface. The command will download the DBtune agent as a tar file and uncompress it. The agent you download is specific to your user account and to the database instance you are about to connect it to, and it reflects the choices on tuning target and the restart option. To change any of these you need to download a new agent.

4. Go into the dbtune_client directory and edit the dbtune_config.yml file with the database instance connection details.

The commented out fields are not mandatory. This is a description of the fields:

connection_string:
  # The host name
  host: string
  # The port postgres is running on
  port: number
  # The name of the database DBtune will optimise
  dbname: string
  # The database username assigned to DBtune agent
  user: string
  # The password for the database user
  password: string
  # If you have installed postgres from source and the command
  # `sudo systemctl restart postgresql` does not restart postgres,
  # provide a command that does in this field.
  # A working restart command is necessary if you allow the agent to restart postgres,
  # or if the postgres extension pg_stat_statements is not currently enabled and you want to tune for query runtime.
  # Enabling pg_stat_statements requires one restart, which the agent will ask if you want to allow,
  # and if you do then it will do it for you even if you choose not to allow restarts in the previous step from the DBtune web interface.
  restart_command: string

5. Start the agent by running python3 dbtune.py.

6. Enter a database instance name and press the Start tuning button on the web interface

7. Once the tuning has started you can detach the screen:

• Press Ctrl + a and then d to detach: the tuning will keep on running in the background;
• You can reattach the screen using the following command: screen -r;
• For more details on how to use screen see this link.

Step 4: Track your optimization progress

After starting the tuning session the user will be redirected to the dashboard

You can monitor the throughput, the average query runtime, disk I/O, RAM usage, CPU, and IOPS usage in real time as the tuning progresses.

The currently active configuration is shown in the configurations panel. Under Tuning summary you can see all the configurations that were explored by DBtune. Click on a point in the chart to visualize the configuration in the bottom panel.

Step 5: Sit back, DBtune can take it from here

The automated tuning session is underway. No further user interaction is necessary.

DBtune is learning how to optimize your database with respect to your specific workload and instance resources. The tuning session will last about 3.5 hours. After that DBtune will automatically install on the instance being tuned the PostgreSQL configuration that delivers the optimal results for your chosen target objective (throughput or query runtime).

If you require the optimization to run faster, please contact the DBtune team at info@dbtune.com. In this user guide we have been conservative in defining the tuning session for the user. We can adapt to your needs and make the tuning faster