Should .sqlx folder be in .gitignore?

[Schmiddiii]

We are currently unsure whether the .sqlx folder should be gitignored in this PR. In my opinion (see this comment), it should be gitignored as it is generated automatically (it is also in the .gitignore file of the sqlx project, see this PR that introduced it). But without this folder, it is not possible to compile the project without setting up a database (see this answer).

What is the correct way to handle the .sqlx folder? I could not find a definive answer in any discussion, issue or the FAQ of this project.

[abonander]

Consider the Cargo.lock file. It's a generated file, and thus by your logic, it should always be in the .gitignore, right? But there are merits to checking it into version control, and the cargo new template does this by default.

Of course, things are a little different for libraries, which I see is what you're developing. The advice used to be to not check in the Cargo.lock, because it doesn't matter to the user of the library. But it's still a good idea to check it in, because it helps contributors to the library, by ensuring that they can build with the same set of dependencies and versions that the CI will be using. Also, so every CI run doesn't implicitly run cargo update, which I've learned the hard way can cause random breakages in the most surprising ways, even if everyone's technically obeying SemVer.

Bottom line, even though it's a generated file, it enables reproducible builds, which tends to be pretty important to mitigate "works on my machine"-type issues. (I also noticed that you actually don't have a Cargo.lock checked in, I'm guessing for the same reason. I'd recommend reconsidering that.)

It's the exact same idea with the .sqlx folder. It enables people to build the project and get a predictable result without having to reconstruct the exact same dev environment as the original author. Edit: this is especially important for a library, where SQLx is merely an implementation detail. The less you burden the user with, the better.

What is the correct way to handle the .sqlx folder? I could not find a definive answer in any discussion, issue or the FAQ of this project.

How about in the actual documentation? Says right there in step 3:

Check the generated .sqlx directory into version control.

It's also in the README for sqlx-cli which you're directed to read by the relevant section in the root README.

At the end of the day though, it's all about tradeoffs. If you think it should be checked in, check it in. If you don't, then don't. If you were looking for a dogmatic answer, you came to the wrong place.

[Schmiddiii]

Thanks for your answer. In that case, we should probably include it.

How about in the actual documentation? Says right there in step 3:

I probably missed it as I searched for .gitignore in all the documentations. Should have searched for something like "version control" instead. Thats my fault.