lqo.net

First LQO Release Finds the PostgreSQL Queries a Planner Setting Makes Faster

Mon, 19 Oct 2026 00:00:00 +0000

Every PostgreSQL database has a few queries the planner gets badly wrong. Not slow because they’re big. Slow because the planner guessed the wrong row count, picked a plan for ten rows, and got ten thousand. Finding them is usually an afternoon with EXPLAIN ANALYZE, one query at a time.

LQO 0.1 does that afternoon for a whole workload. Give it a server log or a file of queries, point it at a replica, and it runs each kind of query under PostgreSQL’s default plan and under a set of planner settings. Then it tells you which settings make which queries clearly faster, with the exact lines to use.

LQO Finds Faster PostgreSQL Plans for 35 of 94 Join Order Benchmark Query Shapes

Mon, 19 Oct 2026 00:00:00 +0000

The Join Order Benchmark is where query optimizers go to be embarrassed. It’s 113 queries over the IMDB movie database, real data with all its skew and correlated columns, and it was built to show how far a planner’s row estimates can drift from the truth. If a tool claims to find better plans, this is the first place anyone should look.

So LQO 0.1.0 ran it, start to finish, on a GitHub runner: 4 cores, 15 GB of memory, PostgreSQL 16 with 5 GB of shared buffers. The 113 queries fold into 94 query shapes, because some JOB variants differ only in their constants. Each shape ran under the default plan and under LQO’s 13 standard hints, with a warm-up run and three timed runs per plan. The whole thing took 75 minutes.

How LQO Was Tested, From Writes It Must Never Run to Traps It Must Find

Sun, 18 Oct 2026 00:00:00 +0000

A tool that runs your queries on a database has two jobs, and the first one matters more. It must never do harm: no writes, no settings left behind, no runaway query. Then it must actually find something. LQO’s tests go after both, against a real PostgreSQL server rather than a mock.

All 62 tests pass in the recorded run, on a two-core cloud machine with PostgreSQL 16. CI runs them again on every change against PostgreSQL 14 and 18, and runs the parts that need no server on macOS and Windows. The logs are on GitHub.

What Is a Learned Query Optimizer? Why PostgreSQL Picks Slow Plans and How to Steer It

Sun, 18 Oct 2026 00:00:00 +0000

A query optimizer turns your SQL into a plan: which table to read first, which index to use, how to join one table to the next. A learned query optimizer is one that improves its choices from what actually happened when queries ran, instead of trusting its own predictions. The idea is older than it sounds, and it’s finally practical.

To see why it matters, look at how an ordinary optimizer goes wrong.

Why LQO Stands for Learned Query Optimizer, and What It Learns

Sun, 18 Oct 2026 00:00:00 +0000

LQO is short for learned query optimizer, the name database researchers use for an optimizer that improves from what queries actually did rather than from its own predictions. Say it as three letters, L-Q-O. The name is plain on purpose. It says what the thing is to the people most likely to look for it.

Each word does some work, though, and one of them needs an honest footnote.

Query Optimizer

Every SQL database has an optimizer. It’s the part that decides how to run your query: which table first, which index, which way to join. You don’t see it, but it’s the reason the same SQL can take 4 ms or 4 seconds. PostgreSQL’s optimizer is the planner, and LQO works with it rather than around it.

About

Mon, 01 Jan 0001 00:00:00 +0000

lqo.net is the home of LQO, a learned query optimizer for PostgreSQL. It finds the queries PostgreSQL’s planner gets wrong, and the planner setting that makes each one clearly faster, by trying them on a replica. It’s one small binary called lqo, with nothing to install on the database.

Why It Exists

PostgreSQL picks every plan from row counts it estimates. Most of the time the estimates are close enough. Sometimes they’re off by a factor of a thousand, usually because two columns are related in a way the statistics can’t see, and a plan built for ten rows runs for ten thousand. A query that should take 40 ms takes four seconds, and nobody notices until a page times out.

Contact

Mon, 01 Jan 0001 00:00:00 +0000

lqo.net would like to hear from:

Anyone trying LQO out. What it found, what it missed, and what got in the way.
Anyone who found a bug. A report that looks wrong, a log LQO couldn’t read, a connection it couldn’t make.
Anyone with an idea for something LQO should do, or a kind of slow query it should catch.

Write to info@lqo.net.

Bug reports are also welcome on GitHub. It helps to include what lqo version prints, your PostgreSQL version, and the JSON report (--report json) if there is one. Please don’t send real customer data or connection strings with passwords: the query shapes and the timings are usually enough.

Download LQO

Mon, 01 Jan 0001 00:00:00 +0000

The lqo command is one file with nothing else to install, on your machine or on the database. Each archive below holds it with its license files and the manual. The links always point to the latest release.

System	Download
Linux, x86-64	lqo_linux_amd64.tar.gz
Linux, ARM64	lqo_linux_arm64.tar.gz
macOS, Apple silicon	lqo_darwin_arm64.tar.gz
macOS, Intel	lqo_darwin_amd64.tar.gz
Windows, x86-64	lqo_windows_amd64.zip

Checksums are in SHA256SUMS. Every release is listed on GitHub.

Install

On Linux or macOS:

tar -xzf lqo_linux_amd64.tar.gz
sudo mv lqo /usr/local/bin/
lqo version

The binaries are static Go builds, so the Linux ones run on any distribution. The macOS binaries aren’t signed by Apple, so macOS may block the first run; allow it in System Settings under Privacy & Security, or run xattr -d com.apple.quarantine lqo. On Windows, unzip the archive and put lqo.exe in a folder on your PATH.

LQO Reference

Mon, 01 Jan 0001 00:00:00 +0000

The commands, the flags, and the rule LQO uses to decide. The complete reference, with the log formats, the JSON report and the state file, is docs/REFERENCE.md on GitHub.

Commands

lqo advise [flags] WORKLOAD...   try a workload's queries with each hint and report
lqo show [flags]                 print what the state file holds
lqo report [flags] REPORT.json   print a saved JSON report as text or Markdown
lqo hints [--hints full]         list the hints lqo tries
lqo demo [flags]                 build the lqo_demo schema and its workload file
lqo version                      print the version

Flags for lqo advise

Flag	Default	What it does
`--dsn`	`LQO_DSN`, then `PG*`	connection string, as for `psql`
`--allow-primary`	off	run on a primary, not only a standby
`--format`	`auto`	workload format: `auto`, `sql`, `stderr`, `csv`, `json`
`--hints`	`standard`	`standard` (13 hints) or `full` (48)
`--top`	25	how many kinds of query to test
`--samples`	3	distinct texts tested per kind
`--repeat`	3	timed runs per plan, after one warm-up
`--min-gain`	20	percent of the time a hint must save
`--timeout-factor`	3	stop a hinted run at this multiple of the default plan’s time
`--max-time`	`60s`	stop the default plan’s runs after this long
`--set name=value`		session setting for every trial, may repeat
`--all-databases`	off	keep logged statements from every database
`--report`	`text`	`text`, `json` or `markdown`
`--out`	stdout	write the report to a file
`--state`	`lqo-state.json`	where findings are kept
`--no-state`	off	don’t write the state file
`--quiet`	off	no progress lines

Exit codes: 0 when the run finished, 1 on an error, 2 for a usage error or a refusal, such as a primary without --allow-primary.

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

LQO finds the PostgreSQL queries a planner setting makes clearly faster. This page takes you from nothing to a first report in a few minutes, on a demo database, then on your own.

1. Get the lqo Command

Download the archive for your system from the download page, unpack it and check it runs:

tar -xzf lqo_linux_amd64.tar.gz
./lqo version

2. Try It on the Demo

You need a PostgreSQL server you can create a schema on. A throwaway container is ideal: