Developer Guidelines

Developer Guidelines#

This page summarizes the development rules for changing or extending the BaSyx Configuration Service. It focuses on the areas where contributors most often affect runtime behavior: sequence registration, SQL patch handling, compatibility with existing databases, idempotent startup behavior, logging, and tests.

Safe Extension Points#

Preferred extension points are:

  • New sequence implementations in internal/basyxconfigurationservice/sequences.

  • Additional explicit sequence registrations in cmd/basyxconfigurationservice/main.go.

  • New SQL patch files in database/patches.

  • Additional tests for new sequence behavior.

Stability Considerations#

The Configuration Service runs before other BaSyx services. A failure blocks dependent services from starting, so changes should be conservative and deterministic.

When extending the service:

  • Preserve the run-once-and-exit behavior.

  • Avoid background goroutines or server loops unless the service goal changes explicitly.

  • Keep startup work deterministic.

  • Avoid non-idempotent operations in restartable sequences.

  • Keep database patch history immutable.

Backward Compatibility#

Database changes must consider existing installations. If a database may already contain older data, patches should migrate that data safely.

Avoid assumptions that are only true for fresh databases. The service supports fresh initialization and upgrades from an existing version row.

Idempotency#

Initialization steps may be retried by container platforms. Sequences should therefore be safe to run more than once whenever possible.

Use patterns such as:

  • CREATE TABLE IF NOT EXISTS

  • ALTER TABLE IF EXISTS ... ADD COLUMN IF NOT EXISTS

  • CREATE INDEX IF NOT EXISTS

  • Version checks before patch execution

Logging and Observability#

Each sequence should provide a clear GetDescription result and return errors with stable error codes. This makes deployment logs useful when startup fails.

Recommended error-code format:

BASYXCFG-COMPONENT-STEP: detailed error

Examples:

  • BASYXCFG-DB-CONNECT

  • BASYXCFG-SYSTEM-CREATETABLE

  • BASYXCFG-SCHEMA-EXECUTE

  • BASYXCFG-PATCH-EXECUTE

Testing Recommendations#

For sequence changes, add unit tests with SQL expectations where practical. Useful test cases include:

  • Missing database handle.

  • Successful execution.

  • SQL execution failure.

  • Skip behavior when initialization is already complete.

  • Patch version comparison behavior.

For database patches, prefer integration testing against PostgreSQL before release because SQL syntax and DDL behavior are database-specific.