Getting Started

SQLite over the network.

Overview

nsqlite runs a 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>

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.

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.