varavel/nsqlite

By varavel

•Updated 5 months ago

SQLite over the network with optional Litestream integration

Image

718

Overview Tags

varavel/nsqlite repository overview

SQLite over the network.

⁠ ⁠ ⁠ ⁠ ⁠

⁠

⁠Overview

nsqlite runs a docker-first SQLite-backed HTTP server and ships with a container image that can optionally wrap the process with litestream for continuous replication to any S3-compatible object store.

Container images are published to both Docker Hub and GitHub Container Registry with matching tags:

Docker Hub: varavel/nsqlite:<tag>
GHCR: ghcr.io/varavelio/nsqlite:<tag>

For the full documentation site (including an interactive API explorer), visit nsqlite.varavel.com⁠.

⁠Quick Start

Run NSQLite without Litestream using Docker Compose:

services:
  nsqlite:
    image: varavel/nsqlite:latest
    ports:
      - "9876:9876"
    volumes:
      - ./data:/data
    ulimits:
      nofile:
        soft: 65536
        hard: 65536

Run NSQLite with Litestream and an S3-compatible replica using Docker Compose:

services:
  nsqlite:
    image: varavel/nsqlite:latest
    ports:
      - "9876:9876"
    volumes:
      - ./data:/data
    environment:
      NSQLITE_LITESTREAM_ENABLED: "true"
      NSQLITE_LITESTREAM_S3_BUCKET: my-backups
      NSQLITE_LITESTREAM_S3_PATH: db-backup/database.sqlite
      NSQLITE_LITESTREAM_S3_ENDPOINT: https://minio.example.com:9000
      NSQLITE_LITESTREAM_S3_REGION: us-east-1
      NSQLITE_LITESTREAM_S3_ACCESS_KEY_ID: your-access-key
      NSQLITE_LITESTREAM_S3_SECRET_ACCESS_KEY: your-secret-key
    ulimits:
      nofile:
        soft: 65536
        hard: 65536

⁠NSQLite Configuration

The container always configures NSQLite through environment variables and it has sane default values.

Variable	Container default	Description
`NSQLITE_AUTH_TOKEN`	unset	Admin token list. Use space-separated plaintext tokens or bcrypt/argon2id hashes for full access.
`NSQLITE_AUTH_TOKEN_RW`	unset	Read/write token list. Use space-separated plaintext tokens or bcrypt/argon2id hashes for query read/write access only.
`NSQLITE_AUTH_TOKEN_RO`	unset	Read-only token list. Use space-separated plaintext tokens or bcrypt/argon2id hashes for query read access only.
`NSQLITE_DATA_DIR`	`/data`	Directory used by NSQLite to store its SQLite files. The main database file is always `${NSQLITE_DATA_DIR}/database.sqlite`.
`NSQLITE_LISTEN_HOST`	`0.0.0.0`	Host/interface NSQLite binds to inside the container.
`NSQLITE_LISTEN_PORT`	`9876`	TCP port used by the HTTP server.
`NSQLITE_TX_IDLE_TIMEOUT`	`10s`	Maximum idle time for an open transaction before it is rolled back.
`NSQLITE_MAX_READ_CONNS`	`10`	Maximum number of read-only SQLite connections.
`NSQLITE_CACHE_SIZE_KB`	`20000`	SQLite cache size in KB per connection.
`NSQLITE_BUSY_TIMEOUT`	`5s`	How long SQLite waits when the database is locked by another writer.
`NSQLITE_MAX_REQUEST_SIZE_MB`	`100`	Maximum HTTP body size accepted by the `/query` endpoint.

⚠️ Important: Auth tokens security

Always prefer using token hashes over plaintext tokens. The recommended algorithm is Argon2ID, followed by Bcrypt as a secondary option. Plaintext tokens are discouraged, as they can be exposed if environment variables or the container are compromised.

Browser access: NSQLite is designed to run on servers. If browser-based access is needed (e.g. for a web based DB explorer), place NSQLite behind a reverse proxy like Nginx or Caddy and configure CORS headers there.

⁠rqlite Compatibility

NSQLite is compatible with the rqlite HTTP API⁠ request and response format. However, whenever possible, use NSQLite's native RPC format.

⁠Litestream Configuration

When NSQLITE_LITESTREAM_ENABLED=true, the container writes a Litestream config that uses the explicit S3-compatible configurations.

Credentials are intentionally not written to the generated YAML file. The entrypoint translates the S3 credential variables into the runtime environment that Litestream expects.

⁠Required Litestream Variables

These variables are required when NSQLITE_LITESTREAM_ENABLED=true.

Variable	Description
`NSQLITE_LITESTREAM_ENABLED`	Set to `true` to run NSQLite under Litestream.
`NSQLITE_LITESTREAM_S3_BUCKET`	Bucket or container name used for the replica.
`NSQLITE_LITESTREAM_S3_PATH`	Object path inside the bucket for the replica data.
`NSQLITE_LITESTREAM_S3_ENDPOINT`	S3-compatible endpoint. Examples: `s3.us-east-1.wasabisys.com`, `https://minio.example.com:9000`, `http://localhost:9000`.
`NSQLITE_LITESTREAM_S3_REGION`	Replica region. Use the provider value that matches the target bucket.
`NSQLITE_LITESTREAM_S3_ACCESS_KEY_ID`	Access key used by Litestream.
`NSQLITE_LITESTREAM_S3_SECRET_ACCESS_KEY`	Secret key used by Litestream.

⁠Optional Litestream Variables

Variable	Default	Description
`NSQLITE_LITESTREAM_S3_SESSION_TOKEN`	unset	Optional session token when temporary credentials are used.
`NSQLITE_LITESTREAM_CONFIG_PATH`	`/tmp/litestream.yml`	Where the container writes the generated Litestream config file.
`NSQLITE_LITESTREAM_LOG_LEVEL`	`info`	Litestream log level written into the generated config.
`NSQLITE_LITESTREAM_LOG_FORMAT`	`text`	Litestream log format written into the generated config.
`NSQLITE_LITESTREAM_SNAPSHOT_INTERVAL`	`24h`	Snapshot creation interval.
`NSQLITE_LITESTREAM_SNAPSHOT_RETENTION`	`168h`	Snapshot retention period.
`NSQLITE_LITESTREAM_SYNC_INTERVAL`	`1s`	How often Litestream syncs changes to the replica.
`NSQLITE_LITESTREAM_VALIDATION_INTERVAL`	`5m`	How often Litestream validates replica state.

⁠Notes for S3-Compatible Providers

If your provider accepts an endpoint without a scheme, you can pass it directly. Litestream assumes HTTPS by default.
For local development, an explicit http:// endpoint is valid.
The endpoint and region must match the target provider and bucket configuration.
This image keeps the configuration surface intentionally small. Advanced provider-specific settings should be added only when there is a concrete need.

⁠License

This project is released under the MIT License. See LICENSE⁠.

Tag summary

Recent tags

Content type

Image

Digest

sha256:1ddd3499d…

Size

47.1 MB

Last updated

5 months ago

docker pull varavel/nsqlite