{"id":25903877,"url":"https://github.com/goatplatform/goatdb","last_synced_at":"2025-04-08T13:02:36.425Z","repository":{"id":266274938,"uuid":"897888926","full_name":"goatplatform/goatdb","owner":"goatplatform","description":"Embedded, distributed, document database for servers and the browser","archived":false,"fork":false,"pushed_at":"2025-03-30T15:32:06.000Z","size":1410,"stargazers_count":505,"open_issues_count":12,"forks_count":12,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-01T12:04:08.959Z","etag":null,"topics":["backend","browser","database","deno","devtools","edge","frontend","local-first","low-code","react","typescript"],"latest_commit_sha":null,"homepage":"https://goatdb.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goatplatform.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"goatplatform","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2024-12-03T12:20:41.000Z","updated_at":"2025-03-31T20:45:45.000Z","dependencies_parsed_at":"2024-12-11T13:38:01.491Z","dependency_job_id":"de2a171b-e964-4231-acfc-0c0d981375da","html_url":"https://github.com/goatplatform/goatdb","commit_stats":null,"previous_names":["ofriw/goatdb","goatplatform/goatdb"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goatplatform%2Fgoatdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goatplatform%2Fgoatdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goatplatform%2Fgoatdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goatplatform%2Fgoatdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goatplatform","download_url":"https://codeload.github.com/goatplatform/goatdb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247847601,"owners_count":21006099,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["backend","browser","database","deno","devtools","edge","frontend","local-first","low-code","react","typescript"],"created_at":"2025-03-03T04:02:29.940Z","updated_at":"2025-04-08T13:02:36.388Z","avatar_url":"https://github.com/goatplatform.png","language":"TypeScript","funding_links":["https://github.com/sponsors/goatplatform"],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/user-attachments/assets/4975e49c-e73c-435e-8e10-97adc2c0aaeb\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://github.com/user-attachments/assets/270caf47-3ed8-49d4-b3b9-74a51bd2d6c0\"\u003e\n    \u003cimg alt=\"GoatDB Logo\" src=\"https://github.com/user-attachments/assets/270caf47-3ed8-49d4-b3b9-74a51bd2d6c0\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n---\n\n# GoatDB: An Embedded, Distributed, Document Database\n\n\u003cp align=\"center\"\u003e\n📦 \u003ca href=\"/docs/installation.md\"\u003eInstallation\u003c/a\u003e •\n🚀 \u003ca href=\"/docs/tutorial.md\"\u003eTutorial\u003c/a\u003e • ❓ \u003ca href=\"/faq\"\u003eFAQ\u003c/a\u003e • \u003ca href=\"/benchmarks\"\u003e⚡ Benchmarks\u003c/a\u003e • 💬 \u003ca href=\"https://github.com/goatplatform/goatdb/discussions\"\u003eDiscussions\u003c/a\u003e • 👋 \u003ca href=\"https://discord.gg/SAt3cbUqxr\"\u003eDiscord\u003c/a\u003e\n\u003c/p\u003e\n\nGoatDB is an embedded, distributed, document database that prioritizes\n[speed](https://goatdb.dev/benchmarks) and\n[developer experience](https://goatdb.dev/tutorial/). It excels at real-time\ncollaboration and embedded caching applications.\n\nInstead of following traditional database design patterns, GoatDB leverages\nconcepts refined over decades by distributed version control systems. These are\nenhanced with novel algorithms\n([bloom filter-based synchronization](https://goatdb.dev/sync/) and\n[ephemeral CRDTs](https://goatdb.dev/conflict-resolution)) for efficient\nsynchronization and automatic real-time conflict resolution.\n\nCurrently optimized for JavaScript environments, GoatDB functions as a\nfirst-class citizen in both browsers and servers. It utilizes a document model\nwith schemas, providing causal eventual consistency to simplify development\nwhile offering built-in optional cryptographic signing for the underlying commit\ngraph.\n\nGoatDB implements incremental local queries, leveraging its version control\ninternals to efficiently process only changed documents.\n\nGoatDB employs a memory-first design and a different scaling approach than\ntraditional databases. Rather than growing a single large database, it uses\napplication-level sharding with multiple medium-sized repositories that sync\nindependently. Each user or data group has its own repository, enabling\nhorizontal scaling and efficient client-server synchronization. This\narchitecture provides natural scalability for multi-user applications without\ncomplex manual sharding.\n\nItems in GoatDB are defined alongside their schema. Schemas dictate both the\nfield types and their conflict resolution strategy. Schemas are themselves\nversioned, making rolling schema updates via branches a natural mechanism.​​​​​​​​​​​​​​​​\n\n👉 If you like what we're building, please star ⭐️ our project. We really\nappreciate it! 🙏\n\n\u003e [!WARNING]\n\u003e Please keep in mind that GoatDB is still under active development and\n\u003e therefore full backward compatibility is not guaranteed before reaching\n\u003e v1.0.0.\n\n## Example Projects\n\nExplore projects built with GoatDB:\n\n- **[Todo](https://github.com/goatplatform/todo)**: A minimalist, modern, todo\n  list app specifically designed for self hosting.\n\n- **[EdgeChat](https://github.com/goatplatform/edge-chat)**: A demo of a\n  ChatGPT-like interface that runs completely in the browser, no network\n  connection needed.\n\n- **[Ovvio](https://ovvio.io)**: A productivity suite that has been powered by\n  GoatDB in production since January 2024.\n\n## Installation\n\nGoatDB can be installed in both Deno and Node.js environments. While our\npreferred runtime is Deno (which supports compiling to a self-contained\nexecutable), we also provide experimental support for Node.js. See the full\n[installation instructions](https://goatdb.dev/install) for all compatible\nruntimes.\n\n### Installation\n\n1. **Add GoatDB to your project:**\n\n   ```bash\n   deno add jsr:@goatdb/goatdb\n   ```\n\n2. **Initialize the React Skaffold:**\n\n   ```bash\n   deno run -A jsr:@goatdb/goatdb/init\n   ```\n   \u003e **Note**: This step is only needed for Single Page Applications (SPAs). The\n   \u003e initialization command installs React dependencies and creates a project\n   \u003e skaffold that includes both client-side and server-side code structure. If\n   \u003e you're not building a SPA or already have your React setup, you can skip\n   \u003e this step.\n\n## Basic Usage\n\n```tsx\nimport { GoatDB } from '@goatdb/goatdb';\n\nconst db = new GoatDB({ path: './server-data', peers: ['http://10.0.0.1'] });\nconst item = db.create('/todos', { text: 'Hello, GoatDB!', done: false });\n\n// Update in memory; auto-commits in background\nitem.set('done', true);\n\nconsole.log(item.get('text'), item.get('done'));\n// Output: \"Hello, GoatDB!\" true\n```\n\nGoatDB makes it easy to set up a cluster of servers by specifying replica\nlocations in the `peers` field during initialization. Each server will\nautomatically synchronize with its replicas at the provided URLs, using the same\nefficient sync protocol that clients use to stay in sync with servers. This\nmeans you can easily scale out your deployment by adding more replicas without\nchanging any code or protocols - the servers will seamlessly coordinate using\nthe built-in sync mechanism.\n\n## Using React Hooks\n\nGoatDB's React hooks provide a complete state management solution with mutable\nstate that you can edit synchronously. When you make changes (like\n`task.set('done', true)`), they're applied immediately in memory while GoatDB\nhandles computing diffs, committing to local storage, syncing with the server,\nand resolving conflicts automatically in the background. This gives you simple\nlocal state management with automatic cross-client synchronization and server\npersistence. Here's how the hooks work in practice:\n\n```tsx\nimport { useDB, useItem, useQuery } from '@goatdb/goatdb/react';\n\n// Use hooks in your components\nfunction TaskList() {\n  const db = useDB();\n\n  // Query tasks sorted by text\n  const query = useQuery({\n    schema: kSchemaTask,\n    source: `/data/${db.currentUser!.key}`,\n    sortDescriptor: ({ left, right }) =\u003e\n      left.get('text').localeCompare(right.get('text')),\n  });\n\n  return (\n    \u003cdiv\u003e\n      {query.results().map(({ path }) =\u003e \u003cTaskItem key={path} path={path} /\u003e)}\n    \u003c/div\u003e\n  );\n}\n\nfunction TaskItem({ path }) {\n  // Subscribe to changes for a specific task\n  const task = useItem(path);\n\n  return (\n    \u003cdiv\u003e\n      \u003cinput\n        type='checkbox'\n        checked={task.get('done')}\n        onChange={(e) =\u003e task.set('done', e.target.checked)}\n      /\u003e\n      \u003cinput\n        type='text'\n        value={task.get('text')}\n        onChange={(e) =\u003e task.set('text', e.target.value)}\n      /\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n## Running the Interactive Server\n\n```bash\ndeno task debug\n```\n\nStarts an interactive debug server that listens on http://localhost:8080.\n\n## Compiling a Server Binary\n\n```bash\ndeno task build\n```\n\nBuilds a self-contained executable that bundles the server, database and client\ncode together with no external dependencies or containers needed, making it\ncloud agnostic and easy to self-host on any server you wish.\n\nThat’s it! GoatDB keeps your app running even if the server fails, with clients\nseamlessly backing up and restoring data. No complex indexing required, thanks\nto incremental queries.\n\n## Contributing\n\n**All contributions to this project are made under the Apache License, Version\n2.0. By submitting a Pull Request, you agree that your contributions are\nlicensed under Apache-2.0.**\n\nTo contribute to GoatDB, follow these steps:\n\n1. Fork the repository\n2. Create a branch for your changes\n3. Submit a pull request\n\nWe strive to review all pull requests within a few business days.\n\nTo work on GoatDB's code alongside a project that uses it, run:\n\n```bash\ndeno run -A jsr:@goatdb/goatdb/link link ./path/to/goatdb\n```\n\nThis will link the local GoatDB repo into your project, allowing you to make\nchanges to the codebase and have them reflected in your project without having\nto reinstall GoatDB.\n\nTo unlink GoatDB, run:\n\n```bash\ndeno run -A jsr:@goatdb/goatdb/link unlink\n```\n\nGoatDB has a test suite to ensure reliability and performance. While not yet\ncomprehensive, we're working on expanding them. You can run the tests using:\n\n```bash\ndeno task test\n```\n\nGoatDB includes benchmarks to measure performance across various operations. To\nrun the benchmarks:\n\n```bash\ndeno task bench\n```\n\n## License\n\nGoatDB is licensed under the [Apache 2.0 License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoatplatform%2Fgoatdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoatplatform%2Fgoatdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoatplatform%2Fgoatdb/lists"}