Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

perf: add partial index on task_run for active statuses (#17866)

Danny Xu2ad8d33bb2e7
diff --git a/backend/migrator/migration/3.11/0018##task_run_status_index.sql b/backend/migrator/migration/3.11/0018##task_run_status_index.sql
new file mode 100644
index 0000000000..c80857cb4f
--- /dev/null
+++ b/backend/migrator/migration/3.11/0018##task_run_status_index.sql
@@ -0,0 +1,29 @@
+-- Add partial index on task_run for active statuses
+--
+-- This migration adds a partial index to optimize queries filtering for active task runs.
+--
+-- Background:
+-- Task runs go through state transitions: PENDING -> RUNNING -> (DONE|FAILED|CANCELED)
+-- Once in a terminal state (DONE, FAILED, CANCELED), status never changes again.
+-- Most task runs are in terminal states, but queries frequently filter for active ones (PENDING, RUNNING).
+--
+-- Problem:
+-- Queries like "SELECT ... FROM task_run WHERE status IN ('RUNNING')" were doing sequential scans
+-- because there was no index on the status column.
+--
+-- Solution:
+-- Use a partial index that only covers active statuses (PENDING, RUNNING).
+-- This is more efficient than a full index because:
+-- - Smaller index size (only active tasks, not all historical completed tasks)
+-- - Faster index maintenance (terminal states don't consume index space)
+-- - Better cache efficiency (smaller index fits in memory)
+-- - Matches the query pattern (filters for active statuses)
+--
+-- Example query optimized:
+-- SELECT task_run.id, ... FROM task_run
+-- LEFT JOIN task ON task.id = task_run.task_id
+-- WHERE task_run.status IN ('RUNNING')
+-- ORDER BY task_run.id ASC
+
+CREATE INDEX CONCURRENTLY idx_task_run_active_status_id ON task_run(status, id)
+WHERE status IN ('PENDING', 'RUNNING');
diff --git a/backend/migrator/migration/LATEST.sql b/backend/migrator/migration/LATEST.sql
index ae1a2325d6..aa7d731765 100644
--- a/backend/migrator/migration/LATEST.sql
+++ b/backend/migrator/migration/LATEST.sql
@@ -238,6 +238,11 @@ CREATE INDEX idx_task_run_task_id ON task_run(task_id);
CREATE UNIQUE INDEX uk_task_run_task_id_attempt ON task_run (task_id, attempt);
+-- Partial index for active task runs. Most task runs are in terminal states (DONE, FAILED, CANCELED)
+-- that never change. Queries frequently filter for active statuses (PENDING, RUNNING), so a partial
+-- index is more efficient than a full index on status - smaller size, faster maintenance, better cache efficiency.
+CREATE INDEX idx_task_run_active_status_id ON task_run(status, id) WHERE status IN ('PENDING', 'RUNNING');
+
ALTER SEQUENCE task_run_id_seq RESTART WITH 101;
CREATE TABLE task_run_log (
diff --git a/backend/migrator/migrator_test.go b/backend/migrator/migrator_test.go
index 4accd68d42..73c3ceecad 100644
--- a/backend/migrator/migrator_test.go
+++ b/backend/migrator/migrator_test.go
@@ -12,7 +12,7 @@ import (
func TestLatestVersion(t *testing.T) {
files, err := getSortedVersionedFiles()
require.NoError(t, err)
- require.Equal(t, semver.MustParse("3.11.17"), *files[len(files)-1].version)
+ require.Equal(t, semver.MustParse("3.11.18"), *files[len(files)-1].version)
}
func TestVersionUnique(t *testing.T) {