Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Feature request: typed query artifacts for SQL files

Open
  • Is something wrong?
#509 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
20/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Quiet
Tech stack
python, sql
Domain
tooling

Research direction

Start by reading SQLFileLoader, ParameterDeclaration, the SQLGlot parsing surfaces, and available data dictionary metadata. Define a focused artifact scope and resolve the listed output, inference, annotation, and placement questions before implementation; done means an agreed, testable design rather than a broad wishlist.

Written by the indexing model from the issue text.

Description

Summary

Follow-up feature request for brainstorming typed artifacts generated from SQL files. This is a wishlist / design exploration item, not committed implementation scope for PR #497.

Background

PR #497 adds -- param: metadata, runtime validation, optional named parameters, and declared type resolution. The next possible step is generating type-checker and IDE-friendly artifacts from the SQL file loader metadata plus query shape.

Wishlist / Brainstorming Topics

  • Generate typed query artifacts from existing SQLSpec surfaces, especially SQLFileLoader, ParameterDeclaration, SQLGlot parsing, and data dictionary metadata where available.
  • Factor in query shape, not just declared params: selected columns, aliases, expressions, select *, joins, casts, functions, and scalar/count-style queries.
  • Generate parameter artifacts such as TypedDict classes, keyword-only accessor signatures, and shared type aliases for JSON/UUID/Decimal/date/time values.
  • Generate result artifacts in one or more forms:
    • msgspec.Struct
    • Pydantic BaseModel
    • TypedDict
    • potentially dataclass/attrs if there is demand
  • Generate typed runtime accessors, not only .pyi stubs. .pyi may still be useful when runtime code stays dynamic, but should not be assumed to be the only output.
  • Centralize import generation so emitted files include only the imports actually needed by generated parameter/result types.
  • Use explicit SQL annotations as an escape hatch for ambiguous or non-portable query shapes, for example expression result types, JSON paths, driver-specific functions, duplicate column names, and unresolved select * projections.
  • Keep runtime validation separate from generated typing. Generated code should improve IDE/type-checker ergonomics without duplicating the runtime validation contract.

Possible Artifact Shape

A generator might emit files similar to:

generated/
  params.py      # param TypedDicts and aliases
  models.py      # result models, e.g. msgspec/Pydantic/TypedDict
  queries.py     # typed runtime accessors / optional typed execution helpers
  queries.pyi    # optional, if needed for dynamic runtime wrappers
  __init__.py

Open Design Questions

  • Which output families should be supported first: TypedDict, msgspec, Pydantic, or configurable combinations?
  • Should typed execution helpers call driver methods directly, or should generation stop at typed (SQL, params) accessors?
  • How should cardinality be declared or inferred: many, one, one-or-none, scalar, execute?
  • What annotation syntax should be used for result hints when SQL/data dictionary inference is insufficient?
  • How much should this rely on live database data dictionary introspection versus offline SQL-only inference?
  • Where should generated files live, and should the generator be CLI-based, Python API-based, or both?

Non-goals to consider

  • Do not build a separate SQL parser when existing SQLFileLoader / SQLGlot / data dictionary surfaces can be reused.
  • Do not duplicate execute-time runtime validation.
  • Do not infer full ORM-like schema models or relationships.
Dominant language
Python
Stars
102
Forks
9
Avg merge
8h 38m
Merged PRs (30d)
64

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from litestar-org/sqlspec

All issues in litestar-org/sqlspec

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.