Skip to main content

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.

Sign up

Step 2: Create a database instance to be tuned​

To create a database instance to be tuned, click on the Add database button in the top right corner of the screen.

The process is straightforward and below you can see a short video of the process.

Create database instance

Step 3: Download and run the DBtune open-source agent​

Prepare a shell on your server machine:

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

  1. Login as root user or use the command sudo su. We will use a sudo user account to run the agent process, to allow restarting of the database. In production you may want to run the agent as a non-sudo user if you have another user that has the required privileges to restart the database.

  2. Download the DBtune agent following the instructions on the web app, under the Agent tab. For most cases, you will only need to use one command to download the agent.

Download DBtune agent
  1. Then in the same directory that the agent is downloaded create and edit the dbtune.yml file. In the web-application you will find the connection details for your database instance with pre-filled fields.

You can run vim dbtune.yml to edit the file. When you are done editing the file, save and exit by pressing ESC, then type :wq and press Enter.

DBtune agent config file

The fields of interest are the following:

# Example config file
postgresql:
  connection_url: postgresql://...
  # If you are running PostgreSQL server with systemctl
  # and want to enabled restarts, uncomment the following line
  # and replace postgresql-17 with the name of your service
  # service_name: postgresql-17

dbtune:
  server_url: https://app.dbtune.com
  api_key: api-key-from-web-app # Will be pre-filled
  database_id: database-id-from-web-app # Will be pre-filled
  1. Start the agent by running ./dbtune-agent. The agent will start running and you will see some output in the terminal. Then you can go back to the web-application and see the agent connected to your database instance and start sending data.
Agent running

Step 4: Track your optimization progress​

As soon as the agent is running, you can go back to the web-application and see your database instance data. When you are ready to start the optimization process, click on the Tuning tab and then click on the Start tuning button.

After session is finished, you will see the following screen — We annotated the image with comments in blue to explain the insightful parts.

Tuning finished breakdown

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 between 2.5 and 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 (average query runtime or transactions per second).

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

Last updated on