Skip to content

Instantly share code, notes, and snippets.

@darkterminal

darkterminal/.env-example

Last active July 25, 2024 17:15
Show Gist options
  • Save darkterminal/8b9503b95f35b691a74dd73394675b3a to your computer and use it in GitHub Desktop.
Save darkterminal/8b9503b95f35b691a74dd73394675b3a to your computer and use it in GitHub Desktop.
Download ZIP
libSQL Daemon
Raw
.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
Raw
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment