Skip to content
OPQAI.
Sourced intermediate / 💻 Coding

Query PostgreSQL Databases with Natural Language using Pgmcp

Job to be done: Query a PostgreSQL database using natural language

🇳🇬 Ways to use this in Nigeria

Ideas to get you started, adapt to your situation.

  • Student

    Get a list of all available courses and their descriptions from your university's PostgreSQL database by asking in plain English.

  • 9-5 employee

    Ask your company's PostgreSQL database for the total sales figures for Q3 last year without writing any SQL code.

  • Small business

    Find out how many customers ordered product X last month from your sales database using a simple question instead of SQL.

What you’ll get

The ability to ask your database questions in plain English (“how many customers ordered product X last month?”) and get answers, with no SQL required. Pgmcp is a small server that sits between an AI and your PostgreSQL database (a popular free database): it turns your question into the right SQL query, runs it, and returns the result. It is intermediate: you set a couple of environment variables and run a server in your terminal.

Tools you need

  • Pgmcp (free): the server that translates your plain-English question into SQL and runs it.
  • PostgreSQL (free): the database you are querying. You need an existing one.
  • An AI model: either the OpenAI API (paid) or a local model via Ollama (free) does the English-to-SQL translation. (“API key” = the secret that lets the tool use the AI.)

Steps

  1. Get Pgmcp: download the pre-built Pgmcp server (and client) for your system from the project’s GitHub Releases page.

  2. Set your connection details: tell Pgmcp how to reach your database (and your AI key if using OpenAI) with environment variables (settings for this terminal session):

    # macOS or Linux
export DATABASE_URL="postgres://user:password@localhost:5432/your-db"
export OPENAI_API_KEY="your-api-key"
    # Windows (PowerShell)
$env:DATABASE_URL = "postgres://user:password@localhost:5432/your-db"
$env:OPENAI_API_KEY = "your-api-key"

  3. Start the server: run the Pgmcp server from the folder you downloaded it to:

    # macOS or Linux
./pgmcp-server

    On Windows, run .\pgmcp-server.exe. You should see it report that it is listening and connected to your database.

  4. Ask a question: in a new terminal, use the client to ask in plain English:

    ./pgmcp-client -ask "What tables do I have?" -format table

    You should get a neatly formatted table of your database’s tables.

  5. Try a real query: for example, search for a customer:

    ./pgmcp-client -search "john" -format table

    You should get matching rows back.

  6. Go free with a local model (optional): to avoid OpenAI costs, point Pgmcp at a local model run by Ollama instead (set the relevant environment variable per the README). The whole workflow then costs nothing.

Original source

Based on a Show HN post by fosk introducing Pgmcp (by subnetmarco), an MCP server that lets AI assistants query any PostgreSQL database in natural language.

Notes & variations

  • Free-tier alternative: swap the paid OpenAI API for a local model via Ollama to make the whole thing free.
  • Common pitfall: a malformed DATABASE_URL. Double-check the username, password, host, port, and database name; a wrong one stops Pgmcp connecting.
  • Tip for better results: clear, descriptive table and column names help a lot. Pgmcp reads your database’s structure to interpret questions, so a tidy schema gives more accurate SQL.

Keep going

More Coding workflows