phillarmonic/syncopatedb repository overview

⁠SyncopateDB

GitHub Repo⁠

SyncopateDB is a flexible, lightweight NoSQL database with advanced query capabilities, optimized for SSD performance. It provides a comprehensive REST API (and in the future gRPC connectors) for data storage and retrieval.

⁠Key Features

• Schema Definition: Define entity types with field definitions, validation, and indexing
• Advanced Querying: Filter, sort, paginate, and join data with a powerful query API
• Multiple ID Strategies: Auto-increment, UUID, CUID, or custom IDs
• Rich Data Types: String, text, integer, float, boolean, datetime, JSON
• Fuzzy Search: Find data using fuzzy matching algorithms
• Joins and Relations: Link related data between entity types
• Persistence: Store data on disk with WAL (Write-Ahead Logging) and snapshots
• Schema Evolution: Update entity type definitions with compatibility checks
• Memory Efficiency: Strategic caching and optimizations for performance

⁠Architecture

Currently, SyncopateDB is architected in a monolithic mindset. Only a single instance of SyncopateDB (and its multihthreaded goroutines) can access the database at once.

In the future version 1.x, we'll migrate to a clustered architecture, for smoother horizontally scaling.

The data volume is located at /data in the container

⁠Quick Start

docker run -d --name syncopatedb -p 8080:8080 -v syncopate-data:/data phillarmonic/syncopatedb

This will:

• Start SyncopateDB in detached mode
• Name the container "syncopatedb"
• Map port 8080 from the container to port 8080 on your host
• Create a Docker volume named "syncopate-data" for persistent storage

⁠Configuration Options

You can configure SyncopateDB using environment variables:

docker run -d --name syncopatedb \
  -p 8080:8080 \
  -v syncopate-data:/data \
  -e PORT=8080 \
  -e DEBUG=false \
  -e LOG_LEVEL=info \
  -e ENABLE_WAL=true \
  -e ENABLE_ZSTD=true \
  -e COLORIZED_LOGS=false \
  phillarmonic/syncopatedb

⁠Available Environment Variables

• PORT: Server port (default: 8080)
• DEBUG: Enable verbose debug mode (default: false)
• LOG_LEVEL: Logging level (debug, info, warn, error)
• ENABLE_WAL: Enable Write-Ahead Logging (default: true)
• ENABLE_ZSTD: Enable ZSTD compression (default: true)
• ENABLE_HTTP_ZSTD: Enable HTTP compression (default: false)
• COLORIZED_LOGS: Enable colorized logging (default: false)

⁠Docker Compose Example

services:
  syncopatedb:
    image: phillarmonic/syncopatedb:latest
    container_name: syncopatedb
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - syncopate-data:/data
    environment:
      - PORT=8080
      - LOG_LEVEL=info
      - ENABLE_WAL=true
      - ENABLE_ZSTD=true
      - COLORIZED_LOGS=false
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  syncopate-data:

⁠Security Considerations

The SyncopateDB Docker image:

• Runs as a non-root user (syncopate)
• Has a minimal footprint using Alpine Linux
• Contains only the necessary dependencies

⁠API Examples

⁠Create an Entity Type

curl -X POST http://localhost:8080/api/v1/entity-types \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product",
    "idGenerator": "auto_increment",
    "fields": [
      {
        "name": "name",
        "type": "string",
        "indexed": true,
        "required": true
      },
      {
        "name": "price",
        "type": "float",
        "indexed": true,
        "required": true
      }
    ]
  }'

⁠Create an Entity

curl -X POST http://localhost:8080/api/v1/entities/Product \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "name": "Keyboard",
      "price": 59.99
    }
  }'

⁠Query with Filters

curl -X POST http://localhost:8080/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "Product",
    "filters": [
      {
        "field": "price",
        "operator": "lte",
        "value": 100.0
      }
    ],
    "orderBy": "name",
    "limit": 10,
    "offset": 0
  }'

See the complete documentation⁠ for more examples and details.

⁠Versions

• latest: The most recent stable release
• 0.7.x: Current stable version (feature-complete)
• dev: Development version (unstable)

⁠Made with Go

The system is built in Go (requires 1.23+) and uses Badger⁠ as its storage backend, providing excellent performance on SSDs. The database exposes a RESTful API for all operations.

⁠License

MIT License