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

> Understand DBX agent versioning and release process. Learn about semantic versioning, GitHub Actions, and artifact generation in this comprehensive technical guide.

- Repository: [skyler/dbx](https://github.com/t8y2/dbx)
- Tags: internals
- Published: 2026-07-10

---

**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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/.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`](https://github.com/t8y2/dbx/blob/main/.github/workflows/agents-release.yml) executes four critical jobs:

1. **bump-versions**: Detects changed driver files and updates [`agents/versions.json`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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:

```json
{
  "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:

```bash
node scripts/release.mjs agents patch

```

Force a specific version:

```bash
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:

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

```

Manual version bumping in [`agents/versions.json`](https://github.com/t8y2/dbx/blob/main/agents/versions.json):

```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`](https://github.com/t8y2/dbx/blob/main/.github/workflows/agents-release.yml) pipeline.
- **Version Tracking**: [`agents/versions.json`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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.