Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

8.7 KB
Raw Blame

Design Principles

Bytebase is the standard for database development. Every product and engineering decision serves that goal, built on three principles:

  1. Bring every database under unified control. Every person and AI agent accesses and changes data through one governed path.
  2. Govern change and access as code. Reviewed, enforced, and recorded by policy, not by discipline.
  3. Make the safe path the easy path. Safe by default, simple by design — so no one routes around it.

Read before working

  • Before exploring domain behavior, read domain guidance.
  • For frontend work, read frontend/AGENTS.md; before changing UI, also read the UX contract.
  • Before adding or modifying metadata SQL, pagination, or multi-row transactions anywhere in the repo, read backend/store/AGENTS.md. This includes CEL-to-SQL filters and raw reads in tests.
  • Before changing metadata/DDL conversions or their golden fixtures, read backend/plugin/schema/AGENTS.md. It covers what these packages test and the record process for regenerating fixtures.
  • For issue operations, read issue-tracker.md. Linear is the tracker. For triage, also read triage-labels.md.
  • Before creating a PR, complete docs/pre-pr-checklist.md.
  • AGENTS.md files are the instruction source of truth; CLAUDE.md files import them.

Metadata and API conventions

  • The metadata schema is backend/migrator/migration/LATEST.sql; migrations live in backend/migrator/migration/<major.minor>/.
  • New migrations require updating TestLatestVersion in backend/migrator/migrator_test.go; DDL changes also update LATEST.sql.
  • Metadata JSONB uses protojson.Marshal: keys are camelCase (taskRun), not proto snake_case (task_run).
  • Follow Google language style guides and AIPs for API/proto design. AIPs take precedence over the proto guide. Enum values use HELLO, not TYPE_HELLO.
  • Use American English. Avoid collection names ending in List.
  • Annotating an RPC mcp_method_class = READ or WRITE also changes what the MCP Access policy page promises, and nothing enforces that. Before changing one, read mcp-capability-ladder.md. The in-console agent also runs every READ method without asking (apiCallNeedsConfirmation in frontend/src/modules/agent/logic/tools/apiMethodClass.ts), so a READ method that MCP narrows per request needs an exception there.

Forked engine packages

Some engines have their own copy of a package rather than sharing MySQL's or Postgres's: mariadb and oceanbase are forks of mysql, starrocks of doris, redshift of pg. A fork exists because omni gives each engine an independent AST, so one implementation cannot walk two of them.

  • A fix to a rule, parser or validator in a parent usually applies to its forks. Check each one, port it in the same PR, and name every engine in the subject (fix(mysql,mariadb): ...). This mirrors omni's own rule for parser forks.
  • Inherited facts need re-verifying per engine even where inherited code is correct. StarRocks took Doris's EXPLAIN modifier list and was wrong about it.
  • A fork is partial where omni's tree is. schema/mariadb registers MariaDB but owns no catalog work, because omni's mariadb/catalog has New, Exec and LoadSQL and none of the LoadMetadata, Diff, GenerateMigration or version handling schema/mysql needs; it simulates on omni's MySQL catalog instead. Check the engine's omni tree before assuming a layer can fork, and keep the engine's own package even when it only holds that decision.

Customer information

The repository and its pull requests are public. Never identify a Bytebase customer or user in code, comments, test fixtures, docs, commit messages, or PR titles, bodies, and screenshots. That covers company names, their employees' names and emails, their domains, and the instance, database, and host names, schemas, SQL, or data copied from their environments. Describe the case generically, such as "a customer with 10k databases", and reference the Linear issue for details. Use placeholders such as example.com in fixtures, and redact screenshots.

Code comments

  • Use names and structure to explain what code does. Reserve comments for non-obvious intent, invariants, ordering constraints, external behavior, and public API contracts.
  • Default to one or two sentences. Longer comments must explain a constraint a maintainer needs to change the code safely.
  • Keep implementation history, rejected approaches, review discussions, and follow-up inventories in PRs or issues. For a workaround, keep only the current limitation and a relevant issue reference beside the code.
  • Explain each constraint once, where it is enforced. In tests, let case names and assertions describe behavior; comment only on surprising fixtures or semantics.
  • Before handoff, reread added or modified comments. Remove code narration and repeated rationale, and verify the remaining claims against the implementation.

Test placement

Test API and workflow behavior against PostgreSQL. Engine dialect and DDL fidelity tests belong in omni.

  • Test logic in its owning package. Use backend/api/v1 for service behavior and backend/store for metadata queries, collision isolation, and transaction contention. CI runs every test with no -short, so never check testing.Short() or skip a test to park a known gap; gate a test on an environment variable only when it needs credentials or a server CI cannot provide.
  • A backend test boots a Bytebase server only when it needs a background runner, real rollout, or audit trail; these tests live in backend/tests. Browser E2E tests use the separate frontend harness.
  • Packages needing metadata PostgreSQL use testcontainer.Main and testcontainer.NewMetadataDB. Target-engine tests use testcontainer.SharedPgContainer or its siblings, with NewPgDatabase for a database per test. Use these shared fixtures instead of package-owned or per-test containers; a package with its own TestMain defers testcontainer.CloseShared.
  • Prefer pure functions for handler decisions and conversions. When state reads are necessary, define a narrow interface beside the handler and fake it, as backend/api/mcp does with serverStore; avoid an interface over the entire store. Every fake requires a contract test against the real store too.
  • New or modified composite-key methods require collision coverage. Prove colliding keys exist, assert the intended effect in the target scope, and assert the other scope is unchanged. Use the lowest test layer that exercises the behavior. Existing API collision tests remain regression coverage; fixture details are in the pre-PR checklist.

Verification

During iteration, run focused checks for the changed behavior. Before handoff, run the applicable final gates below. Correct failures before rerunning; repeat when fixes expose further issues, rather than rerunning unchanged failures. Report any unavailable prerequisite or remaining failure explicitly. Inspect formatter/autofix output for unrelated edits.

Go changes

  1. Run gofmt -w on modified Go files.
  2. Run GOGC=off GOMEMLIMIT=10GiB golangci-lint run --fix -j 8 --allow-parallel-runners, then the same command without --fix until clean after corrections. Run at repo root without filenames so package context is available. Keep the flags: on a cold cache they take the run from ~730 to ~420 CPU-seconds and hold peak RSS near 10 GB, on a box shared with two CI runners.
  3. Run tests for changed packages and affected behavior, including required collision or contention coverage.
  4. Build: go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go.
  5. After dependency changes, run go mod tidy and recheck affected code.

For focused tests, quote the regex:

go test -v -count=1 ./backend/store/ -run '^(TestFunctionName|TestFunctionNameTwo)$'

Frontend changes

Run pnpm --dir frontend fix, then pnpm --dir frontend test — the single gate CI runs. To iterate, pnpm --dir frontend vitest run <path> runs one file; pnpm --dir frontend run prepare refreshes generated sources.

For browser verification, read frontend/tests/e2e/README.md; before writing tests, read its AGENTS.md.

Proto changes

Run buf format -w proto, buf lint proto, and (cd proto && buf generate). Verify generated Go/frontend changes with their corresponding gates.

Documentation changes

Check local links, referenced paths/symbols, and shell examples. Code build/test gates do not apply to documentation-only changes.