compose-anything/src/libsql/README.md

libSQL Server

中文说明

Introduction

libSQL is an open-source fork of SQLite optimized for edge deployments and serverless architectures. It offers SQLite compatibility with additional features like primary-replica replication, built-in HTTP/WebSocket API (Hrana protocol), and is designed for distributed database scenarios.

Key Features:

• 100% SQLite compatible
• Primary-replica replication support
• Built-in HTTP and WebSocket APIs
• Edge-optimized for low latency
• Open-source and extensible

Official Resources:

• GitHub: https://github.com/tursodatabase/libsql
• Documentation: https://github.com/tursodatabase/libsql/tree/main/docs
• Docker Hub: https://github.com/tursodatabase/libsql/pkgs/container/libsql-server

Quick Start

1. Basic Usage (Primary Instance)

cd src/libsql
docker compose up -d

The database will be available at:

• HTTP/Hrana API: http://localhost:8080
• gRPC (for replication): localhost:5001

2. With Replica Instance

To enable replication, start with the replica profile:

docker compose --profile replica up -d

This will start:

• Primary instance on ports 8080 (HTTP) and 5001 (gRPC)
• Replica instance on ports 8081 (HTTP) and 5002 (gRPC)

3. Accessing the Database

You can connect to libSQL using:

Via HTTP API:

# Create a table
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"statements": ["CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"]}'

# Insert data
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"statements": ["INSERT INTO users (name) VALUES ('\''Alice'\'')"]}'

# Query data
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"statements": ["SELECT * FROM users"]}'

Via libSQL CLI (if installed):

libsql client http://localhost:8080

Configuration

Environment Variables

Key environment variables (see .env.example for full list):

Variable	Default	Description
LIBSQL_VERSION	latest	libSQL server version
LIBSQL_HTTP_PORT_OVERRIDE	8080	HTTP API port
LIBSQL_GRPC_PORT_OVERRIDE	5001	gRPC port for replication
LIBSQL_NODE	primary	Node type: primary, replica, or standalone
LIBSQL_DB_PATH	iku.db	Database file name
LIBSQL_PRIMARY_URL	http://libsql:5001	Primary URL for replica nodes
TZ	UTC	Timezone

Authentication (Optional)

To enable authentication, uncomment and configure these variables:

HTTP Basic Auth:

# Generate base64 encoded credentials
echo -n "username:password" | base64
# Result: dXNlcm5hbWU6cGFzc3dvcmQ=

# Set in .env
LIBSQL_HTTP_AUTH=basic:dXNlcm5hbWU6cGFzc3dvcmQ=

JWT Authentication:

# Option 1: Using key file
LIBSQL_AUTH_JWT_KEY_FILE=/path/to/jwt-key.pem

# Option 2: Using key directly
LIBSQL_AUTH_JWT_KEY=your-jwt-key-here

Platform Support

• x86-64: Use LIBSQL_PLATFORM=linux/amd64 (default)
• ARM64 (Apple Silicon):
  • Use LIBSQL_VERSION=latest-arm for native ARM images
  • Or use LIBSQL_PLATFORM=linux/amd64 to run via Rosetta

Data Persistence

Database files are stored in a Docker named volume:

• Volume: libsql_data
• Container path: /var/lib/sqld

To backup your database:

# Copy database file from container
docker compose cp libsql:/var/lib/sqld/iku.db ./backup.db

Resource Limits

Default resource allocations per instance:

• CPU: 0.5-1.0 cores
• Memory: 256M-512M

Adjust in .env file:

LIBSQL_CPU_LIMIT=2.0
LIBSQL_MEMORY_LIMIT=1G

Replication Architecture

libSQL supports primary-replica replication:

1. Primary Instance: Accepts reads and writes
2. Replica Instance(s): Read-only, replicates from primary via gRPC

To add a replica:

# Start with replica profile
docker compose --profile replica up -d

Replicas connect to the primary using LIBSQL_PRIMARY_URL and stay synchronized automatically.

Common Operations

Check Server Health

curl http://localhost:8080/health

View Logs

docker compose logs -f libsql

Restart Service

docker compose restart libsql

Stop and Remove

docker compose down
# To remove volumes as well
docker compose down -v

Troubleshooting

Connection Refused

• Verify the service is running: docker compose ps
• Check logs: docker compose logs libsql
• Ensure ports are not in use: netstat -an | grep 8080

Replica Not Syncing

• Verify LIBSQL_PRIMARY_URL is correct
• Check primary instance is healthy and accessible
• Review replica logs for connection errors

Performance Issues

• Increase resource limits in .env
• Consider using SSD for volume storage
• Enable query logging for optimization

Security Notes

• Default Setup: No authentication enabled - suitable for development only
• Production: Always enable authentication (HTTP Basic or JWT)
• Network: Consider using Docker networks or reverse proxy for external access
• Secrets: Never commit .env with credentials to version control

License

libSQL is licensed under the MIT License. See the official repository for details.