How errors are reported
This page tells you how SqlSource reports a problem: how severe it is, where you see it, what it costs and what reports it. Each error, with its cause and its fix, is on the page Diagnostics.
Errors, warnings and information
Every problem that SqlSource finds is an error. You cannot turn an error off or make it a warning. Eight ids are the exceptions.
These six are warnings:
- SQLSRC026: the build cannot start the
sqlsourcetool, and goes on with the sidecars it has. - SQLSRC031: a connection is marked for a logical database that no repository query uses.
- SQLSRC121: a parameter of a SQL Server query is written in two spellings.
- SQLSRC240: another version of the tool wrote a sidecar, or an entry of one.
- SQLSRC245: an entry of a sidecar names no query that needs it.
- SQLSRC284: a short name of a C# type that you chose finds a type of a package that the project does not reference itself.
These two are information, about the version of a database driver:
The section of each of the eight says how a project can configure it.
Information is not in the output of dotnet build. An IDE that lists information shows it, and the build log has it at the detailed verbosity, as SQLSRC248 says.
Where an error is reported
The build reports its errors and warnings in its output, and your IDE lists them with the compiler's. Each one names the file, the line and the column of the problem, where it has them:
- A
.sqlfile. An error in a.sqlfile is at its line and column in that file. An error about a query is at the query's name, or at the marker that the error is about. - A sidecar. An error in a sidecar is at its line and column in the sidecar.
- A settings file. An error in a settings file,
sqlsource.json, is at its line and column in that file. - A C# file. An error about a type that carries
[SqlSourceGenerate]is at the type's name, at its attribute, or at the member that the error names. - The project file. The errors of a build that runs the tool, SQLSRC024 to SQLSRC027, are at the project file.
Some errors are about the project's references, and have no file and line. In the build's output, such an error starts with CSC in place of a path. These are reported once for the project:
- SQLSRC022, SQLSRC023 and SQLSRC038, about SqlSource's exceptions in the projects that the project references.
- SQLSRC247 and SQLSRC248, about the version of Npgsql.
- SQLSRC267 and SQLSRC268, about the version of Microsoft.Data.SqlClient.
Two more have no file and line, and the project can get more than one of each:
- SQLSRC273, a driver that the project does not reference, is reported once for each driver that is missing, Npgsql or Microsoft.Data.SqlClient.
- SQLSRC282, a library that is too old, is reported once for each package that is too old.
SQLSRC021, a compiler that is too old, comes before the build compiles anything.
What an error costs
Most errors cost part of what SqlSource generates, until you fix them. What an error costs depends on what it is about.
- How a
.sqlfile is written. An error from SQLSRC101 to SQLSRC120, or SQLSRC126, costs the file all its members and models. The other files of the type keep theirs. The section of SQLSRC120 says when it costs only a type that keeps comments. - Where a query's members go. An error from SQLSRC122 to SQLSRC125 costs the file its members and models for the type that the error is reported for. Another type that claims the file keeps them. The section of SQLSRC123 says when it costs one method alone.
- An empty list. SQLSRC127 is reported only for a query whose output is
repositoryormethods. It costs that query its method, and nothing else. - Describing a query, or its sidecar. An error such as SQLSRC241 costs the query that it is about its models. SQLSRC209 costs its models to each query of the file that needs an entry. The other members of the file stay in place.
- A repository. Each of SQLSRC028 to SQLSRC034, and SQLSRC036, costs a method to each repository query of the logical databases that it is about. The warning SQLSRC031 is not one of them. The models of those queries are still generated.
A query can get several errors at once. If a query has an error about describing it, its sidecar, its models or its method, the query's output decides what it keeps:
- If the output is
models, the query keeps its constant or its token method. - If the output is
repositoryormethods, the query gets no method until you fix every error.
The section of an error says when it costs less. SQLSRC297 costs only the collection method, SQLSRC299 only the synchronous methods, and SQLSRC281 costs nothing.
While a .sql file has an error of its own, the build checks less of its sidecar: see sidecar files.
Who reports an error: the build, the tool, or both
Two things report errors: the build of your project, and the sqlsource tool, such as dotnet sqlsource describe. Each section of Diagnostics has a line under its title that says which one reports its error.
| Reported by | Ids | What you see |
|---|---|---|
| The build alone | SQLSRC001 to SQLSRC013, SQLSRC020 to SQLSRC038, SQLSRC121 to SQLSRC125, SQLSRC127, SQLSRC237 to SQLSRC261, SQLSRC267 to SQLSRC270, SQLSRC272 to SQLSRC284, and SQLSRC297 to SQLSRC299 |
The build reports them, and the tool never does. SQLSRC020, a key that a settings file repeats, is the build's alone. SQLSRC122 to SQLSRC125 depend on the type that claims the file, and SQLSRC127 on the query's output |
| The tool alone | SQLSRC200 to SQLSRC208, SQLSRC211 to SQLSRC236, SQLSRC262 to SQLSRC266, SQLSRC271, and SQLSRC285 to SQLSRC296 |
The tool reports them. A build shows them only when it runs the tool, as running in the build says |
The build and the tool: how a .sql file is written |
SQLSRC101 to SQLSRC120, and SQLSRC126 |
The tool reports them with the same id as the build. The problem is the same, and so is the fix |
| The build and the tool: a settings file | SQLSRC015 to SQLSRC019 |
The tool reports them at the same line and column as the build. It reports them only for a settings file that applies to a .sql file or a C# file of a project it runs on. It reports each once in a run, however many of those projects the file applies to. The tool reports SQLSRC019 for dialect, output and database alone. The build reports it for every key but database, whose value the tool alone checks |
| The build and the tool: a query that cannot be described | SQLSRC209 and SQLSRC210 |
Each reports them at the same place: the query that must be described and cannot be |
In a build that runs the tool, the build lists each error that both report once: see running in the build.
The tool's errors
$ dotnet sqlsource describe --check
/work/App/Queries/Users.sql(3,10): error SQLSRC219: The sidecar is out of date for 'GetUser': the query has changed since it was described
help: run 'dotnet sqlsource describe' and commit the sidecars
see: https://mbcrawfo.github.io/SqlSource/diagnostics.html#sqlsrc219
The tool prints its errors itself, in your terminal. Each error has the format of a build error: its place, error, the id and the message. The place is the file, with the line and column when the error has them. An error with no file starts with sqlsource in place of a path.
Lines under the error tell you more. A help: line, when the error has one, says what to do. The last line, see:, links to the error's section of Diagnostics.
The tool's exit code says whether it reported an error: see exit codes. In a build that runs the tool, each of its errors is an error of the build: see running in the build.
Errors by area
Ids below 100 are about the type that carries [SqlSourceGenerate], or about the project. Ids from 101 to 127 are about the contents of a .sql file.
| Area | Ids | Reported by | Where |
|---|---|---|---|
| Project and attribute | SQLSRC001, SQLSRC002, SQLSRC003, SQLSRC004, SQLSRC005, SQLSRC007, SQLSRC008, SQLSRC009, SQLSRC012, SQLSRC013 | The build | In the C# file, at the type's name or its [SqlSourceGenerate]. SQLSRC008, SQLSRC009 and SQLSRC013 are in the .sql file |
| Settings files | SQLSRC015, SQLSRC016, SQLSRC017, SQLSRC018, SQLSRC019, SQLSRC020 | The build and the tool, but SQLSRC020 the build alone |
At the line and column in the settings file |
| The compiler | SQLSRC021 | The build | Before the build compiles anything |
| Projects that share SqlSource's exceptions | SQLSRC022, SQLSRC023 | The build | No file and line, once for the project |
| A build that runs the tool | SQLSRC024, SQLSRC025, SQLSRC026, SQLSRC027 | The build | At the project file |
| Repositories | SQLSRC028, SQLSRC029, SQLSRC030, SQLSRC031, SQLSRC032, SQLSRC033, SQLSRC034, SQLSRC035, SQLSRC036, SQLSRC037 | The build | In the C# file, at the type's [SqlSourceGenerate] or at the member that the error names. SQLSRC032 and SQLSRC033 of a factory's member are at the field, property or parameter that holds the factory. Only for a type that claims a query whose output is repository, but SQLSRC032 of a static member of the project, or of a mark that can never give a connection, which is at the mark whatever the queries. A static member of a base type of a repository is the repository's own member, and is reported with it |
| Projects that share SqlSource's exceptions across frameworks | SQLSRC038 | The build | No file and line, once for the project |
.sql files |
SQLSRC101, SQLSRC102, SQLSRC103, SQLSRC104, SQLSRC105, SQLSRC106, SQLSRC107, SQLSRC108, SQLSRC109, SQLSRC110, SQLSRC111, SQLSRC112, SQLSRC113, SQLSRC114, SQLSRC115, SQLSRC116, SQLSRC117, SQLSRC118, SQLSRC119, SQLSRC120, SQLSRC121, SQLSRC122, SQLSRC123, SQLSRC124, SQLSRC125, SQLSRC126, SQLSRC127 | The build and the tool, but SQLSRC121 to SQLSRC125 and SQLSRC127 the build alone |
At the line and column in the .sql file |
| The tool | SQLSRC200, SQLSRC201, SQLSRC202, SQLSRC203, SQLSRC204, SQLSRC205, SQLSRC206, SQLSRC207, SQLSRC208, SQLSRC209, SQLSRC210, SQLSRC211, SQLSRC212, SQLSRC213, SQLSRC214, SQLSRC215, SQLSRC216, SQLSRC217, SQLSRC218, SQLSRC219, SQLSRC220, SQLSRC221, SQLSRC222, SQLSRC223 | The tool, and SQLSRC209 and SQLSRC210 the build too |
At the query, the file, the project or the solution that the error is about. Some have no file |
| Describing a query | SQLSRC224, SQLSRC225, SQLSRC226, SQLSRC227, SQLSRC228, SQLSRC229, SQLSRC230, SQLSRC231, SQLSRC232, SQLSRC233, SQLSRC234, SQLSRC235, SQLSRC236 | The tool | In the .sql file, at the query's name. An error about the database is at its first query |
The sidecar of a .sql file |
SQLSRC237, SQLSRC238, SQLSRC239, SQLSRC240, SQLSRC241, SQLSRC242, SQLSRC243, SQLSRC244, SQLSRC245 | The build | In the sidecar of a .sql file that a type uses, at the line and column of the problem. SQLSRC241 to SQLSRC244 are at the query in the .sql file |
| The C# types of a query | SQLSRC246, SQLSRC247, SQLSRC248, SQLSRC249 | The build | At the query's name. SQLSRC247 and SQLSRC248 have no file and line, and are reported once for the project |
| A C# type of your choice | SQLSRC250, SQLSRC251, SQLSRC252 | The build | At the name of each query that has a column or a parameter of the type |
| The models of a query | SQLSRC253, SQLSRC254, SQLSRC255, SQLSRC256, SQLSRC257, SQLSRC258, SQLSRC259, SQLSRC260 | The build | At the query's name, or at the marker that the error is about |
| An entry of the type override that maps nothing | SQLSRC261 | The build | At the query's name |
| The parameters of a SQL Server query | SQLSRC262 | The tool | At the query's name |
| The columns of a SQL Server query | SQLSRC263, SQLSRC264, SQLSRC265, SQLSRC266 | The tool | At the query's name |
| The C# types of a SQL Server query | SQLSRC267, SQLSRC268, SQLSRC269, SQLSRC270 | The build | At the query's name. SQLSRC267 and SQLSRC268 have no file and line, and are reported once for the project |
| The encoding of a file | SQLSRC271 | The tool | At the .sql file, with no line and column. For a C# file, at its Source or at the type's name |
| The methods of a query | SQLSRC272, SQLSRC273, SQLSRC274, SQLSRC275, SQLSRC276 | The build | At the query's name. SQLSRC273 has no file and line. SQLSRC276 is at the type's [SqlSourceGenerate] |
| Converters | SQLSRC277, SQLSRC278, SQLSRC279, SQLSRC280 | The build | At the converter's name in the C# file, or at the query's name |
| The libraries of a query | SQLSRC281, SQLSRC282 | The build | SQLSRC281 is at the entry of the settings file or the marker that turns the library on. SQLSRC282 has no file and line |
| The JSON opt-in | SQLSRC283 | The build | At the query's name |
| A short name of your choice | SQLSRC284 | The build | At the query's name |
A .env file |
SQLSRC285, SQLSRC286, SQLSRC287 | The tool | At the .env file, or at the line and column of a variable in it. SQLSRC287 is at the folder that is watched |
| A bug-report bundle | SQLSRC288, SQLSRC289, SQLSRC290, SQLSRC291 | The tool | At the bundle |
Making a bug report with diagnose |
SQLSRC292, SQLSRC293, SQLSRC294, SQLSRC295, SQLSRC296 | The tool | At the bundle. SQLSRC292 is at the .sql file |
| The collection method of a query | SQLSRC297 | The build | At the query's name |
| A query's synchronous method | SQLSRC298, SQLSRC299 | The build | At the query's name |
SQLSRC224 to SQLSRC236, and SQLSRC262 to SQLSRC266, are the errors of describing a query against its database, PostgreSQL or SQL Server. The section of each names the database that gives it.
The build checks the models of a query, SQLSRC253 to SQLSRC260, only while the query's entry in its sidecar is current. For SQLSRC253 to SQLSRC258, each column and parameter of the query must also have a C# type.