{"id":42684829,"url":"https://github.com/codepr/raft-c","last_synced_at":"2026-01-29T12:08:25.790Z","repository":{"id":274218141,"uuid":"921962786","full_name":"codepr/raft-c","owner":"codepr","description":"Fun-driven Raft-based distributed time series database, featuring sharding with consistent hashing, an SQL-like query language","archived":false,"fork":false,"pushed_at":"2025-10-21T03:09:03.000Z","size":693,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-21T04:19:39.607Z","etag":null,"topics":["c","distributed-systems","network-programming","raft","sql-query","time-series","write-ahead-log"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codepr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-25T00:46:09.000Z","updated_at":"2025-10-21T03:09:06.000Z","dependencies_parsed_at":"2025-02-25T01:19:56.668Z","dependency_job_id":"0bdf65af-483b-438b-b828-fc63ae327378","html_url":"https://github.com/codepr/raft-c","commit_stats":null,"previous_names":["codepr/raft-c"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/codepr/raft-c","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codepr%2Fraft-c","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codepr%2Fraft-c/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codepr%2Fraft-c/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codepr%2Fraft-c/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codepr","download_url":"https://codeload.github.com/codepr/raft-c/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codepr%2Fraft-c/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28877131,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T10:31:27.438Z","status":"ssl_error","status_checked_at":"2026-01-29T10:31:01.017Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","distributed-systems","network-programming","raft","sql-query","time-series","write-ahead-log"],"created_at":"2026-01-29T12:08:20.644Z","updated_at":"2026-01-29T12:08:25.779Z","avatar_url":"https://github.com/codepr.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"Raft-C - Distributed Time Series Database\n==========================================\n\nA Raft-based distributed time series database written in C, featuring\nconsistent hashing for sharding, a SQL-like query language, and minimal\ndependencies.\n\nThis project explores distributed systems concepts with a focus on simplicity\nand educational value. It implements a complete distributed time series\ndatabase with leader election, log replication, and automatic sharding.\n\n**NOT FOR PRODUCTION USE** It's not a mature project and some parts are\nyet to be completed, if you intend to test it out you're likely gonna\nincur in some bugs and missing features.\n\n## Features\n\nThe software evolves incrementally with the following features:\n\n- **Raft Consensus** - [Raft algorithm](https://raft.github.io/raft.pdf) for leader election and log replication\n    - UDP-based transport for efficient communication\n    - Pluggable serialization (binary by default)\n    - Write-Ahead Log (WAL) for durability\n- **Consistent Hashing** - [Consistent hashing](https://highscalability.com/consistent-hashing-algorithm/) for sharding keys across nodes\n    - Pluggable TCP/UDP transport protocol\n    - Pluggable serialization (binary by default)\n    - Mesh topology with all nodes connected\n- **Time Series Query Language** - SQL-like query language for time series operations\n    - Database and time series management\n    - Flexible timestamp formats (Unix epochs, ISO dates, relative times)\n    - Aggregation functions (avg, min, max, latest)\n    - Time range queries with sampling intervals\n- **Storage Backend** - Custom storage implementation (WIP)\n- **Configuration** - Static configuration files with flag overrides (WIP)\n\n## Architecture\n\nThe cluster is organized as **shards with replicas**:\n\n- **Shards** - Distribute data across the cluster using consistent hashing. Each\n  shard is responsible for a portion of the key space.\n\n- **Replicas** - Each shard has multiple replicas that use Raft consensus\n  to maintain consistency. One replica is the leader, others are followers.\n\nExample topology (3 shards, 2 replicas each):\n```\nShard 0: node-0 (leader) + raft-0-0, raft-0-1 (replicas)\nShard 1: node-1 (leader) + raft-1-0, raft-1-1 (replicas)\nShard 2: node-2 (leader) + raft-2-0, raft-2-1 (replicas)\n```\n\n## Building the Project\n\n### Prerequisites\n\n- `gcc` or `clang`\n- `make`\n\n### Build Commands\n\n```bash\n# Build everything (server, client, tests)\nmake\n\n# Build specific targets\nmake raft-c        # Server binary\nmake raft-cli      # Client CLI\nmake raft-c-tests  # Test suite\n\n# Clean build artifacts\nmake clean\n```\n\n## Quick Start\n\n### 1. Start a Cluster\n\nUse the convenience script to start a 3-shard cluster with 2 replicas each:\n\n```bash\n./start-cluster.sh\n```\n\nOr start nodes individually:\n\n```bash\n# Shard 0\n./raft-c -c conf/node-0.conf\n./raft-c -c conf/raft-0-0.conf\n./raft-c -c conf/raft-0-1.conf\n\n# Shard 1\n./raft-c -c conf/node-1.conf\n./raft-c -c conf/raft-1-0.conf\n./raft-c -c conf/raft-1-1.conf\n\n# Shard 2\n./raft-c -c conf/node-2.conf\n./raft-c -c conf/raft-2-0.conf\n./raft-c -c conf/raft-2-1.conf\n```\n\nLogs are written to `logs/` directory.\n\n### 2. Connect with the CLI Client\n\n```bash\n./raft-cli -h 127.0.0.1 -p 27778\n```\n\n### 3. Create and Query Time Series\n\n```sql\n-- Create a database\nCREATEDB metrics\n\n-- Set active database\nUSE metrics\n\n-- Create a time series\nCREATE cpu_usage\n\n-- Insert data points\nINSERT INTO cpu_usage VALUES (now(), 78.5)\nINSERT INTO cpu_usage VALUES ('2025-01-15 12:30:00', 82.3)\n\n-- Insert multiple points\nINSERT INTO cpu_usage VALUES\n    (1643673600, 78.5),\n    (1643673660, 80.2),\n    (1643673720, 75.1)\n\n-- Query all values\nSELECT value FROM cpu_usage\n\n-- Query with time range\nSELECT value FROM cpu_usage\nBETWEEN '2025-01-01' AND '2025-01-31'\n\n-- Aggregation queries\nSELECT avg(value) FROM cpu_usage\nBETWEEN '2025-01-01' AND '2025-01-31'\n\nSELECT min(value), max(value) FROM cpu_usage\n\n-- Downsampling with intervals\nSELECT avg(value) FROM cpu_usage\nBETWEEN '2025-01-01' AND '2025-01-31'\nSAMPLE BY 1d\n\n-- Limit results\nSELECT value FROM cpu_usage LIMIT 100\nSELECT latest(value) FROM cpu_usage\n\n-- Meta commands\n.databases\n.timeseries\n```\n\n## Query Language Reference\n\n### Supported Timestamp Formats\n\n- **Unix epoch**: `1643673600`\n- **ISO date**: `'2025-01-15 12:30:00'`\n- **Relative time**: `now()`, `now() - 24h`, `now() - 7d`\n- **Auto timestamp**: Omit timestamp to use current time\n\n### Aggregate Functions\n\n- `avg(value)` - Average value\n- `min(value)` - Minimum value\n- `max(value)` - Maximum value\n- `latest(value)` - Most recent value\n\n### Time Intervals\n\n- `ms` - Milliseconds\n- `s` - Seconds\n- `m` - Minutes\n- `h` - Hours\n- `d` - Days\n\n### Commands\n\n- `CREATEDB \u003cname\u003e` - Create a new database\n- `USE \u003cname\u003e` - Set active database\n- `CREATE \u003ctimeseries\u003e` - Create a time series\n- `INSERT INTO \u003ctimeseries\u003e VALUES (timestamp, value)` - Insert data\n- `SELECT ... FROM \u003ctimeseries\u003e` - Query data\n- `DELETE \u003ctimeseries\u003e` - Delete a time series\n\n## Configuration\n\nConfiguration files define node behavior and cluster topology.\n\n### Shard Node Configuration\n\n```conf\n# Cluster config\nid                  0\ntype                shard\nhost                127.0.0.1:27778\nshard_leaders       127.0.0.1:7778 127.0.0.1:7878 127.0.0.1:7978\n\n# Raft replicas for this shard\nraft_replicas       127.0.0.1:8778 127.0.0.1:8779 127.0.0.1:7778\nraft_heartbeat_ms   150\n```\n\n### Replica Node Configuration\n\nSimilar structure but with `type replica` and appropriate ports.\n\n## Testing\n\n```bash\n# Build and run tests\nmake raft-c-tests\n./raft-c-tests\n```\n\nTest coverage includes (for now):\n- Encoding/decoding (binary serialization)\n- Statement parsing (SQL query parser)\n- Time series operations (aggregations, sampling)\n\n## Project Goals\n\nThis is a **didactic project** focused on:\n\n- Exploring distributed systems concepts\n- Keeping implementation simple and dependency-free\n- Prioritizing code clarity over performance\n- Using straightforward approaches (e.g., `select` for I/O multiplexing)\n\nIt is **not intended for production use**. Features are added incrementally as learning opportunities.\n\n## Stopping the Cluster\n\n```bash\npkill -f raft-c\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodepr%2Fraft-c","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodepr%2Fraft-c","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodepr%2Fraft-c/lists"}