canonical / dqlite-docs Goto Github PK

While developing an Erlang client for Dqlite, I discovered that the documentation of the wire protocol doesn't mention the DQLITE_UNIXTIME tuple value type (type code: 9) when it can be returned by Dqlite in row tuples for example. It seems that the documentation of the wire protocol is not part of this repository so I can't open a PR to modify the documentation myself, it's the reason why I opened an issue.

We want to go through the docs on dqlite.io, update or remove any statements that are out of date, and add basic descriptions of interfaces -- like request types -- that have been implemented in the last couple of years. This is separate from the more comprehensive rewrite that's planned for the future once we have a C client library to document.

Checklist (WIP)

• Remove out-of-date stuff about checkpointing
• Update docs for ASSIGN request (formerly PROMOTE)
• Document new request types:
  • TRANSFER
  • DESCRIBE
  • WEIGHT
• Document new response types
• Document schema version 1 for EXEC, EXEC_SQL, QUERY, QUERY_SQL
• Update documentation about significance of schema version
• Clarify documentation about the two addresses passed into the dqlite server API
• Discussion of snapshotting

Why I'm thinking it's worth it:

SQLite is a MVVC database, which means that conceptually, for a stale row to be evicted (or a whole lot of them during VACUUM), the database needs to know when all the "old" read transactions have finished.

SQLite VACUUM obtains an exclusive lock for this process, but that's not something naively feasible in a distributed database.

At the same time, operators (people) need to know when the space may be reclaimed, ideally across the cluster.