Reimplemnetation of part of sqlite3(1)'s .dump command.

Writing data in sqlite3 dump file format

This is a replacement for sqlite3(1) CLI .dump.

That fearure is often unsuitable because:

• It drops TEXT data after nul bytes (srsly!)
• It won't necessarily produce UTF-8 output
• It needs to run as a CLI utility, so you can't feed it the data to archive from a db transaction. (We can't give sqlite3(1) access to our in-program transaction.)

So we reimplement it.

Features

• Faithful reproduction of whole rows, provided as [rusqlite::Row] or [HashMap], in a format that sqlite3 can read.
• Storing the schema.
• Selectively storing some rows.

Stability and useability warning

This crate's features are quite closely matched to the needs of its caller.

And the API is not yet declared stable. We will adhere to semver, but API bumps may occur more often that you like. The MSRV is also subject to ad-hoc increase.

If you find this library useful, please let us know (for example by filing a ticket) and we will consider offering better stability.

Text encoding

Text is quite tricky. sqlite3 can store invalid UTF-8, and (contrary to the docs) sqlite3(1) can dump and reload it. But we want our archive file to be UTF-8. sqlite3 doesn't provide useful string de-escaping. It provides a char() function but that can only insert valid UTF-8. A search of the manual yielded CAST(x'abcd' AS TEXT) which gives raw bytes in the the database's natural encoding. This will be UTF-8, but we must check it with a pragma.

I have checked that Rust's format!("{:e}", f64::MAX) produces untruncated (precise) output.

Why this exists

Debian's tag2upload-service-manager wants a format for archiving. It should be:

• straighrforward
• textual
• faithful
• machine-readable

We shouldn't put any non-UTF-8 in our db, but sqlite3 can represent it so I don't want to rule it out.

JSON can't represent non-UTF-8. Most other formats are worse.

The sqlite3 dump format (a series of commands to create the db and populate it with data) is nearly good enough.

But generating it isn't so easy. That's what this library is for.