Table of Contents

How SqlSource works

This page says how the source generator, the tool and the sidecar file worked together on the last page, to describe a query and build.

The picture

flowchart LR
    sql[".sql file"] --> generator
    subgraph build["Your build"]
        generator["Generator"]
    end
    generator --> code["Constants, methods and models"]
    sql --> tool["Tool + your database"]
    tool --> sidecar["Sidecar"]
    sidecar -->|checked and read| generator

SqlSource has two parts, one in each package:

  • The generator is in the SqlSource package. It is a source generator: it runs inside the compiler at each build. It turns each query of your .sql files into C# code.
  • The tool is the sqlsource command of the SqlSource.Tool package. It asks your database about each query, and writes the answer to a sidecar file beside the .sql file.

The build reads the sidecar, so it needs no database. By default, every query must be described. The build reports an error for a query that has no current entry in its sidecar.

The words

  • Query: the SQL that follows a -- name: line, up to the next -- name: line or the end of the file. See queries and names.
  • Marker: a line comment of the form -- word: value that SqlSource reads, such as -- name: GetUser. See markers.
  • Describe: to ask your database, without running the query, what its parameters and columns are. See what describe does.
  • Sidecar: the file beside a .sql file, such as UserRepository.sql.json, where the tool writes what your database said. See sidecar files.
  • Repository: a class marked [SqlSourceGenerate] that gets one method for each query of its .sql file. See repository methods.
  • Model: a record that the build generates for a query, such as GetUserParams for its parameters and GetUserDto for its rows. See models.

What needs a database and what does not

  • Describing needs your database. The tool connects to it to describe a query that is new or changed.
  • Describing checks each query against your schema. A table or a column that does not exist is an error when you describe, not when the query runs.
  • A build needs no database. It reads the sidecars that you committed, so it builds on a colleague's machine or in CI with no connection.
  • The tool reads your schema, not your data. A database with your tables and no rows is enough.

If it does not work

  • If a colleague's build reports SQLSRC241 for every query, the sidecars are not in git. Commit them, as Your first query says.

What you have now

The six words that the next pages use, and the reason the sidecars go into git.

Rules: the generator, the tool, sidecar files, running in the build, what describing does on PostgreSQL and SQL Server.

Next: Write queries