alexsun/compose-anything
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add libsql

Browse Source
This commit is contained in:
Sun-ZhenXing
2025-12-29 18:05:34 +08:00
parent 4c7b3afc10
commit 953bb146ba
18 changed files with 1128 additions and 502 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
src/libsql/.env.example Normal file
View File

@@ -0,0 +1,71 @@
# Global registry prefix (optional, for custom registry mirrors)
# GLOBAL_REGISTRY=
# libSQL Server version
LIBSQL_VERSION=latest
# Platform architecture (linux/amd64 or linux/arm64)
# Note: For ARM64 (Apple Silicon), use latest-arm tag or run via Rosetta with linux/amd64
LIBSQL_PLATFORM=linux/amd64
# Timezone
TZ=UTC
# ==================== Port Configuration ====================
# HTTP/Hrana API port (client connections)
LIBSQL_HTTP_PORT_OVERRIDE=8080
# gRPC port (for replication between primary and replicas)
LIBSQL_GRPC_PORT_OVERRIDE=5001
# Replica HTTP port (only used when replica profile is enabled)
LIBSQL_REPLICA_HTTP_PORT_OVERRIDE=8081
# Replica gRPC port (only used when replica profile is enabled)
LIBSQL_REPLICA_GRPC_PORT_OVERRIDE=5002
# ==================== Node Configuration ====================
# Node type: primary, replica, or standalone
# - primary: Main database instance, accepts writes
# - replica: Read-only replica, replicates from primary
# - standalone: Single instance without replication
LIBSQL_NODE=primary
# Database file name (stored in /var/lib/sqld by default)
LIBSQL_DB_PATH=iku.db
# HTTP listen address (internal, usually no need to change)
LIBSQL_HTTP_LISTEN_ADDR=0.0.0.0:8080
# gRPC listen address (internal, usually no need to change)
LIBSQL_GRPC_LISTEN_ADDR=0.0.0.0:5001
# ==================== Replication Configuration ====================
# Primary URL for replica instances (format: http://host:port or https://host:port)
# Only required when LIBSQL_NODE=replica
# Example for Docker Compose: http://libsql:5001
LIBSQL_PRIMARY_URL=http://libsql:5001
# ==================== Authentication (Optional) ====================
# HTTP basic authentication (format: basic:base64(username:password))
# Example: basic:dXNlcjpwYXNz (for user:pass)
# LIBSQL_HTTP_AUTH=
# Path to JWT key file for authentication (mounted into container)
# LIBSQL_AUTH_JWT_KEY_FILE=
# JWT key directly as environment variable (alternative to file)
# LIBSQL_AUTH_JWT_KEY=
# ==================== Resource Limits ====================
# Primary instance resource limits
LIBSQL_CPU_LIMIT=1.0
LIBSQL_MEMORY_LIMIT=512M
LIBSQL_CPU_RESERVATION=0.5
LIBSQL_MEMORY_RESERVATION=256M
# Replica instance resource limits (when replica profile is enabled)
LIBSQL_REPLICA_CPU_LIMIT=1.0
LIBSQL_REPLICA_MEMORY_LIMIT=512M
LIBSQL_REPLICA_CPU_RESERVATION=0.5
LIBSQL_REPLICA_MEMORY_RESERVATION=256M

228
src/libsql/README.md Normal file
View File

@@ -0,0 +1,228 @@
# libSQL Server
[中文说明](README.zh.md)
## 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)
```bash
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:
```bash
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:**
```bash
# 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):**
```bash
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:**
```bash
# Generate base64 encoded credentials
echo -n "username:password" | base64
# Result: dXNlcm5hbWU6cGFzc3dvcmQ=
# Set in .env
LIBSQL_HTTP_AUTH=basic:dXNlcm5hbWU6cGFzc3dvcmQ=
```
**JWT Authentication:**
```bash
# 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:
```bash
# 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:
```bash
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:
```bash
# 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
```bash
curl http://localhost:8080/health
```
### View Logs
```bash
docker compose logs -f libsql
```
### Restart Service
```bash
docker compose restart libsql
```
### Stop and Remove
```bash
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](https://github.com/tursodatabase/libsql) for details.

228
src/libsql/README.zh.md Normal file
View File

@@ -0,0 +1,228 @@
# libSQL Server
[English Documentation](README.md)
## 简介
libSQL 是 SQLite 的开源分支，针对边缘部署和无服务器架构进行了优化。它提供与 SQLite 的完全兼容性，同时增加了主从复制、内置 HTTP/WebSocket API（Hrana 协议）等功能，专为分布式数据库场景设计。
**核心特性：**
- 100% SQLite 兼容
- 支持主从复制
- 内置 HTTP 和 WebSocket API
- 边缘优化，低延迟
- 开源可扩展
**官方资源：**
- GitHub：<https://github.com/tursodatabase/libsql>
- 文档：<https://github.com/tursodatabase/libsql/tree/main/docs>
- Docker Hub：<https://github.com/tursodatabase/libsql/pkgs/container/libsql-server>
## 快速开始
### 1. 基本用法（主实例）
```bash
cd src/libsql
docker compose up -d
```
数据库将在以下端口可用：
- HTTP/Hrana API：<http://localhost:8080>
- gRPC（用于复制）：localhost:5001
### 2. 启用副本实例
要启用复制，使用 `replica` profile 启动：
```bash
docker compose --profile replica up -d
```
这将启动：
- 主实例，端口 8080（HTTP）和 5001（gRPC）
- 副本实例，端口 8081（HTTP）和 5002（gRPC）
### 3. 访问数据库
可以通过以下方式连接到 libSQL：
**通过 HTTP API：**
```bash
# 创建表
curl -X POST http://localhost:8080 \
-H "Content-Type: application/json" \
-d '{"statements": ["CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"]}'
# 插入数据
curl -X POST http://localhost:8080 \
-H "Content-Type: application/json" \
-d '{"statements": ["INSERT INTO users (name) VALUES ('\''Alice'\'')"]}'
# 查询数据
curl -X POST http://localhost:8080 \
-H "Content-Type: application/json" \
-d '{"statements": ["SELECT * FROM users"]}'
```
**通过 libSQL CLI（如已安装）：**
```bash
libsql client http://localhost:8080
```
## 配置说明
### 环境变量
主要环境变量（完整列表请参见 `.env.example`）：
| 变量名 | 默认值 | 说明 |
| --------------------------- | -------------------- | ---------------------------------------------- |
| `LIBSQL_VERSION` | `latest` | libSQL 服务器版本 |
| `LIBSQL_HTTP_PORT_OVERRIDE` | `8080` | HTTP API 端口 |
| `LIBSQL_GRPC_PORT_OVERRIDE` | `5001` | gRPC 复制端口 |
| `LIBSQL_NODE` | `primary` | 节点类型：`primary`、`replica` 或 `standalone` |
| `LIBSQL_DB_PATH` | `iku.db` | 数据库文件名 |
| `LIBSQL_PRIMARY_URL` | `http://libsql:5001` | 副本节点的主节点 URL |
| `TZ` | `UTC` | 时区 |
### 身份验证（可选）
要启用身份验证，请取消注释并配置以下变量：
**HTTP 基本认证：**
```bash
# 生成 base64 编码的凭据
echo -n "username:password" | base64
# 结果：dXNlcm5hbWU6cGFzc3dvcmQ=
# 在 .env 中设置
LIBSQL_HTTP_AUTH=basic:dXNlcm5hbWU6cGFzc3dvcmQ=
```
**JWT 认证：**
```bash
# 方式 1：使用密钥文件
LIBSQL_AUTH_JWT_KEY_FILE=/path/to/jwt-key.pem
# 方式 2：直接使用密钥
LIBSQL_AUTH_JWT_KEY=your-jwt-key-here
```
### 平台支持
- **x86-64：** 使用 `LIBSQL_PLATFORM=linux/amd64`（默认）
- **ARM64（Apple Silicon）：**
- 使用 `LIBSQL_VERSION=latest-arm` 获取原生 ARM 镜像
- 或使用 `LIBSQL_PLATFORM=linux/amd64` 通过 Rosetta 运行
## 数据持久化
数据库文件存储在 Docker 命名卷中：
- 卷名：`libsql_data`
- 容器路径：`/var/lib/sqld`
备份数据库：
```bash
# 从容器复制数据库文件
docker compose cp libsql:/var/lib/sqld/iku.db ./backup.db
```
## 资源限制
每个实例的默认资源分配：
- CPU：0.5-1.0 核心
- 内存：256M-512M
在 `.env` 文件中调整：
```bash
LIBSQL_CPU_LIMIT=2.0
LIBSQL_MEMORY_LIMIT=1G
```
## 复制架构
libSQL 支持主从复制：
1. **主实例：** 接受读写操作
2. **副本实例：** 只读，通过 gRPC 从主实例复制
添加副本：
```bash
# 使用 replica profile 启动
docker compose --profile replica up -d
```
副本使用 `LIBSQL_PRIMARY_URL` 连接到主实例，并自动保持同步。
## 常用操作
### 检查服务器健康状态
```bash
curl http://localhost:8080/health
```
### 查看日志
```bash
docker compose logs -f libsql
```
### 重启服务
```bash
docker compose restart libsql
```
### 停止并删除
```bash
docker compose down
# 同时删除卷
docker compose down -v
```
## 故障排查
### 连接被拒绝
- 验证服务正在运行：`docker compose ps`
- 检查日志：`docker compose logs libsql`
- 确保端口未被占用：`netstat -an | grep 8080`
### 副本未同步
- 验证 `LIBSQL_PRIMARY_URL` 是否正确
- 检查主实例是否健康且可访问
- 查看副本日志以查找连接错误
### 性能问题
- 在 `.env` 中增加资源限制
- 考虑为卷存储使用 SSD
- 启用查询日志以进行优化
## 安全注意事项
- **默认设置：** 未启用身份验证 - 仅适用于开发环境
- **生产环境：** 始终启用身份验证（HTTP Basic 或 JWT）
- **网络：** 考虑使用 Docker 网络或反向代理进行外部访问
- **密钥：** 切勿将包含凭据的 `.env` 提交到版本控制
## 许可证
libSQL 采用 MIT 许可证。详情请参见[官方仓库](https://github.com/tursodatabase/libsql)。

87
src/libsql/docker-compose.yaml Normal file
View File

@@ -0,0 +1,87 @@
# Docker Compose configuration for libSQL Server
# libSQL is an open-source fork of SQLite optimized for edge deployments
# Supports primary-replica replication and serverless architectures
x-defaults: &defaults
restart: unless-stopped
logging:
driver: json-file
options:
max-size: 100m
max-file: "3"
services:
libsql:
<<: *defaults
image: ${GHCR_IO_REGISTRY:-ghcr.io}/tursodatabase/libsql-server:${LIBSQL_VERSION:-latest}
platform: ${LIBSQL_PLATFORM:-linux/amd64}
ports:
- "${LIBSQL_HTTP_PORT_OVERRIDE:-8080}:8080" # HTTP/Hrana API port
- "${LIBSQL_GRPC_PORT_OVERRIDE:-5001}:5001" # gRPC port for replication
volumes:
- libsql_data:/var/lib/sqld
environment:
- TZ=${TZ:-UTC}
- SQLD_NODE=${LIBSQL_NODE:-primary}
- SQLD_DB_PATH=${LIBSQL_DB_PATH:-iku.db}
- SQLD_HTTP_LISTEN_ADDR=${LIBSQL_HTTP_LISTEN_ADDR:-0.0.0.0:8080}
- SQLD_GRPC_LISTEN_ADDR=${LIBSQL_GRPC_LISTEN_ADDR:-0.0.0.0:5001}
# Authentication (optional, uncomment to enable)
# - SQLD_HTTP_AUTH=${LIBSQL_HTTP_AUTH:-}
# - SQLD_AUTH_JWT_KEY_FILE=${LIBSQL_AUTH_JWT_KEY_FILE:-}
# - SQLD_AUTH_JWT_KEY=${LIBSQL_AUTH_JWT_KEY:-}
healthcheck:
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
deploy:
resources:
limits:
cpus: ${LIBSQL_CPU_LIMIT:-1.0}
memory: ${LIBSQL_MEMORY_LIMIT:-512M}
reservations:
cpus: ${LIBSQL_CPU_RESERVATION:-0.5}
memory: ${LIBSQL_MEMORY_RESERVATION:-256M}
# Replica instance (optional, use with profile)
libsql-replica:
<<: *defaults
image: ${GHCR_IO_REGISTRY:-ghcr.io}/tursodatabase/libsql-server:${LIBSQL_VERSION:-latest}
platform: ${LIBSQL_PLATFORM:-linux/amd64}
profiles:
- replica
ports:
- "${LIBSQL_REPLICA_HTTP_PORT_OVERRIDE:-8081}:8080"
- "${LIBSQL_REPLICA_GRPC_PORT_OVERRIDE:-5002}:5001"
volumes:
- libsql_replica_data:/var/lib/sqld
environment:
- TZ=${TZ:-UTC}
- SQLD_NODE=replica
- SQLD_PRIMARY_URL=${LIBSQL_PRIMARY_URL:-http://libsql:5001}
- SQLD_DB_PATH=${LIBSQL_DB_PATH:-iku.db}
- SQLD_HTTP_LISTEN_ADDR=${LIBSQL_HTTP_LISTEN_ADDR:-0.0.0.0:8080}
- SQLD_GRPC_LISTEN_ADDR=${LIBSQL_GRPC_LISTEN_ADDR:-0.0.0.0:5001}
healthcheck:
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
depends_on:
libsql:
condition: service_healthy
deploy:
resources:
limits:
cpus: ${LIBSQL_REPLICA_CPU_LIMIT:-1.0}
memory: ${LIBSQL_REPLICA_MEMORY_LIMIT:-512M}
reservations:
cpus: ${LIBSQL_REPLICA_CPU_RESERVATION:-0.5}
memory: ${LIBSQL_REPLICA_MEMORY_RESERVATION:-256M}
volumes:
libsql_data:
libsql_replica_data: