implement-query-service

Implements CQRS read-side queries in Go using PostgreSQL, pgx/v5, and sqlc.

Updated Sep 14, 2026
One-click install
npx skills add https://github.com/nakamori-naoya/go-convention-plugins --skill implement-query-service-nakamori-naoya
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: implement-query-service
Source: https://github.com/nakamori-naoya/go-convention-plugins/tree/main/plugins/go-convention/skills/implement-query-service
Command: npx skills add https://github.com/nakamori-naoya/go-convention-plugins --skill implement-query-service-nakamori-naoya

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Implementing the read side of CQRS in Go often drifts into restoring aggregates, opening transactions, or redefining contracts, which breaks layering and duplicates business rules. This Skill enforces a convention where read queries are built purely from SQL relational projection and aggregation, plus confirmed value objects or pure functions for calculations SQL cannot express. ## Core Features & Use Cases - Contract-driven read implementation: Uses the usecase-owned read port, read models, Page, and sentinels without redefining them, keeping dependencies pointing from implementation to contract. - SQL-first relational logic: Places JOINs, filtering, ordering, paging, and counts in sqlc-generated SQL, while SQL-unfriendly business calculations reuse existing value objects or pure functions. - Strict prohibitions: Never restores or mutates aggregates or entities, never writes, never starts transactions, and translates :one zero-row results into the contract's ErrNotFound sentinel. - Use Case: Given a reservation history read contract and a finalized data model, implement a paged query that joins parent reservations with history events and maps rows to querycontract.ReservationHistory. ## Quick Start Implement the availability list query for this read contract using the finalized data model, keeping all aggregation in SQL and mapping rows to the usecase-owned read model.

Frequently Asked Questions about implement-query-service

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I implement a CQRS read query in Go with sqlc?▼

Write SELECT-only SQL with explicit columns, generate it with sqlc, then build a Query type holding a pgxpool.Pool that validates arguments, picks tx or pool from context, calls the generated method once, and maps rows to the usecase-owned read model.

How should read models be mapped from database rows in Go?▼

Use pure functions named {Row}To{ReadModel} that take only the DB row and resolved values. Map NULL to a value plus Has{X} pair, convert times with .UTC(), return nil slices for zero results, and fold parent-child joins by parent identifier.

Can a query implementation reuse domain value objects?▼

Yes, for confirmed business calculations that SQL expresses poorly, such as money rounding or business hours, the implementation may import existing value objects or pure functions. Counts, sums, JOINs, and filters must stay in SQL, and aggregates must never be restored.

Does this approach support transactions in read queries?▼

Read implementations never begin, commit, or roll back transactions. If a transaction already exists on the context, the query rides on it; otherwise it reads through the connection pool, which keeps command-side consistency without coupling.

When should query implementation stop instead of proceeding?▼

Stop when the read port, read models, Page, or sentinels are not finalized on the usecase side, when a required field cannot be derived from columns, SQL, or confirmed domain calculations, or when aggregate restoration, writes, or caller-supplied SQL conditions are demanded.