Connect a database via agent

Last updated: July 2026 · 6 min read

Connecting a production database to an analytics tool usually means poking a hole in your firewall. Dotwave avoids that entirely with an agent: a small program you run on your own server that connects outbound to Dotwave and executes only the queries Dotwave sends. Your database stays private and your credentials never leave your infrastructure.

Why an agent?

Your production database should never be exposed to the public internet. The Dotwave agent runs on your server, opens an outbound connection to Dotwave, and receives SQL queries over that connection. It runs each query against your database locally and returns only the results. Your database host, port, and credentials stay entirely on your server — Dotwave never sees them and never needs a direct network path to your database.

Supported databases

The agent currently supports:

MySQL 8.x
PostgreSQL 14+

Step 1 — Create a connection in Dotwave

Add data source → Database

From the Data sources page, click Add data source and choose Database.

Name the connection

Give it a name that identifies the server or database it points to.

Create connection

Click Create connection. Dotwave generates a unique token that ties the agent to this connection.

Copy the token

Copy the token now — it is shown only once. Store it somewhere secure; you will pass it to the agent in the next step.

Step 2 — Install the agent on your server

Download the agent binary for your platform from the Dotwave UI, place it on the server that can reach your database, and run it with your connection details:

./dotwave-agent \
  -token YOUR_TOKEN \
  -db-type mysql \
  -db-host localhost \
  -db-port 3306 \
  -db-name your_database \
  -db-user readonly_user \
  -db-pass your_password

You can also supply every flag as an environment variable instead — for example DOTWAVE_TOKEN, DOTWAVE_DB_TYPE, DOTWAVE_DB_HOST, DOTWAVE_DB_PORT, DOTWAVE_DB_NAME, DOTWAVE_DB_USER, and DOTWAVE_DB_PASS. Environment variables are the safer choice on shared machines because they keep the database password out of your shell history and process list.

Note

For PostgreSQL, set -db-type postgres and use the appropriate port (5432 by default). The agent connects outbound only, so no inbound firewall rules are required.

Step 3 — Run a query and import

Back in Dotwave, once the agent shows "Connected", enter a SQL query for the connection and click Import. Dotwave sends the query to the agent, the agent runs it against your database, and the returned rows become a Dotwave dataset. Write queries that select only the columns and rows you need — filtering and aggregating in SQL keeps result sets small and imports fast.

Security

Use a read-only database user for the agent. The agent only executes the queries Dotwave sends it, but your database user's permissions are the real safety boundary — a read-only user cannot modify or delete data no matter what query is issued. Grant that user access only to the schemas and tables you intend to analyze.

Warning

Create a dedicated read-only database user for Dotwave. Never use your root or admin credentials.

Tip

Run the agent under a process manager such as systemd or Docker so it restarts automatically and reconnects after a reboot. Passing credentials as environment variables pairs naturally with both.

Was this helpful?