Versioning & Upgrades

Taking a newer BigLedger release is a change to a version number in your build file, and usually a database migration that somebody has to run. This page explains what the numbers mean, what changed between the releases that exist, and how to move between them without surprises.

One version for the whole platform

akaun-api, javasdk and client-sdk are always released together and always carry the same version. “We are on BigLedger 1.2.0” is a single, checkable fact about your deployment.

Three versions are published: 1.0.0 (6 August 2026), 1.1.0 (8 October 2026) and 1.2.0 (14 October 2026). The pages in this section are read from a commit two days later than 1.2.0, so where they describe a change merged after 1.2.0, a 1.2.0 build does not have it.

Always keep the three aligned. Mixing versions — for example akaun-api:1.2.0 with javasdk:1.0.0 — is not tested and not supported.

What the numbers mean

Releases are numbered MAJOR.MINOR.PATCH in the semantic-versioning style. BigLedger has not published a commitment to follow its rules (see the callout further down), so read this table as what each number is meant to signal, not as a promise:

Change	Example	What it is meant to signal
Patch	`1.2.0` → `1.2.1`	Bug fixes only. No patch release has been published yet.
Minor	`1.1.0` → `1.2.0`	New capability, added without breaking anything. Your code still compiles.
Major	`1.2.0` → `2.0.0`	Something you may compile against has changed or been removed. Expect to make changes.

A minor number does not mean “no database change”. Both minor releases so far carried new database changesets: 1.1.0 added 42 over 1.0.0, and 1.2.0 added four more. Plan every upgrade as one that may need a migration.

A published version is never modified or replaced. Once 1.0.0 exists, its contents are fixed forever — a build that resolved it today resolves exactly the same bytes next year.

Pin an exact version

Always depend on an exact version:

implementation("com.bigledger:akaun-api:1.2.0")
implementation("com.bigledger:javasdk:1.2.0")

Do not use dynamic versions such as 1.+ or latest.release. They make your build non-reproducible and can pull in a major upgrade without warning.

How to upgrade

Find out what changed. No release notes are published beside the tags. The only written description of a release is the message on its tag commit. The 1.1.0 message says it was cut from the main branch 319 commits after 1.0.0. The 1.2.0 message describes new branding settings read from environment variables, and says that with none of them set the release behaves as 1.1.0 did. If your access covers the source repository as well as the packages, compare the two tags there (v1.1.0...v1.2.0) for everything between them. Otherwise ask your BigLedger contact. Read every version between yours and the target, not just the newest one.
Change the version in your build file — both artifacts, to the same number.
Build. Compilation errors point at anything that moved; on a minor or patch upgrade there should be none.
Test against a development database first, and get it migrated. Starting your application does not migrate any database. Database changes (Liquibase changesets) are applied in two situations only. One is when a new tenant database is created. The other is when a platform system administrator calls POST /core2/platform/dm/db-migration/run, which migrates every tenant listed in your master database, or POST /core2/platform/dm/db-migration/run/{tenantCode} for one tenant. Anyone else gets 403. The migration applies the changelog packaged inside the process that receives the call. So call it on a process already running the new version: the same call on an old process applies the old changelog and changes nothing.
Deploy, then migrate before anyone uses it. Between the moment the new version starts and the moment the migration finishes, new code is running against the old schema. Agree in advance who holds the system administrator login for your environment and who makes the call. BigLedger’s own deployments are handed to a separate repository, so whether BigLedger runs this step for an environment it hosts is not something these pages can tell you. Ask your BigLedger contact rather than assume it happens on its own.

// Before
implementation("com.bigledger:akaun-api:1.1.0")
implementation("com.bigledger:javasdk:1.1.0")

// After
implementation("com.bigledger:akaun-api:1.2.0")
implementation("com.bigledger:javasdk:1.2.0")

There is no merge step, and no BigLedger source in your repository that could conflict.

Nothing migrates on its own, and nothing rolls a migration back. The platform has no step that undoes a changeset. Once a database has been migrated for a newer release, an older application version may no longer run against it. Take a backup before migrating a production environment, and never test a new release against a production database.

Read the answer per tenant. The all-tenants call answers OK_RESPONSE even when the migration failed for one of them. Each tenant’s entry under migrations says Updated successfully. or carries a short failure code instead. Check every entry, not just the overall code.

What success looks like

Run these once the new version is deployed and the migration call has returned.

One version, three artifacts. ./gradlew dependencies --configuration runtimeClasspath | grep com.bigledger lists akaun-api, javasdk and client-sdk at the same number. A different number on any line is the mixed-version case above, and it is not supported.
The schema migrated. Before the migration, a system administrator calls GET /core2/platform/dm/db-migration/status/{tenantCode} and notes the answer: the id of the last changeset applied to that tenant’s database, and whether a migration lock is held. Call it again afterwards. On a release that carried changesets the id has changed, and the lock reads false. Without that login, whoever administers the database can read the same from the latest row of its databasechangelog table.
The application answers. One authenticated GET against an endpoint you already use returns "code": "OK_RESPONSE" — the same response it gave before the upgrade.

If step 1 fails, fix the versions before anything else; a mixed classpath produces failures that look like product bugs. If step 2 shows the same changeset id as before on a release that carried changesets, nobody has migrated that database yet. Or the call went to a process still on the old version, which applies the old changelog. If the lock reads true long after the call returned, an interrupted migration left it held. Ask the system administrator to check the server log before clearing it with POST /core2/platform/dm/db-migration/unlock/{tenantCode}. If step 3 returns CLIENT_AUTH_*, the upgrade is fine and the credential is not — see Authentication.

What is stable and what is not

Area	Treat as
REST API paths and payloads	The published surface — the API Reference is generated from the controllers of a named commit, so you can diff it release to release
Table and container classes in `client-sdk`	The published surface — `client-sdk` exists to be compiled against
Domain service and unit-of-work signatures	Usable, but internal in character; expect movement at a major release
Anything else on the classpath	Internal — may change in any release

BigLedger has not published a compatibility commitment, so nothing in the table above is a promise about what a minor release will and will not break. What is fixed is the release mechanics: the three artifacts always carry one version number, and a published version is never replaced. Build your upgrade process on compiling and testing, not on the version number alone, and ask BigLedger before you depend on a signature that is not in the API Reference or in client-sdk.

The safest code depends on documented, public entry points. The more deeply you reach into internals, the more work a major upgrade becomes.

Staying current

Every release so far has been a minor number cut from the main branch as it stood that day. There has been no patch release that carries only fixes. So each upgrade takes everything merged since your last one, migrations included.

The larger the gap between your version and the current one, the more an upgrade carries at once. Moving from 1.0.0 to 1.1.0 meant 319 commits and 42 changesets in a single migration. Moving from 1.1.0 to 1.2.0 meant four. Small, regular upgrades keep each migration short and each surprise traceable to a few commits.