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
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.

Step 3: Download and run the DBtune open-source agent
Prepare a shell on your server machine:
- Since DBtune will be running for a few hours for your testing purposes, it is recommended to use a terminal multiplexer such as
screen
ortmux
so as not to accidentally disconnect the agent if the SSH session is closed or the terminal session is lost. Type the commandscreen
on the terminal of your agent machine, you will get the following output:

-
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. -
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.

- 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.

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
- 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.

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.

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