How DBX Agent Versioning and Release Process Works: A Complete Technical Guide

DBX agents are versioned and released through a three-stage automation pipeline that uses semantic versioning tags, GitHub Actions workflows, and per-driver version tracking in agents/versions.json to produce cross-platform artifacts.

The DBX project (t8y2/dbx) maintains a sophisticated release pipeline for its database agent components. Understanding how the DBX agent versioning and release process works is essential for contributors and operators who need to publish new driver versions or troubleshoot build failures. This guide examines the actual implementation in the source code, from the release.mjs script that initiates tags to the Gradle-based artifact generation.

The Three-Stage Release Pipeline

The release process is orchestrated through three distinct stages that transform source code changes into published artifacts. Each stage is fully automated and traceable through the repository's GitHub Actions.

Stage 1: Tag Resolution with release.mjs

The process begins in scripts/release.mjs, which contains the resolveAgentTag function responsible for determining the next version identifier. The script identifies the most recent tag matching the agents-v* prefix (e.g., agents-v0.1.23) and calculates the next version based on two input methods:

• Automatic bumping: Supplying patch, minor, or major increments the corresponding semantic version component via resolveReleaseVersion
• Explicit versioning: Providing a complete version string (e.g., 1.4.0) through normalizeExplicitVersion

The function parses existing tags using parseVersion and assembles the final tag string (agents-vX.Y.Z) while preventing collisions through the tagExists check.

Stage 2: Automated Tag Creation and Push

Once the target version is determined, the script executes git tag agents-vX.Y.Z && git push origin agents-vX.Z (around line 80 in release.mjs). This push operation triggers the Agents Release workflow defined in .github/workflows/agents-release.yml. The script includes safety checks to prevent overwriting existing tags, ensuring that each release is immutable and traceable.

Stage 3: The Agents-Release Workflow Execution

The workflow defined in .github/workflows/agents-release.yml executes four critical jobs:

1. bump-versions: Detects changed driver files and updates agents/versions.json using the .github/scripts/bump-agent-versions.mjs helper
2. build-agents: Executes ./gradlew shadowJar to produce shaded JARs for every driver
3. build-native: Cross-compiles native binaries for drivers like Oracle and Xugu using Go-based build scripts
4. build-jre: Generates minimal JREs via jlink for each supported Java version

All artifacts are published as workflow artifacts for downstream consumption.

How Version Bumping Works in DBX

The versioning system supports two primary workflows for determining the next release number.

Automatic Semantic Versioning When you run the release script with patch, minor, or major, the system parses the latest existing tag and increments only the specified component. This ensures that bug fixes, new features, and breaking changes follow semantic versioning principles without manual calculation.

Explicit Version Control For specific release requirements, you can provide an exact version string. The normalizeExplicitVersion function handles both bare version numbers (e.g., 1.4.0) and full tag names (e.g., agents-v1.4.0), normalizing them to the standard agents-v prefix format.

Per-Driver Version Tracking

Individual driver versions are maintained in agents/versions.json, which serves as the single source of truth for the bundled components. This JSON file maps driver names to their semantic versions:

{
  "postgresql": "0.1.27",
  "mysql": "0.1.31",
  "oracle": "0.2.1"
}

The bump-versions job automatically updates this file when it detects changes in driver source code, ensuring that the built artifacts contain accurate metadata about their internal component versions. This file is committed back to the repository during the workflow execution, maintaining a permanent record of which driver versions shipped with each agent release.

Building and Publishing Artifacts

The artifact generation process uses Gradle configurations defined in agents/build.gradle and individual agents/drivers/*/build.gradle files.

Java Agent Compilation The shadowJar task produces shaded JARs containing all dependencies, ensuring that each driver agent runs in an isolated classpath without external dependency conflicts.

Native Binary Compilation For drivers requiring native components (such as Oracle and Xugu), the workflow executes Go-based build scripts that cross-compile binaries for multiple target platforms. These binaries are attached to the workflow run as downloadable artifacts.

JRE Generation The build-jre job uses jlink to create minimal Java Runtime Environments tailored to the agents' requirements. These custom JREs reduce the deployment footprint compared to full JDK installations.

Practical Release Commands

Trigger a standard patch release:

node scripts/release.mjs agents patch

Force a specific version:

node scripts/release.mjs agents 1.4.0

# Or with full tag syntax:

node scripts/release.mjs agents agents-v1.4.0

Preview changes without execution:

node scripts/release.mjs agents minor --dry-run

Manual version bumping in agents/versions.json:

{
  "postgresql": "0.1.28",
  "mysql": "0.1.31"
}

After editing the JSON file, commit the changes and run the release script to incorporate the updated driver versions into the new release.

Summary

• Entry Point: The scripts/release.mjs script controls the entire process through the resolveAgentTag function, supporting both automatic semantic bumps and explicit version strings.
• Workflow Trigger: Pushing an agents-v* tag automatically initiates the .github/workflows/agents-release.yml pipeline.
• Version Tracking: agents/versions.json maintains per-driver versions, updated automatically by .github/scripts/bump-agent-versions.mjs during the release process.
• Artifact Generation: The workflow produces shaded JARs via Gradle shadowJar, native binaries for Oracle/Xugu drivers, and minimized JREs via jlink.
• Safety Mechanisms: The tagExists check prevents duplicate releases, ensuring each version is immutable and traceable.

Frequently Asked Questions

How does the DBX release script prevent duplicate tags?

The release.mjs script includes a tagExists validation that queries the Git repository before creating any new tags. If the calculated agents-vX.Y.Z tag already exists locally or remotely, the script aborts with an error message, preventing accidental overwrites of existing releases and ensuring version uniqueness.

What happens if I need to release a specific driver update without bumping the global agent version?

You can manually update the specific driver version in agents/versions.json (e.g., changing "postgresql" from "0.1.27" to "0.1.28"), commit the change, and run the release script. The bump-versions job detects the modified versions.json and incorporates the new driver version into the release artifacts while maintaining the semantic versioning of the overall agent package.

Where are the native binaries for Oracle and Xugu drivers built?

Native binaries are constructed in the build-native job of the agents-release workflow. This job uses Go-based build scripts located in the driver-specific directories under agents/drivers/ to cross-compile platform-specific binaries. The resulting binaries are published as workflow artifacts alongside the Java JARs.

Can I test the release process without actually creating a tag?

Yes, the release.mjs script supports a --dry-run flag that simulates the entire process without executing git tag or git push. This allows you to verify the calculated version, confirm the tag name format, and validate that no existing tags would conflict, providing a safe way to test your release parameters before making permanent changes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}