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.4-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:

​
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.

​
SDK Changes from 0.0.3

Protocol 2 extensions must be rebuilt. VEF Protocol 3 is stable as of v0.0.4, and the server now rejects Protocol 2 extensions at load time. Rebuild against the Protocol 3 API using the typed wrappers (StringArg, IntArg, StringResult, etc.). vef_version_t::extra type corrected to const char*. The field was unsigned char* in 0.0.3. Most extensions don’t access it directly — it’s populated by the SDK from your manifest.json version field. If yours does, remove any (unsigned char *) cast when compiling against the 0.0.4 SDK.