Note
This work is sponsored by Monibot - Easy Server and Application Monitoring. Try out Monibot at https://monibot.io.
Sqinn is an alternative to the SQLite C API. Sqinn reads requests from stdin, forwards the request to SQLite, and writes a response to stdout. It is used in programming environments that do not allow calling C API functions.
The SQLite database library is written in C and provides an API for using it in C/C++. There are many language bindings. If you cannot or do not want to use one of the available language bindings, and your programming language allows the creation of subprocesses (fork/exec), an option might be to communicate with SQLite over stdin/stdout, using Sqinn.
One example is Go: There exist a bunch of Go libraries
for reading and writing SQLite databases. Most of them use cgo to call the
SQLite C API functions. While this works (very well, indeed), it has drawbacks:
First, you have to have gcc installed on your development system. Second, cgo
slows down the Go compilation process. Third, cross compiling a cgo program to
another platform (say from Linux to MacOS) is hard to setup.
Sqinn provides functions that map to SQLite functions, like sqlite3_open(),
sqlite3_prepare(), sqlite3_bind(), and so on. If you have not read the
Introduction to the SQLite C/C++
Interface, now it's a good time. It's a
5-minute read and shows the basic workings of SQLite.
Marshalling requests and responses back and forth between process boundaries is, of course, slow. To improve performance, Sqinn provides functions that lets you call multiple SQLite functions in one request/response cycle.
All function calls and the binary IO protocol used for marshalling request and response data is described in io_protocol.md.
For the Go (Golang) language binding, see https://github.com/cvilsmeier/sqinn-go, for benchmarks, see https://github.com/cvilsmeier/sqinn-go-bench.
See the included build.sh script for compiling Sqinn with gcc. I have
tested it on the following platforms:
- Windows 10 amd64, using Mingw64 gcc (tdm64-gcc-9.2.0 from https://jmeubank.github.io/tdm-gcc/)
- Debian Linux 11 amd64
The releases page contains a tar file with pre-built binaries for Windows amd64 and Linux amd64, see https://github.com/cvilsmeier/sqinn/releases.
If you want to compile Sqinn, have gcc installed and follow the steps:
$ git clone https://github.com/cvilsmeier/sqinn
$ cd sqinn
$ chmod a+x build.sh clean.sh
$ ./build.sh
The build script creates a bin subdirectory that the build results go into.
Test it with:
$ bin/sqinn test
There isn't really one. Sqinn is not used by humans, it's used by other programs. That said:
$ sqinn help
Sqinn is SQLite over stdin/stdout
Usage:
sqinn [options...] [command]
Commands are:
help show this help page
version print Sqinn version
sqlite_version print SQLite library version
test execute built-in unit tests
bench execute built-in benchmarks
Options are:
-db db file, used for test and bench
commands. Default is ":memory:"
When invoked without a command, Sqinn will read (await) requests
from stdin, print responses to stdout and output error messages
on stderr.
Sqinn is single threaded. It serves requests one after another.
Sqinn supports only a subset of the many functions that the SQLite C/C++ API provides. Interruption of SQL operations, backup functions, vfs and extension functions are not supported, among others.
As of now, Sqinn does not support multiple active statements at a time. If a caller tries to prepare a statement while another one is still active (i.e. un-finalized), Sqinn will bark.
See version in src/util.h
- SQLite Version 3.45.3 (2024-04-15)
- SQLite Version 3.45.2 (2024-03-12)
- SQLite Version 3.45.0 (2024-01-15)
- SQLite Version 3.44.2 (2023-11-24)
- SQLite Version 3.44.0 (2023-11-01)
- SQLite Version 3.43.2 (2023-10-10)
- SQLite Version 3.43.1 (2023-09-11)
- SQLite Version 3.43.0 (2023-08-24)
- SQLite Version 3.42.0 (2023-05-16)
- SQLite Version 3.41.2 (2023-03-22)
- SQLite Version 3.41.1 (2023-03-10)
- SQLite Version 3.41.0 (2023-02-21)
- SQLite Version 3.40.1 (2022-12-28)
- SQLite Version 3.40.0 (2022-11-16)
- SQLite Version 3.39.4 (2022-09-29)
- SQLite Version 3.39.2 (2022-07-21)
- SQLite Version 3.39.0 (2022-06-25)
- SQLite Version 3.38.5 (2022-05-06)
- SQLite Version 3.38.3 (2022-04-27)
- SQLite Version 3.38.2 (2022-03-26)
- SQLite Version 3.38.1 (2022-03-12)
- SQLite Version 3.38.0 (2022-02-22)
- SQLite Version 3.37.2 (2022-01-06)
- SQLite Version 3.37.0
- sqlite 3.36.0 (2021-06-18)
- sqlite 3.35.5 (2021-04-19)
- sqlite 3.35.4 (2021-04-02)
- fix version tests
- sqlite 3.35.2 (2021-03-17)
- fixed version number
- sqlite v3.34.1 (2021-01-20)
- sqlite v3.33.0
- fix unsuccessful FC_EXEC/QUERY leaked prepared statement
- sqlite v3.32.3
- fast IEEE 745 encoding for double values
- first version
I will reject most PRs and feature requests. Why? Because I use sqinn for my own projects, and I want it to be fast, secure, robust and easy to maintain. I cannot include every feature under the sun. I give it away for free, so everybody can adjust it to his or her own needs.
This is free and unencumbered software released into the public domain.
Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.
In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
For more information, please refer to https://unlicense.org