kandev/docs/plans/postgres-task-terminal-queries/plan.md

created, status, requirements, system_design, legacy_specs

created	status	requirements	system_design	legacy_specs
2026-09-04	done	REQ-TASKS-TASK-TERMINALS-001	../../specs/tasks/system-design/task-terminal-persistence.md

Implementation Plan: PostgreSQL Task Terminal Queries

Overview

Make every parameterized ordinary task-terminal query use placeholder syntax for the selected database driver. One work order adds PostgreSQL lifecycle coverage first, applies the mechanical repository correction, and runs the targeted backend checks.

Scope

In scope

• Add an environment-gated PostgreSQL regression for the ordinary terminal repository lifecycle.
• Rebind every parameterized read and write in the ordinary terminal repository.
• Preserve existing SQLite behavior and error wrapping.

Out of scope

• Changes to terminal service, WebSocket handlers, or web components.
• Changes to terminal sequence allocation or concurrency semantics.
• New database schema or migrations.
• New terminal error presentation.

Technical approach

Add postgres_test.go beside the existing SQLite repository tests. The test constructs the real repository over an isolated PostgreSQL schema and exercises all parameterized lifecycle methods. It must first fail with PostgreSQL syntax error 42601 on the current implementation.

Update apps/backend/internal/terminal/repository/sqlite.go so reads call r.ro.Rebind and writes call r.db.Rebind before passing statements to sqlx. Do not change schema statements because they have no placeholders.

Tests

• AC-TASKS-TASK-TERMINALS-001.1 maps to PostgreSQL create and get assertions plus the existing SQLite sequence tests.
• AC-TASKS-TASK-TERMINALS-001.2 maps to PostgreSQL open/all list assertions and ordered sequence assertions.
• AC-TASKS-TASK-TERMINALS-001.3 maps to PostgreSQL rename, state, single delete, and task-wide delete assertions.

E2E tests

The existing browser terminal suites cover the unchanged user, WebSocket, and service flow. The new real-PostgreSQL lifecycle test covers the driver boundary that caused the end-to-end failure. No frontend or protocol behavior changes.

Work orders

• Task 01: Rebind Task Terminal Queries

Verification results

• The PostgreSQL lifecycle regression passed three subtests on PostgreSQL 16.
• The terminal package suite passed 29 tests in three packages.
• The changed-file backend linter reported zero issues.

Risks

• Omitting one parameterized method can leave a later lifecycle action broken on PostgreSQL even if creation starts working.
• PostgreSQL integration coverage skips when KANDEV_TEST_POSTGRES_DSN is not configured, so the implementation run must provide an isolated database.