Skip to main content

​
Overview

VillageSQL follows clear versioning and compatibility policies to help you make informed decisions about deployment and upgrades.

​
VillageSQL Versioning

VillageSQL uses Semantic Versioning (SemVer) to communicate the nature and impact of changes in each release.

​
Version Format

Versions follow the format: MAJOR.MINOR.PATCH

​
Version Increment Rules

  • MAJOR version (e.g., 1.0.0 → 2.0.0): Breaking changes that may require code modifications or database migrations
  • MINOR version (e.g., 0.1.0 → 0.2.0): New features and functionality added in a backwards-compatible manner
  • PATCH version (e.g., 0.0.1 → 0.0.2): Backwards-compatible bug fixes and minor improvements
VillageSQL is currently in pre-1.0 development (version 0.x.x). During this phase, API and extension interfaces may change more frequently as we stabilize the platform.

​
Development Builds

Versions with a pre-release suffix (e.g., 0.0.6-dev) are development builds. The server blocks upgrades from a database initialized with a development build by default. Dev builds are not tested for upgrade compatibility and may include breaking schema or protocol changes. To permit this, start the server with --villagesql-allow-unsafe-dev-upgrade:
Without the flag, the server exits with an error if it detects a dev-version database:
With the flag, the server logs a warning and proceeds:
The server exits with an error if the flag is specified but the current version is not a development build:
Or if no schema upgrade is being performed:

​
Minimal Upgrades

Starting the server with --upgrade=MINIMAL skips upgrade steps that are not absolutely necessary. VillageSQL schema upgrades are not among the steps it skips. When a server upgrade is needed and the server is started in this mode, it logs a warning that it skipped the server upgrade, then runs the VillageSQL schema upgrades if the stored VillageSQL schema version does not match the build version.
If the VillageSQL schema upgrade fails in this mode, the server aborts startup. A datadir initialized by a development build is still refused in this mode. Start with --villagesql-allow-unsafe-dev-upgrade to permit it.

​
Code Base Changes

Every VillageSQL version is tied to a code base — the upstream fork the server builds on. For example, mysql-9.7_0.0.6 is version 0.0.6 of the mysql-9.7 code base. Version numbers from different code bases are not comparable, so a move between code bases is not a supported upgrade: you can upgrade from mysql-9.7_0.0.5 to mysql-9.7_0.0.6, but not from mysql-9.7_0.0.6 to mysql-8.4_0.0.6. A data directory records the code base of the server that created it, as villagesql_schema_version. If you start a server built from a different code base on that data directory, the startup fails and the error log names both versions:
There is no supported way to move a data directory across code bases. Keep using a server binary from the code base that created it. --upgrade=MINIMAL does not bypass this check.

​
Extension Compatibility

VillageSQL extensions are version-specific. An extension built for one version of VillageSQL may not work with another version. When upgrading VillageSQL:
  1. Check extension compatibility for the new version
  2. Update or rebuild extensions as needed
  3. Test extensions in a development environment before production deployment
See the Upgrade Guide for detailed upgrade procedures.