> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Version Policy

> Understand VillageSQL's versioning scheme and MySQL compatibility matrix.

## Overview

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

## VillageSQL Versioning

VillageSQL uses [Semantic Versioning](https://semver.org/) (SemVer) to communicate the nature and impact of changes in each release.

### Version Format

Versions follow the format: **MAJOR.MINOR.PATCH**

```
0.0.1
│ │ │
│ │ └─ PATCH version
│ └─── MINOR version
└───── MAJOR version
```

### 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

<Note>
  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.
</Note>

### Development Builds

Versions with a pre-release suffix (e.g., `0.0.5-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`:

```bash theme={null}
mysqld --villagesql-allow-unsafe-dev-upgrade --datadir=/path/to/data
```

Without the flag, the server exits with an error if it detects a dev-version database:

```
Upgrading from a development version (0.0.5-dev) is not allowed. Use --villagesql-allow-unsafe-dev-upgrade to permit this.
```

With the flag, the server logs a warning and proceeds:

```
Upgrading from a development version (0.0.5-dev); --villagesql-allow-unsafe-dev-upgrade was specified.
```

The server exits with an error if the flag is specified but the current version is not a development build:

```
--villagesql-allow-unsafe-dev-upgrade specified, but current version (0.0.3) is not a development version.
```

Or if no schema upgrade is being performed:

```
--villagesql-allow-unsafe-dev-upgrade specified, but no 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](/guides/upgrade) for detailed upgrade procedures.