libSQL Daemon

.env-example

# Database Path
SQLD_DB_PATH=data.sqld

# HTTP Listener Address
SQLD_HTTP_LISTEN_ADDR=127.0.0.1:8080

# Hrana Listener Address
SQLD_HRANA_LISTEN_ADDR=

# Admin HTTP API Address
SQLD_ADMIN_LISTEN_ADDR=

# JWT Key File for Authentication
SQLD_AUTH_JWT_KEY_FILE=

# HTTP Authentication
SQLD_HTTP_AUTH=

# HTTP Self URL for Sticky Sessions
SQLD_HTTP_SELF_URL=

# gRPC Listener Address
SQLD_GRPC_LISTEN_ADDR=

# Primary gRPC URL for Writes
SQLD_PRIMARY_GRPC_URL=

# Enable Bottomless Replication
SQLD_ENABLE_BOTTOMLESS_REPLICATION=

# Idle Shutdown Timeout (seconds)
SQLD_IDLE_SHUTDOWN_TIMEOUT_S=

# Initial Idle Shutdown Timeout (seconds)
SQLD_INITIAL_IDLE_SHUTDOWN_TIMEOUT_S=

# Maximum Log Size (MB)
SQLD_MAX_LOG_SIZE=200

# Maximum Log Duration (seconds)
SQLD_MAX_LOG_DURATION=

# Heartbeat URL
SQLD_HEARTBEAT_URL=

# Heartbeat Authorization Header
SQLD_HEARTBEAT_AUTH=

# Heartbeat Period (seconds)
SQLD_HEARTBEAT_PERIOD_S=30

# Soft Heap Limit (MB)
SQLD_SOFT_HEAP_LIMIT_MB=

# Hard Heap Limit (MB)
SQLD_HARD_HEAP_LIMIT_MB=

# Maximum Response Size
SQLD_MAX_RESPONSE_SIZE=10MB

# Maximum Total Response Size
SQLD_MAX_TOTAL_RESPONSE_SIZE=32MB

# Snapshot Execution Command
SQLD_SNAPSHOT_EXEC=

# Checkpoint Interval (seconds)
SQLD_CHECKPOINT_INTERVAL_S=

# Maximum Active Namespaces
SQLD_MAX_ACTIVE_NAMESPACES=100

# Backup Metadata Store
SQLD_BACKUP_META_STORE=

# S3 Access Key ID for Metadata Store Backup
SQLD_META_STORE_ACCESS_KEY_ID=

# S3 Secret Access Key for Metadata Store Backup
SQLD_META_STORE_SECRET_ACCESS=

# S3 Region for Metadata Store Backup
SQLD_META_STORE_REGION=

# Metadata Store Backup ID
SQLD_META_STORE_BACKUP_ID=

# S3 Bucket Name for Metadata Store Backup
SQLD_META_STORE_BUCKET_NAME=

# Metadata Store Backup Interval (seconds)
SQLD_META_STORE_BACKUP_INTERVAL_S=

# S3 Endpoint for Metadata Store Backup
SQLD_META_STORE_BUCKET_ENDPOINT=

# Encryption Key for Encryption at Rest
SQLD_ENCRYPTION_KEY=

# Maximum Concurrent Connections
SQLD_MAX_CONCURRENT_CONNECTIONS=128

# Maximum Concurrent Requests
SQLD_MAX_CONCURRENT_REQUESTS=128

# Allow Metadata Store Recovery from Older Version
SQLD_ALLOW_METASTORE_RECOVERY=

# Shutdown Timeout (seconds)
SQLD_SHUTDOWN_TIMEOUT=30

sqld-help.md

SQL Daemon Command-Line Interface (CLI) Guide

Overview

The sqld command is used to start and manage the SQL daemon. Below is a comprehensive guide on how to use it, including its commands and options.

Usage

sqld [OPTIONS] [COMMAND]

Commands

• dump: Dump the current database.
• help: Print the help message or the help of the specified subcommand(s).

Options

• -d, --db-path <DB_PATH>

  • Specify the path to the database.
  • Environment Variable: SQLD_DB_PATH
  • Default: data.sqld

• -e, --extensions-path <EXTENSIONS_PATH>

  • Directory path where trusted extensions can be loaded. If the directory is present, it should contain a trusted.lst file with the sha256 and name of each extension, one per line.
  • Example:

    trusted.lst:
    sha256:extension1
    sha256:extension2
    

• --http-listen-addr <HTTP_LISTEN_ADDR>

  • Address and port for the HTTP listener.
  • Environment Variable: SQLD_HTTP_LISTEN_ADDR
  • Default: 127.0.0.1:8080

• --enable-http-console

  • Enable the HTTP console.

• -l, --hrana-listen-addr <HRANA_LISTEN_ADDR>

  • Address and port for the legacy, Web-Socket-only Hrana server.
  • Environment Variable: SQLD_HRANA_LISTEN_ADDR

• --admin-listen-addr <ADMIN_LISTEN_ADDR>

  • Address and port for the admin HTTP API.
  • Environment Variable: SQLD_ADMIN_LISTEN_ADDR

• --auth-jwt-key-file <AUTH_JWT_KEY_FILE>

  • Path to a file with a JWT decoding key used to authenticate clients in the Hrana and HTTP APIs. The key can be a PKCS#8-encoded Ed25519 public key in PEM, or plain bytes of the Ed25519 public key in URL-safe base64.
  • Environment Variable: SQLD_AUTH_JWT_KEY_FILE

• --http-auth <HTTP_AUTH>

  • Specify legacy HTTP basic authentication. The format should be "basic:$PARAM", where $PARAM is a base64-encoded string "$USERNAME:$PASSWORD".
  • Environment Variable: SQLD_HTTP_AUTH

• --http-self-url <HTTP_SELF_URL>

  • URL pointing to the HTTP API of this server. Used for "sticky sessions" in Hrana over HTTP.
  • Environment Variable: SQLD_HTTP_SELF_URL

• --grpc-listen-addr <GRPC_LISTEN_ADDR>

  • Address and port for the inter-node RPC protocol.
  • Example: 0.0.0.0:5001
  • Environment Variable: SQLD_GRPC_LISTEN_ADDR

• --grpc-tls

  • Enable TLS for gRPC.

• --grpc-cert-file <GRPC_CERT_FILE>

  • Path to the gRPC TLS certificate file.

• --grpc-key-file <GRPC_KEY_FILE>

  • Path to the gRPC TLS key file.

• --grpc-ca-cert-file <GRPC_CA_CERT_FILE>

  • Path to the gRPC TLS CA certificate file.

• --primary-grpc-url <PRIMARY_GRPC_URL>

  • gRPC URL of the primary node to connect to for writes.
  • Example: http://localhost:5001
  • Environment Variable: SQLD_PRIMARY_GRPC_URL

• --primary-grpc-tls

  • Enable TLS for primary gRPC.

• --primary-grpc-cert-file <PRIMARY_GRPC_CERT_FILE>

  • Path to the primary gRPC TLS certificate file.

• --primary-grpc-key-file <PRIMARY_GRPC_KEY_FILE>

  • Path to the primary gRPC TLS key file.

• --primary-grpc-ca-cert-file <PRIMARY_GRPC_CA_CERT_FILE>

  • Path to the primary gRPC TLS CA certificate file.

• --no-welcome

  • Disable the welcome message.

• --enable-bottomless-replication

  • Enable bottomless replication.
  • Environment Variable: SQLD_ENABLE_BOTTOMLESS_REPLICATION

• --idle-shutdown-timeout-s <IDLE_SHUTDOWN_TIMEOUT_S>

  • Duration (in seconds) after which the server shuts down if no requests are received. By default, the server does not shut down when idle.
  • Environment Variable: SQLD_IDLE_SHUTDOWN_TIMEOUT_S

• --initial-idle-shutdown-timeout-s <INITIAL_IDLE_SHUTDOWN_TIMEOUT_S>

  • Initial idle shutdown timeout (in seconds), used once after the server starts. If the server does not receive requests, it shuts down or uses --idle-shutdown-timeout-s moving forward.
  • Environment Variable: SQLD_INITIAL_IDLE_SHUTDOWN_TIMEOUT_S

• --max-log-size <MAX_LOG_SIZE>

  • Maximum allowed size for the replication log (in MB).
  • Default: 200MB
  • Environment Variable: SQLD_MAX_LOG_SIZE

• --max-log-duration <MAX_LOG_DURATION>

  • Maximum duration before the replication log is compacted (in seconds). The log is compacted only if it grows above the --max-log-size limit.
  • Environment Variable: SQLD_MAX_LOG_DURATION

• --heartbeat-url <HEARTBEAT_URL>

  • URL to send a server heartbeat POST request to. By default, no heartbeat is sent.
  • Environment Variable: SQLD_HEARTBEAT_URL

• --heartbeat-auth <HEARTBEAT_AUTH>

  • HTTP "Authorization" header to include in a server heartbeat POST request. By default, no heartbeat is sent.
  • Environment Variable: SQLD_HEARTBEAT_AUTH

• --heartbeat-period-s <HEARTBEAT_PERIOD_S>

  • Heartbeat period (in seconds).
  • Default: 30 seconds
  • Environment Variable: SQLD_HEARTBEAT_PERIOD_S

• --soft-heap-limit-mb <SOFT_HEAP_LIMIT_MB>

  • Soft heap size limit in mebibytes. libSQL tries not to exceed this limit with memory usage.
  • Environment Variable: SQLD_SOFT_HEAP_LIMIT_MB

• --hard-heap-limit-mb <HARD_HEAP_LIMIT_MB>

  • Hard heap size limit in mebibytes. libSQL stops with an SQLITE_NOMEM error if this limit is exceeded.
  • Environment Variable: SQLD_HARD_HEAP_LIMIT_MB

• --max-response-size <MAX_RESPONSE_SIZE>

  • Maximum size for a single response (e.g., 5KB, 10MB).
  • Default: 10MB
  • Environment Variable: SQLD_MAX_RESPONSE_SIZE

• --max-total-response-size <MAX_TOTAL_RESPONSE_SIZE>

  • Maximum size for all responses combined (e.g., 5KB, 10MB).
  • Default: 32MB
  • Environment Variable: SQLD_MAX_TOTAL_RESPONSE_SIZE

• --snapshot-exec <SNAPSHOT_EXEC>

  • Command to execute when a snapshot file is generated.
  • Environment Variable: SQLD_SNAPSHOT_EXEC

• --checkpoint-interval-s <CHECKPOINT_INTERVAL_S>

  • Interval (in seconds) at which WAL checkpoint is called.
  • Default: 1 hour
  • Environment Variable: SQLD_CHECKPOINT_INTERVAL_S

• --disable-default-namespace

  • Disable fallback to the default namespace default when a namespace cannot be determined.

• --enable-namespaces

  • Enable namespace features. Namespaces are disabled by default, and all requests target the default namespace.

• --snapshot-at-shutdown

  • Enable snapshot at shutdown.

• --max-active-namespaces <MAX_ACTIVE_NAMESPACES>

  • Maximum number of active namespaces kept in memory.
  • Default: 100
  • Environment Variable: SQLD_MAX_ACTIVE_NAMESPACES

• --backup-meta-store

  • Enable backup for the metadata store.
  • Environment Variable: SQLD_BACKUP_META_STORE

• --meta-store-access-key-id <META_STORE_ACCESS_KEY_ID>

  • S3 access key ID for the metadata store backup.
  • Environment Variable: SQLD_META_STORE_ACCESS_KEY_ID

• --meta-store-secret-access-key <META_STORE_SECRET_ACCESS_KEY>

  • S3 secret access key for the metadata store backup.
  • Environment Variable: SQLD_META_STORE_SECRET_ACCESS

• --meta-store-region <META_STORE_REGION>

  • S3 region for the metadata store backup.
  • Environment Variable: SQLD_META_STORE_REGION

• --meta-store-backup-id <META_STORE_BACKUP_ID>

  • ID for the metadata store backup.
  • Environment Variable: SQLD_META_STORE_BACKUP_ID

• --meta-store-bucket-name <META_STORE_BUCKET_NAME>

  • S3 bucket name for the metadata store backup.
  • **Environment

Variable**: SQLD_META_STORE_BUCKET_NAME

• --meta-store-backup-interval-s <META_STORE_BACKUP_INTERVAL_S>

  • Interval for performing backups of the metadata store.
  • Environment Variable: SQLD_META_STORE_BACKUP_INTERVAL_S

• --meta-store-bucket-endpoint <META_STORE_BUCKET_ENDPOINT>

  • S3 endpoint for the metadata store backups.
  • Environment Variable: SQLD_META_STORE_BUCKET_ENDPOINT

• --encryption-key <ENCRYPTION_KEY>

  • Encryption key for encryption at rest.
  • Environment Variable: SQLD_ENCRYPTION_KEY

• --max-concurrent-connections <MAX_CONCURRENT_CONNECTIONS>

  • Maximum number of concurrent connections.
  • Default: 128
  • Environment Variable: SQLD_MAX_CONCURRENT_CONNECTIONS

• --max-concurrent-requests <MAX_CONCURRENT_REQUESTS>

  • Maximum number of concurrent requests.
  • Default: 128
  • Environment Variable: SQLD_MAX_CONCURRENT_REQUESTS

• --allow-metastore-recovery

  • Allow metadata store to recover configuration from the filesystem from an older version if the metadata store is empty on startup.
  • Environment Variable: SQLD_ALLOW_METASTORE_RECOVERY

• --shutdown-timeout <SHUTDOWN_TIMEOUT>

  • Shutdown timeout duration (in seconds).
  • Default: 30 seconds
  • Environment Variable: SQLD_SHUTDOWN_TIMEOUT

• -h, --help

  • Print help message. Use --help for more details.

• -V, --version

  • Print version information.