Consider improving the VFS design explanation

[michaellenaghan]

I'm having a hard time convincing myself that I understand the VFS design explanation correctly.

That could, of course, be a me thing.

But maybe it's not just a me thing?

Here are some suggestions.

• The explanation uses the term "Unix", and it isn't clear what that actually means. For example, is macOS a "Unix"? I think it would help to define "Unix" in terms of platforms, or avoid "Unix" and just enumerate platforms?

• The explanation of BSD locks says "This package can also use BSD locks, albeit with reduced concurrency (BEGIN IMMEDIATE behaves like BEGIN EXCLUSIVE)." I think it would help to clarify that EXCLUSIVE and IMMEDIATE are the same in WAL mode anyway?

The first time I looked at the VFS design explanation I had the impression that there were, or there could be, significant issues.

After looking at the code, though, my impression is that locks and WAL mode actually work as expected on all major platforms?

If that's correct, it took reading code to come to that conclusion.

If it isn't, well, as I said: I had a hard time convincing myself that my conclusion was correct. :-)

[ncruces]

Unix here, is any platform for which SQLite uses os_unix.c:

This file contains the VFS implementation for unix-like operating systems include Linux, MacOSX, *BSD, QNX, VxWorks, AIX, HPUX, and others.

Or, in Go terms, any platform you can use golang.org/x/sys/unix on.

So yes, macOS is a Unix.

Also yes, the difference between BEGIN IMMEDIATE and BEGIN EXCLUSIVE is irrelevant for Wal mode. It reduces concurrency a bit in rollback journal mode.

As for whether the VFS is good enough in general, I guess this is the better summary: anything green or yellow is OK, IMO; orange less so; and red… not so.

Detailing the compromises in terms non-experts can understand, and help users not jeopardize their data, is challenging. But I'll try to improve.

[michaellenaghan]

Thanks for the link! That table is very, very helpful. Perhaps it should be the focus of the explanation? It seems to say almost everything that needs to be said. (And it makes the definition of "Unix" unnecessary. Well: it makes it an implementation detail.)

The only thing that page is missing, perhaps, is the connection between "reduced concurrency" and WAL mode.

[michaellenaghan]

The VFS design says:

Accessing databases concurrently using incompatible implementations will eventually corrupt data.

It might be worth making that the first sentence of the paragraph, rather than the last, so that it stands out?

And would the same thing be true for incompatible shared memory implementations if the database was opened in WAL mode?