/
Install

Development ​

Commands ​

bash
make test        # go test ./...
make race        # with the race detector
make lint        # golangci-lint (wsl enforces blank lines)
make build       # static binary: bin/ndb
make dist        # tar.gz + checksums.txt in dist/ (linux/amd64, linux/arm64, darwin/arm64)
test/smoke.sh    # builds ndb and runs every endpoint with curl

Keep local test runs light:

bash
nice -n 10 go test -p 2 -race -parallel=2 -timeout 300s ./...

make fuzz-smoke runs each fuzz target for 10 s with two workers. Long fuzz runs belong in CI.

SDK tests:

bash
(cd sdk/go && go test -race ./...)          # starts the daemon it needs
(cd sdk/ruby && bundle install && bundle exec rake test)   # gem ndb
(cd sdk/rails && bundle install && bundle exec rake test)  # gem ndb-rails
(cd sdk/ts && pnpm install && pnpm test && pnpm lint && pnpm typecheck && pnpm build)

Code layout ​

Where the code lives, for contributors.

PackageJob
cmd/ndbflags, listeners, graceful stop, ndb backup
internal/serverHTTP routes, error mapping, metrics, watch stream
internal/engineopens the data dir, owns the collections, blobs and backup
internal/catalogcollection definitions in catalog.bolt; merge of code, YAML and implicit declarations
internal/configloads the optional ndb.yml
internal/collectionone collection: writes, reads, indexes, sealing, compaction, TTL
internal/writer, internal/walengine-mode WAL with CRC and group commit
internal/tailerdirect mode: follows the source files, keeps a cursor per file, quarantines bad lines
internal/query, internal/aggparse and run where, sort and aggregate pipelines
internal/segmentParquet segments
internal/index_id and secondary indexes
internal/feed, internal/cursorswatch change feed and consumer positions
internal/blobcontent-addressed blob store
internal/recovery, internal/lockstart-up recovery, one daemon per data dir (flock)

Docs site ​

The site in docs-site/ is built from docs/dev/*.md (the only source; no copies). It uses VitePress with a custom theme and the tokens of brand/.

bash
cd docs-site
pnpm install
pnpm docs:dev      # live reload
pnpm docs:build    # static site in docs-site/.vitepress/dist

A push to main that changes docs/, docs-site/ or brand/ deploys it to Cloudflare Pages with wrangler (.github/workflows/docs.yml, project ndb-docs). Links in the docs that point outside docs/dev/ become GitHub links in the site.

Rules ​

  • Test first. Each change starts with a failing test.
  • gofmt and GOOS=linux go vet ./... must be clean.
  • Code style: a blank line before if, for, switch, return, defer, go, after a closing }, and between groups that do different things.
  • Docs in docs/dev/ change with the behavior.

Release ​

Push a tag vX.Y.Z. The full checklist is in releasing.md.

  • release.yml runs the tests, builds the static binaries with the version in -ldflags "-X main.version=...", makes tar.gz files and checksums.txt, and creates the GitHub release with generated notes.
  • release.yml also pushes the Go submodule tag sdk/go/vX.Y.Z.
  • publish-npm.yml publishes @thadeu/ndb; publish-gem.yml publishes ndb, then ndb-rails.
  • image.yml builds the multi-arch image and pushes ghcr.io/<owner>/ndb.

ndb -version prints the version. Locally: make dist VERSION=0.1.0.

GoReleaser is not used: it would do the same job as release.yml (build matrix, archives, checksums, release), and the workflow is the same shape as the one in the sibling project anway.