Self-host GoatDB

Changelog

All notable changes to GoatDB will be documented in this file.

The format is based on Keep a Changelog, and GoatDB adheres to Semantic Versioning.

Pre-1.0 compatibility notice: GoatDB is still pre-1.0. Backward compatibility is not guaranteed between releases; APIs, storage formats, and behavior may change without notice.

Unreleased

[0.6.1] - 2026-09-01

Fixed

• Republish 0.6.0 as 0.6.1: npm prohibits re-publishing an unpublished version (tombstone retention in registry time metadata), so 0.6.1 supersedes with identical code.

0.6.0 - 2026-08-30

Breaking Changes

• Binary .goat storage format: Commits are now stored in a compact binary format (magic byte 0x47 'G', little-endian commit fields, big-endian 4-byte length framing). Both .jsonl and binary storage are supported, with the format selected through DBInstanceConfig.storageFormat. Tooling that reads .goat files directly requires manual migration.

• Bloom-filter ancestors replaced with explicit string arrays: The af and ac commit fields are no longer written or read. Existing commits using Bloom-filter ancestry load with empty ancestor arrays and rebuild their ancestry through new merge commits.

• Strict .goat binary records: Non-binary records in .goat files are rejected instead of being silently loaded. Mixed JSON/binary files require manual migration.

• Ed25519 signing replaces ECDSA P-384: Existing ECDSA-signed commits cannot be verified after upgrading and require a fresh trust pool.

• Query cache identity changed: Query IDs now use Murmur3 and account for relevant options and normalized source paths. Persisted caches from earlier versions may miss and be rebuilt lazily.

• Query live updates are enabled by default: Queries now receive uncommitted updates from set(). Set liveUpdates: false to retain commit-only behavior.

• Public API changes: The optional session parameter was removed from Repository.leavesForKey(), and commitIsHighProbabilityLeaf() was renamed to commitIsLeaf().

• Item path components are limited to 39 characters: Type, repository, item, and embed path components longer than 39 characters are rejected.

Added

• GoatDB.insert() for creating batches of new items without redundant ancestor computation.
• liveUpdates query configuration for selecting live or commit-only updates.
• WriteFailure events on GoatDB when a commit cannot be persisted.
• Shard configuration through maxShardCommits, splitThreshold, and minShardCommits, with read-only access through GoatDB.shardConfig.
• Public AppConfig.esbuildPlugins support for build customization.

Changed

• CSS is bundled through esbuild during compile and debug builds, including plugin processing, hashed url() assets, and composed sourcemaps.
• The normal-accuracy sync Bloom-filter false-positive rate is capped at 0.001 to reduce unnecessary resynchronization rounds. The low-accuracy path retains its previous setting.
• Repository authentication concurrency is captured when the repository is created, preventing inconsistent verification batching.
• The homepage, benchmarks, and documentation have been overhauled.

Fixed

• Conflict resolution now selects the closest available lowest common ancestor and defers merging when that ancestor is unavailable, avoiding destructive fallback merges.
• Query IDs no longer collide across relevant options or source paths, explicit empty IDs are preserved, stale aliases are avoided, and generated-ID caching is bounded.
• Query ordering and find() now handle dates, booleans, numbers, NaN, and near-equal values consistently.
• Locally created commits retain monotonic creation order when timestamps collide.
• CoroutineQueue now preserves FIFO ordering, runs a single worker, and recovers after task failures.
• Zero-byte writes now fail explicitly instead of retrying indefinitely.

0.5.1 - 2026-03-05

Breaking Changes

• ./init sub-path export removed. deno run -A jsr:@goatdb/goatdb/init no longer works.

  Migration:

  # Before
  deno run -A jsr:@goatdb/goatdb/init
  
  # After (Deno)
  deno run -A jsr:@goatdb/goatdb init
  
  # After (Node.js)
  npx -y @goatdb/goatdb init

Changed

• npm build output uses .js extension instead of .mjs
• @types/node bumped from ^22 to ^24
• postject bundled as optional dependency — no more global install required
• esbuild target updated from node18 to node24
• goatdb CLI binary now available via npm (npx -y @goatdb/goatdb init)

0.5.0 - 2026-02-26

[0.4.0] - 2026-02-20

Breaking Changes

• Build tools moved from @goatdb/goatdb/server: compile, startDebugServer, and AppConfig moved to @goatdb/goatdb/server/build. Runtime exports (Server, createHttpServer, etc.) remain in @goatdb/goatdb/server.

  Migration:

  // Before
  import { compile, Server, startDebugServer } from '@goatdb/goatdb/server';
  
  // After
  import { Server } from '@goatdb/goatdb/server';
  import { compile, startDebugServer } from '@goatdb/goatdb/server/build';

Security

• Fixed two vulnerabilities in persistCommits: null namespace guard and delta-based record bypass

Added

• GoatDB.sync(repo) and GoatDB.syncAll() for explicit sync control
• GoatDB.mode property to query the current operation mode
• Client mode for non-browser environments (Deno, Node.js)
• StderrLogStream for logging to stderr
• getGlobalLoggerStreams() for log stream management
• Loading status exposed on ManagedItem
• itemPathIsValid() exported as a public utility
• getEnvVar exported as stable cross-runtime API
• setup callback in DebugServerOptions for configuring server-side logic during development
• Health check endpoint on Server
• port and address getters on Server; graceful shutdown support
• Node.js Single Executable Application (SEA) compilation via compile()
• jsr:@goatdb/goatdb/link now works in Node.js in addition to Deno
• HTTPS support with automatic self-signed certificate generation for secure development

Changed

• Runtime abstraction layer refactored for cross-platform compatibility (Deno, Node.js, Browser)
• Path utilities moved to base/path.ts with POSIX-style handling across all environments
• Windows path support — backslashes from Deno.cwd()/process.cwd() are normalized to forward slashes
• FileImpl interface extended with exists, copyFile, and readDir methods
• CLI init templates externalized to cli/templates/ directory
• CLI commands (init, link) now work in Node.js
• Build info and platform detection now work on Windows
• Node.js minimum version raised to 24 (required for SEA support)
• Node.js is now production-ready; experimental warning removed
• esbuild bumped from 0.24 to 0.25.4
• Browser getOS() uses 3-tier detection (User-Agent Client Hints, navigator.platform, User-Agent string) and returns 'unknown' when platform cannot be detected
• Default server port for HTTPS changed to 8443 (HTTP remains 8080)
• ManagedItem.commit() now ensures all changes are fully committed before returning

Removed

• @std/fs dependency (replaced by cross-runtime file abstraction)
• @std/expect dependency (fixes test compatibility on Node.js)

Fixed

• Expired sessions are now blocked from accessing protected routes
• First sync awaited when opening a repository for the first time
• Query scan now correctly awaited in browser environments
• Resource leak in OPFS copyFile() — file handles now properly closed on error
• Template DomainConfig used incorrect method names (resolveOrg instead of mapToOrg)
• Template HTML referenced raw index.tsx instead of built /app.js
• Sync engine: recursive serverUrl expansion, infinite loop, dangling promise, and sync-before-open bugs
• FileImpl: partial-read loop and resource cleanup on error
• No longer crashes when the cache file is missing
• Now throws an error when commit contents are missing instead of failing silently

0.3.1

Fixed

• Support for crypto on older Node.js versions has been improved #27
• Item not properly propagating schema field types
• Correctly propagate inspect flag to worker in node #27
• GoatDB.close() correctly flushes to disk and clears memory

Changed

• Updated React dependency to 19.1.0

0.3.0

Added

• Orderstamp is now bundled and exposed directly within GoatDB

0.2.2

Added

• An exception is now thrown when passing an invalid source path to a query
• Added SchemaField<T> for easy access to a schema's field names

Fixed

• itemPathNormalize sometimes returns relative paths

Changed

• Renamed SchemaManager to DataRegistry
• Renamed DBConfig to DBInstanceConfig

0.2.1

Added

• FieldDef.validate enables custom field level validation
• Before/After hooks for integrating with external build steps via LiveReloadOptions.beforeBuild and LiveReloadOptions.afterBuild
• CoreTypes are now exported by the top level mod.ts
• It's now possible to set a custom user schema via SchemaManager.userSchema
• Attempting to commit an item with invalid data now throws with a detailed message when running in debug mode

Fixed

• Live reload in debug server is now working again
• Set types being deserialized incorrectly
• Crash in useItem React hook when first passing undefined then a ManagedItem instance

0.2.0

Added

• Initial support for Node.js
• Trusted mode which disables security mechanisms for increased performance in trusted environments

Changed

• Auth rules now accept an info object like query predicate and sort descriptor
• Added default auth rules for /user/<userId>
• Improved repository open performance by ~25%

Fixed

• Attempting to register multiple auth rules throws an error
• Crash when opening a query without a sort descriptor
• db.flush now properly flushes query caches to disk

Removed

• Order stamps have been moved to their own repository — https://github.com/goatplatform/orderstamp-js

0.1.6 - 2025-02-26

Added

• FileImpl.getCWD to get the current working directory
• cli/link.ts now enables easy development of GoatDB alongside an existing project

Fixed

• Debug server now correctly turns on debug mode

0.1.3 - 2025-02-17

Added

• BaseTimer.reset to reset the timer and reschedule it

Changed

• GoatDB is now licensed under Apache 2.0
• JSONLogFile.append now automatically scans the log file rather than throw
• JSONLogFile worker now uses the transpiled JS version both for the server and the browser
• Improved React SPA scaffold
• ServerOptions.domain enables fine control over domain / organization mapping

Fixed

• Configuration is now correctly injected into the app bundle

0.1.2 - 2025-02-16

Added

• Item.isNull to check if an item has a null schema
• It's now possible to override the authorization rules for /sys/users and /sys/*
• Query.sortDescending to sort results in descending order

Changed

• Item.get now returns undefined for null items

Fixed

• Init script calling manager.register() instead of manager.registerSchema()
• Item.isNull now works as expected

0.1.1 - 2025-02-15

Added

• ServerOptions.autoCreateUser for environment-specific user creation

Changed

• Updated LLM cheatsheet

Removed

• Operator Emails

0.1.0 - 2025-02-13

Added

• Initial release

Changelog

All notable changes to GoatDB will be documented in this file.

The format is based on Keep a Changelog,
and GoatDB adheres to
Semantic Versioning.

0.5.1 - 2026-03-05

Breaking Changes

• ./init sub-path export removed. deno run -A jsr:@goatdb/goatdb/init no
  longer works.

  Migration:

  # Before
  deno run -A jsr:@goatdb/goatdb/init
  
  # After (Deno)
  deno run -A jsr:@goatdb/goatdb init
  
  # After (Node.js)
  npx -y @goatdb/goatdb init

Changed

• npm build output uses .js extension instead of .mjs
• @types/node bumped from ^22 to ^24
• postject bundled as optional dependency — no more global install required
• esbuild target updated from node18 to node24
• goatdb CLI binary now available via npm (npx -y @goatdb/goatdb init)

0.5.0 - 2026-02-26

[0.4.0] - 2026-02-20

Breaking Changes

• Build tools moved from @goatdb/goatdb/server: compile,
  startDebugServer, and AppConfig moved to @goatdb/goatdb/server/build.
  Runtime exports (Server, createHttpServer, etc.) remain in
  @goatdb/goatdb/server.

  Migration:

  // Before
  import { compile, Server, startDebugServer } from '@goatdb/goatdb/server';
  
  // After
  import { Server } from '@goatdb/goatdb/server';
  import { compile, startDebugServer } from '@goatdb/goatdb/server/build';

Security

• Fixed two vulnerabilities in persistCommits: null namespace guard and
  delta-based record bypass

Added

• GoatDB.sync(repo) and GoatDB.syncAll() for explicit sync control
• GoatDB.mode property to query the current operation mode
• Client mode for non-browser environments (Deno, Node.js)
• StderrLogStream for logging to stderr
• getGlobalLoggerStreams() for log stream management
• Loading status exposed on ManagedItem
• itemPathIsValid() exported as a public utility
• getEnvVar exported as stable cross-runtime API
• setup callback in DebugServerOptions for configuring server-side logic
  during development
• Health check endpoint on Server
• port and address getters on Server; graceful shutdown support
• Node.js Single Executable Application (SEA) compilation via compile()
• jsr:@goatdb/goatdb/link now works in Node.js in addition to Deno
• HTTPS support with automatic self-signed certificate generation for secure
  development

Changed

• Runtime abstraction layer refactored for cross-platform compatibility (Deno,
  Node.js, Browser)
• Path utilities moved to base/path.ts with POSIX-style handling across all
  environments
• Windows path support — backslashes from Deno.cwd()/process.cwd() are
  normalized to forward slashes
• FileImpl interface extended with exists, copyFile, and readDir methods
• CLI init templates externalized to cli/templates/ directory
• CLI commands (init, link) now work in Node.js
• Build info and platform detection now work on Windows
• Node.js minimum version raised to 24 (required for SEA support)
• Node.js is now production-ready; experimental warning removed
• esbuild bumped from 0.24 to 0.25.4
• Browser getOS() uses 3-tier detection (User-Agent Client Hints,
  navigator.platform, User-Agent string) and returns 'unknown' when platform
  cannot be detected
• Default server port for HTTPS changed to 8443 (HTTP remains 8080)
• ManagedItem.commit() now ensures all changes are fully committed before
  returning

Removed

• @std/fs dependency (replaced by cross-runtime file abstraction)
• @std/expect dependency (fixes test compatibility on Node.js)

Fixed

• Expired sessions are now blocked from accessing protected routes
• First sync awaited when opening a repository for the first time
• Query scan now correctly awaited in browser environments
• Resource leak in OPFS copyFile() — file handles now properly closed on error
• Template DomainConfig used incorrect method names (resolveOrg instead of
  mapToOrg)
• Template HTML referenced raw index.tsx instead of built /app.js
• Sync engine: recursive serverUrl expansion, infinite loop, dangling promise,
  and sync-before-open bugs
• FileImpl: partial-read loop and resource cleanup on error
• No longer crashes when the cache file is missing
• Now throws an error when commit contents are missing instead of failing
  silently

0.3.1

Fixed

• Support for crypto on older Node.js versions has been improved #27
• Item not properly propagating schema field types
• Correctly propagate inspect flag to worker in node #27
• GoatDB.close() correctly flushes to disk and clears memory

Changed

• Updated React dependency to 19.1.0

0.3.0

Added

• Orderstamp is now bundled and
  exposed directly within GoatDB

0.2.2

Added

• An exception is now thrown when passing an invalid source path to a query
• Added SchemaField<T> for easy access to a schema's field names

Fixed

• itemPathNormalize sometimes returns relative paths

Changed

• Renamed SchemaManager to DataRegistry
• Renamed DBConfig to DBInstanceConfig

0.2.1

Added

• FieldDef.validate enables custom field level validation
• Before/After hooks for integrating with external build steps via
  LiveReloadOptions.beforeBuild and LiveReloadOptions.afterBuild
• CoreTypes are now exported by the top level mod.ts
• It's now possible to set a custom user schema via SchemaManager.userSchema
• Attempting to commit an item with invalid data now throws with a detailed
  message when running in debug mode

Fixed

• Live reload in debug server is now working again
• Set types being deserialized incorrectly
• Crash in useItem React hook when first passing undefined then a
  ManagedItem instance

0.2.0

Added

• Initial support for Node.js
• Trusted mode which disables security mechanisms for increased performance in
  trusted environments

Changed

• Auth rules now accept an info object like query predicate and sort descriptor
• Added default auth rules for /user/<userId>
• Improved repository open performance by ~25%

Fixed

• Attempting to register multiple auth rules throws an error
• Crash when opening a query without a sort descriptor
• db.flush now properly flushes query caches to disk

Removed

• Order stamps have been moved to their own repository —
  https://github.com/goatplatform/orderstamp-js

0.1.6 - 2025-02-26

Added

• FileImpl.getCWD to get the current working directory
• cli/link.ts now enables easy development of GoatDB alongside an existing
  project

Fixed

• Debug server now correctly turns on debug mode

0.1.3 - 2025-02-17

Added

• BaseTimer.reset to reset the timer and reschedule it

Changed

• GoatDB is now licensed under Apache 2.0
• JSONLogFile.append now automatically scans the log file rather than throw
• JSONLogFile worker now uses the transpiled JS version both for the server
  and the browser
• Improved React SPA scaffold
• ServerOptions.domain enables fine control over domain / organization mapping

Fixed

• Configuration is now correctly injected into the app bundle

0.1.2 - 2025-02-16

Added

• Item.isNull to check if an item has a null schema
• It's now possible to override the authorization rules for /sys/users and
  /sys/*
• Query.sortDescending to sort results in descending order

Changed

• Item.get now returns undefined for null items

Fixed

• Init script calling manager.register() instead of manager.registerSchema()
• Item.isNull now works as expected

0.1.1 - 2025-02-15

Added

• ServerOptions.autoCreateUser for environment-specific user creation

Changed

• Updated LLM cheatsheet

Removed

• Operator Emails

0.1.0 - 2025-02-13

Added

• Initial release

Changelog

All notable changes to GoatDB will be documented in this file.

The format is based on Keep a Changelog,
and GoatDB adheres to
Semantic Versioning.

0.4.0 - 2026-02-20

Breaking Changes

• Build tools moved from @goatdb/goatdb/server: compile,
  startDebugServer, and AppConfig moved to @goatdb/goatdb/server/build.
  Runtime exports (Server, createHttpServer, etc.) remain in
  @goatdb/goatdb/server.

  Migration:

  // Before
  import { compile, Server, startDebugServer } from '@goatdb/goatdb/server';
  
  // After
  import { Server } from '@goatdb/goatdb/server';
  import { compile, startDebugServer } from '@goatdb/goatdb/server/build';

Security

• Fixed two vulnerabilities in persistCommits: null namespace guard and
  delta-based record bypass

Added

• GoatDB.sync(repo) and GoatDB.syncAll() for explicit sync control
• GoatDB.mode property to query the current operation mode
• Client mode for non-browser environments (Deno, Node.js)
• StderrLogStream for logging to stderr
• getGlobalLoggerStreams() for log stream management
• Loading status exposed on ManagedItem
• itemPathIsValid() exported as a public utility
• getEnvVar exported as stable cross-runtime API
• setup callback in DebugServerOptions for configuring server-side logic
  during development
• Health check endpoint on Server
• port and address getters on Server; graceful shutdown support
• Node.js Single Executable Application (SEA) compilation via compile()
• jsr:@goatdb/goatdb/link now works in Node.js in addition to Deno
• HTTPS support with automatic self-signed certificate generation for secure
  development

Changed

• Runtime abstraction layer refactored for cross-platform compatibility (Deno,
  Node.js, Browser)
• Path utilities moved to base/path.ts with POSIX-style handling across all
  environments
• Windows path support — backslashes from Deno.cwd()/process.cwd() are
  normalized to forward slashes
• FileImpl interface extended with exists, copyFile, and readDir methods
• CLI init templates externalized to cli/templates/ directory
• CLI commands (init, link) now work in Node.js
• Build info and platform detection now work on Windows
• Node.js minimum version raised to 24 (required for SEA support)
• Node.js is now production-ready; experimental warning removed
• esbuild bumped from 0.24 to 0.25.4
• Browser getOS() uses 3-tier detection (User-Agent Client Hints,
  navigator.platform, User-Agent string) and returns 'unknown' when
  platform cannot be detected
• Default server port for HTTPS changed to 8443 (HTTP remains 8080)
• ManagedItem.commit() now ensures all changes are fully committed before
  returning

Removed

• @std/fs dependency (replaced by cross-runtime file abstraction)
• @std/expect dependency (fixes test compatibility on Node.js)

Fixed

• Expired sessions are now blocked from accessing protected routes
• First sync awaited when opening a repository for the first time
• Query scan now correctly awaited in browser environments
• Resource leak in OPFS copyFile() — file handles now properly closed on
  error
• Template DomainConfig used incorrect method names (resolveOrg instead
  of mapToOrg)
• Template HTML referenced raw index.tsx instead of built /app.js
• Sync engine: recursive serverUrl expansion, infinite loop, dangling
  promise, and sync-before-open bugs
• FileImpl: partial-read loop and resource cleanup on error
• No longer crashes when the cache file is missing
• Now throws an error when commit contents are missing instead of failing
  silently

0.3.1

Fixed

• Support for crypto on older Node.js versions has been improved #27
• Item not properly propagating schema field types
• Correctly propagate inspect flag to worker in node #27
• GoatDB.close() correctly flushes to disk and clears memory

Changed

• Updated React dependency to 19.1.0

0.3.0

Added

• Orderstamp is now bundled and
  exposed directly within GoatDB

0.2.2

Added

• An exception is now thrown when passing an invalid source path to a query
• Added SchemaField<T> for easy access to a schema's field names

Fixed

• itemPathNormalize sometimes returns relative paths

Changed

• Renamed SchemaManager to DataRegistry
• Renamed DBConfig to DBInstanceConfig

0.2.1

Added

• FieldDef.validate enables custom field level validation
• Before/After hooks for integrating with external build steps via
  LiveReloadOptions.beforeBuild and LiveReloadOptions.afterBuild
• CoreTypes are now exported by the top level mod.ts
• It's now possible to set a custom user schema via SchemaManager.userSchema
• Attempting to commit an item with invalid data now throws with a detailed
  message when running in debug mode

Fixed

• Live reload in debug server is now working again
• Set types being deserialized incorrectly
• Crash in useItem React hook when first passing undefined then a
  ManagedItem instance

0.2.0

Added

• Initial support for Node.js
• Trusted mode which disables security mechanisms for increased performance in
  trusted environments

Changed

• Auth rules now accept an info object like query predicate and sort descriptor
• Added default auth rules for /user/<userId>
• Improved repository open performance by ~25%

Fixed

• Attempting to register multiple auth rules throws an error
• Crash when opening a query without a sort descriptor
• db.flush now properly flushes query caches to disk

Removed

• Order stamps have been moved to their own repository —
  https://github.com/goatplatform/orderstamp-js

0.1.6 - 2025-02-26

Added

• FileImpl.getCWD to get the current working directory
• cli/link.ts now enables easy development of GoatDB alongside an existing
  project

Fixed

• Debug server now correctly turns on debug mode

0.1.3 - 2025-02-17

Added

• BaseTimer.reset to reset the timer and reschedule it

Changed

• GoatDB is now licensed under Apache 2.0
• JSONLogFile.append now automatically scans the log file rather than throw
• JSONLogFile worker now uses the transpiled JS version both for the server
  and the browser
• Improved React SPA scaffold
• ServerOptions.domain enables fine control over domain / organization mapping

Fixed

• Configuration is now correctly injected into the app bundle

0.1.2 - 2025-02-16

Added

• Item.isNull to check if an item has a null schema
• It's now possible to override the authorization rules for /sys/users and
  /sys/*
• Query.sortDescending to sort results in descending order

Changed

• Item.get now returns undefined for null items

Fixed

• Init script calling manager.register() instead of manager.registerSchema()
• Item.isNull now works as expected

0.1.1 - 2025-02-15

Added

• ServerOptions.autoCreateUser for environment-specific user creation

Changed

• Updated LLM cheatsheet

Removed

• Operator Emails

0.1.0 - 2025-02-13

Added

• Initial release

Fixed

• Support for crypto on older Node.js versions has been improved #27
• Item not properly propagating schema field types
• Correctly propagate inspect flag to worker in node #27
• GoatDB.close() correctly flushes to disk and clears memory

Changed

• Updated React dependency to 19.1.0

Added

• Orderstamp is now bundled and exposed directly within GoatDB