DEV Community

Cover image for Grafana for Beginners: Build Your First Dashboard Using PostgreSQL and Docker
Sanjay Ghosh
Sanjay Ghosh

Posted on

Grafana for Beginners: Build Your First Dashboard Using PostgreSQL and Docker

As I continue exploring the DevOps ecosystem, I wanted to understand how monitoring and observability tools fit into the software delivery lifecycle.

Tools like Git, Jenkins, Docker, and Kubernetes are frequently discussed, but eventually every team reaches a common question:

How do we monitor what is happening after deployment?

That's where Grafana comes in.

Grafana is one of the most popular open-source visualization platforms used by development, operations, and Site Reliability Engineering (SRE) teams. It helps transform raw metrics into meaningful dashboards that provide insights into application performance, infrastructure health, and business metrics.

In this article, we'll build a complete working example from scratch:

  • Install Grafana using Docker
  • Create a PostgreSQL database
  • Insert sample metrics
  • Connect Grafana to PostgreSQL
  • Build a dashboard
  • Troubleshoot common connection issues

By the end, you'll have a fully functional Grafana dashboard running locally and a solid understanding of how Grafana fits into modern DevOps workflows.

What is Grafana?

Grafana is an open-source monitoring and visualization platform.

It connects to various data sources and transforms raw data into interactive dashboards and alerts.

Grafana itself does not store monitoring data. Instead, it reads data from external systems such as:

  • PostgreSQL
  • MySQL
  • Prometheus
  • Elasticsearch
  • Loki
  • AWS CloudWatch
  • InfluxDB

A simplified architecture looks like this:

Database / Monitoring Tool
            |
            v
         Grafana
            |
            v
       Dashboards
            |
            v
          Alerts
Enter fullscreen mode Exit fullscreen mode

Where Grafana Fits in DevOps

Grafana is used throughout the DevOps lifecycle.

Development

  • Performance analysis
  • Debugging bottlenecks
  • Resource utilization monitoring

Testing

  • Monitor test environments
  • Validate application behavior

CI/CD

  • Monitor deployments
  • Track build success rates
  • Visualize pipeline metrics

Production

  • Infrastructure monitoring
  • Application Performance Monitoring (APM)
  • Alerting and incident management

Step 1: Install Grafana Using Docker

Pull the Grafana image:

docker pull grafana/grafana
Enter fullscreen mode Exit fullscreen mode

Verify:

docker images
Enter fullscreen mode Exit fullscreen mode

Run Grafana:

docker run -d \
  --name grafana \
  -p 3000:3000 \
  grafana/grafana
Enter fullscreen mode Exit fullscreen mode

Verify the container:

docker ps
Enter fullscreen mode Exit fullscreen mode

Example:

0.0.0.0:3000->3000/tcp
Enter fullscreen mode Exit fullscreen mode

Open:

http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

Default credentials:

Username: admin
Password: admin
Enter fullscreen mode Exit fullscreen mode

Grafana will prompt you to change the password during the first login.

Screenshot of login:

Step 2: Create a PostgreSQL Database

Create a database:

CREATE DATABASE grafana_demo;
Enter fullscreen mode Exit fullscreen mode

Connect:

\c grafana_demo
Enter fullscreen mode Exit fullscreen mode

Create a table:

CREATE TABLE system_metrics
(
    id SERIAL PRIMARY KEY,
    metric_time TIMESTAMP,
    cpu_usage NUMERIC(5,2)
);
Enter fullscreen mode Exit fullscreen mode

Verify:

\d system_metrics
Enter fullscreen mode Exit fullscreen mode

Step 3: Insert Sample Metrics

Insert some sample CPU usage data:

INSERT INTO system_metrics(metric_time, cpu_usage)
VALUES
(NOW() - INTERVAL '9 minutes',15),
(NOW() - INTERVAL '8 minutes',18),
(NOW() - INTERVAL '7 minutes',25),
(NOW() - INTERVAL '6 minutes',30),
(NOW() - INTERVAL '5 minutes',45),
(NOW() - INTERVAL '4 minutes',50),
(NOW() - INTERVAL '3 minutes',42),
(NOW() - INTERVAL '2 minutes',55),
(NOW() - INTERVAL '1 minute',60),
(NOW(),48);
Enter fullscreen mode Exit fullscreen mode

Verify:

SELECT *
FROM system_metrics;
Enter fullscreen mode Exit fullscreen mode

Step 4: Connect Grafana to PostgreSQL

Navigate to:

http://localhost:3000/datasources
Enter fullscreen mode Exit fullscreen mode

Choose:

PostgreSQL
Enter fullscreen mode Exit fullscreen mode

Use:

Host:
host.docker.internal:5432

Database:
grafana_demo

User:
postgres

Password:
your_password
Enter fullscreen mode Exit fullscreen mode

Save and test the connection.

Screenshot of connection:

Step 5: Create Your First Dashboard

Navigate to:

Dashboards
→ New Dashboard
→ Add Visualization
Enter fullscreen mode Exit fullscreen mode

Select your PostgreSQL data source.

Switch to Code Mode and execute:

SELECT
    metric_time AS "time",
    cpu_usage AS value
FROM system_metrics
ORDER BY metric_time;
Enter fullscreen mode Exit fullscreen mode

Click:

Run Query
Enter fullscreen mode Exit fullscreen mode

Grafana automatically plots the data.

Screenshot of graph:

Common Connection Problem

One of the most common errors is:

Network error:
Failed to connect to the server
Enter fullscreen mode Exit fullscreen mode

Example:

dial tcp:
lookup host.docker.internal:
no such host
Enter fullscreen mode Exit fullscreen mode

Verify PostgreSQL Settings

Check:

SHOW listen_addresses;

SHOW port;
Enter fullscreen mode Exit fullscreen mode

You may see:

listen_addresses = localhost
Enter fullscreen mode Exit fullscreen mode

This means PostgreSQL only accepts local connections.

Grafana running inside Docker cannot reach it.

Fix PostgreSQL Connectivity

Locate the configuration file:

sudo -u postgres psql -c "SHOW config_file;"
Enter fullscreen mode Exit fullscreen mode

Example:

/etc/postgresql/16/main/postgresql.conf
Enter fullscreen mode Exit fullscreen mode

Modify:

listen_addresses='*'
Enter fullscreen mode Exit fullscreen mode

Update:

/etc/postgresql/16/main/pg_hba.conf
Enter fullscreen mode Exit fullscreen mode

Add:

host all all 0.0.0.0/0 scram-sha-256
Enter fullscreen mode Exit fullscreen mode

Restart PostgreSQL:

sudo systemctl restart postgresql
Enter fullscreen mode Exit fullscreen mode

Or:

sudo service postgresql restart
Enter fullscreen mode Exit fullscreen mode

Verify:

SHOW listen_addresses;
Enter fullscreen mode Exit fullscreen mode

Expected:

*
Enter fullscreen mode Exit fullscreen mode

Find the Host IP Address

If host.docker.internal does not work:

hostname -I
Enter fullscreen mode Exit fullscreen mode

Example:

172.21.xxx.xxx
Enter fullscreen mode Exit fullscreen mode

Use that IP address as the Grafana host connection.

Grafana vs Prometheus

A common beginner question is:

Do I need Prometheus?

The answer depends on your use case.

Prometheus
-----------
Collects Metrics

Grafana
--------
Visualizes Metrics
Enter fullscreen mode Exit fullscreen mode

Prometheus and Grafana are frequently used together.

Grafana + Jenkins

Grafana can also monitor Jenkins pipelines when combined with Prometheus exporters.

Learning Path 

Install Grafana
       |
       v
Connect Data Source
       |
       v
Run Queries
       |
       v
Create Dashboard
       |
       v
Create Alerts
       |
       v
Production Monitoring
Enter fullscreen mode Exit fullscreen mode

Final Thoughts

Grafana is one of the most valuable tools in the modern DevOps ecosystem because it turns raw operational data into actionable insights.

Even with a simple PostgreSQL database and a handful of records, we can create meaningful visualizations and begin understanding trends, performance characteristics, and system behavior.

In real-world environments, Grafana is often integrated with:

  • Prometheus for metrics collection
  • Jenkins for CI/CD monitoring
  • Docker and Kubernetes for container monitoring
  • Loki for centralized logging
  • Cloud platforms such as AWS, Azure, and Google Cloud

This article focused on the fundamentals using PostgreSQL because it provides an easy way to understand how Grafana connects to a data source and transforms query results into visual dashboards.

Once you're comfortable with this setup, the next logical steps are:

  • Grafana + Prometheus
  • Grafana + Jenkins
  • Grafana + Docker Metrics
  • Grafana + Kubernetes
  • Grafana + Loki

Those integrations unlock the full power of observability and provide the continuous feedback loop that modern DevOps teams depend on.

I hope this walkthrough helps you build your first Grafana dashboard and serves as a foundation for deeper monitoring and observability projects.

Top comments (0)