There is a discussion over the future direction for this project. Take a look, and chip in if you want!

ws4sql is a server application that, applied to one or more database files, allows to perform SQL queries and statements on them via REST (or better, JSON over HTTP). It supports SQLite and DuckDB.

Possible use cases are the ones where remote access to an embedded db is useful/needed, for example a data layer for a remote application, possibly serverless or even called from a web page (after security considerations of course).

Client libraries are available, that will abstract the "raw" JSON-based communication. See here for Java/JVM, here for Go(lang); others will follow.

As a quick example, after launching

ws4sql --db mydatabase.db

It's possible to make a POST call to http://localhost:12321/mydatabase, e.g. with the following body:

// Set Content-type: application/json
{
    "resultFormat": "map", // "map" or "list"; if omitted, "map"
    "transaction": [
        {
            "statement": "INSERT INTO TEST_TABLE (ID, VAL, VAL2) VALUES (:id, :val, :val2)",
            "values": { "id": 1, "val": "hello", "val2": null }
        },
        {
            "query": "SELECT * FROM TEST_TABLE"
        }
    ]
}

Obtaining an answer of

{
    "results": [
        {
            "success": true,
            "rowsUpdated": 1
        },
        {
            "success": true,
            "resultSet": [
                { "ID": 1, "VAL": "hello", "VAL2": null }
            ]
        }
    ]
}

Features

Docs, a Tutorial, a Discord.

• Aligned to SQLite 3.50.3 and DuckDB 1.3.2;
• A single executable file (written in Go);
• HTTP/JSON access, with client libraries for convenience;
• Directly call ws4sql on a database (as above), many options available using a YAML companion file;
• In-memory DBs are supported;
• Serving of multiple databases in the same server instance;
• Batching of multiple value sets for a single statement;
• Parameters may be passed to statements positionally (lists) or by name (maps);
• Results of queries may be returned as key-value maps, or as values lists;
• All queries of a call are executed in a transaction;
• For each query/statement, specify if a failure should rollback the whole transaction, or the failure is limited to that query;
• "Stored Statements": define SQL in the server, and call it from the client;
• CORS mode, configurable per-db;
• Scheduled tasks, cron-like and/or at startup, also configurable per-db;
• Scheduled tasks can be: backup (with rotation), vacuum and/or a set of SQL statements;
• Provide initialization statements to execute when a DB is created;
• (for SQLite) WAL mode enabled by default, can be disabled;
• Quite fast!
• Embedded web server to directly serve web pages that can access ws4sql without CORS;
• Compact codebase;
• Comprehensive test suite (make test);
• 4 os's/arch's directly supported (linux, amd64 and arm64; macos, arm64; windows, amd64);
• Docker images, for amd64, arm and arm64.

Security Features

• Authentication can be configured
  • on the client, either using HTTP Basic Authentication or specifying the credentials in the request;
  • on the server, either by specifying credentials (also with hashed passwords) or providing a query to look them up in the db itself;
  • customizable Not Authorized error code (if 401 is not optimal)
• A database can be opened in read-only mode (only queries will be allowed);
• It's possible to enforce using only stored statements, to avoid some forms of SQL injection and receiving SQL from the client altogether;
• CORS Allowed Origin can be configured and enforced;
• It's possible to bind to a network interface, to limit access.

Design Choices

Some design choices:

• Very thin layer over the database. Errors and type translation, for example, are those provided by the db driver;
• Doesn't include HTTPS, as this can be done easily (and much more securely) with a reverse proxy;
• Doesn't support SQLite/DuckDB extensions, to improve portability.

Contacts and Support

Let's meet on Discord!

Credits

Many thanks and all the credits to these awesome projects:

• lnquy's cron (MIT License);
• robfig's cron (MIT License);
• gofiber's fiber (MIT License);
• marcboeker's go-duckdb (MIT License);
• mitchellh's go-homedir (MIT License);
• mattn's go-sqlite3 (MIT License);
• wI2L's jettison (MIT License)
• iancoleman's orderedmap (MIT License);
• and of course, Google Go.

Kindly supported by JetBrains for Open Source development

GPG Signing

Import my key:

curl -sSL https://public.germanorizzo.it/4BD993A579025E4932C0110DC368E8BA7D4453F6.gpgkey | gpg --import -