STX Spatial Plugin for MySQL

MySQL plugin that adds spatial functions (STX_*) powered by Boost.Geometry and GEOS. Our approach: implement functions broadly first, then refine through thorough testing. Motto: "Imperfect beats unavailable."

Provides GIS functions missing from MySQL, including distance-based queries, spatial relationships (DE-9IM), coordinate transformations, I/O format conversions, and more. Supports Cartesian (including projected CRS such as UTM) and Geographic (WGS84, etc.) coordinate systems.

For testing status and known limitations of each function, see CHECKLIST.md.

See Function Reference for full documentation.

Daemon plugins are tied to the exact MySQL version (patch level included), so each MySQL version needs its own .so. Supported MySQL tracks:

• LTS: MySQL 9.7.x (a new .so is built for each patch release)
• Innovation: calendar-versioned releases starting July 2026 (26.7 → 26.10 → 27.1 → …, quarterly)
• MySQL 9.6 support ended with plugin v0.2.0 — 9.6 users should stay on that release

For building from source: MySQL source tree (headers + Boost), g++ with C++17 support, and a MySQL binary installation for the plugin directory. Multi-version release builds use Docker (see Build).

├── mysql-buildkits/           # per-MySQL-version source + libmysqlservices.a kits (auto-generated)
│   ├── boost_1_87_0/          #   shared Boost dir (populated from the first extracted MySQL source)
│   ├── 9.7.2/                 #   ~300MB per version (source tree minus mysql-test/, plus compiled libmysqlservices.a)
│   └── 26.7.0/
├── build-artifacts/           # per-version .so outputs from docker-build.sh
│   └── 26.7.0/spatial_plugin-mysql-26.7.0-glibc-{2.34,2.39}.so
├── mysql-<DEV_VER>/           # native dev install (MySQL binary). Current dev
├── mysql-<DEV_VER>.source/    #   version defaults to 9.7.0 (legacy dir: mysql970/);
│                              #   override with DEV_MYSQL_VER=X.Y.Z on `make`
└── plugins/
    ├── gis_lib/               # shared GIS library (WKB parser, geometry types)
    └── spatial_plugin/        # plugin source
        ├── spatial_plugin.cc
        ├── plugin_version.h
        ├── Makefile
        ├── extract-buildkit.sh
        ├── docker-build.sh
        ├── docker-test.sh
        ├── test.sql
        └── docs/function_reference.md

mysql-buildkits/, build-artifacts/, and the mysql-<version>*/ dev installs are not committed to this repository. Download the MySQL source tarball you need from MySQL Downloads; extract-buildkit.sh fetches it automatically when building for a version that has no local buildkit yet.

Two variants are built per MySQL version, differing only in target glibc:

Check the Releases page for the current MySQL versions we ship binaries for. Each .so reports the MySQL version it was built against via SHOW STATUS LIKE 'spatial_plugin_built_for'; it must match your server or INSTALL PLUGIN will fail.

Pick the binary matching your MySQL version and your system's glibc (check with ldd --version; a lower-glibc binary also runs on newer systems). Copy it as-is to the MySQL plugin directory and load it by file name:

INSTALL PLUGIN spatial_plugin SONAME 'spatial_plugin-mysql-26.7.0-glibc-2.34.so';

-- Verify the .so matches your server:
SHOW STATUS LIKE 'spatial_plugin_%';

Legacy assets in v0.3.0 — the two files without a MySQL version in the name (spatial_plugin-glibc-2.39.so, spatial_plugin-glibc-2.34.so) were the initial build for MySQL 9.7.0. Newer MySQL versions ship under the versioned name above. For MySQL 9.6, stay on plugin v0.2.0.

Native dev build (compiles against the sibling mysql-<DEV_MYSQL_VER>/ install):

cd plugins/spatial_plugin
make            # compile spatial_plugin.so against DEV_MYSQL_VER (default 9.7.0)
make install    # copy .so to MySQL plugin directory

# Build against a different local MySQL install:
make DEV_MYSQL_VER=26.7.0

DEV_MYSQL_VER defaults to 9.7.0; the Makefile looks for ../../mysql-<DEV_MYSQL_VER>/ first and falls back to the legacy dotted-out name (mysql970/ for 9.7.0) if only the legacy dir is present. Set DEV_MYSQL_VER on the make command line or in local.mk.

Multi-version release build via Docker (any supported MySQL version):

cd plugins/spatial_plugin
make build-mysql   MYSQL_VER=26.7.0   # extract buildkit, build both glibc variants, run test suite
make release-mysql MYSQL_VER=26.7.0   # upload .so files to the current GitHub release (--clobber not used)

extract-buildkit.sh downloads and processes the MySQL source tarball on first use for a given version (~5 minutes; cached under mysql-buildkits/.cache/). Subsequent make build-mysql runs for the same version skip extraction.

Load the .so by the file name you copied into the MySQL plugin directory:

-- Pre-built binary (recommended): file name embeds MySQL version + glibc floor
INSTALL PLUGIN spatial_plugin SONAME 'spatial_plugin-mysql-26.7.0-glibc-2.34.so';

-- Or, when using the native dev build's `make install` output:
INSTALL PLUGIN spatial_plugin SONAME 'spatial_plugin.so';

All 62 functions are registered automatically. No CREATE FUNCTION needed.

-- Verify — spatial_plugin_built_for shows the exact MySQL version the .so was compiled against
SELECT * FROM performance_schema.user_defined_functions WHERE UDF_NAME LIKE 'stx_%';
SHOW STATUS LIKE 'spatial_plugin_%';

-- Perimeter of a polygon (geographic, result in meters)
SELECT STX_Perimeter(ST_GeomFromText('POLYGON((139 35,140 35,140 36,139 36,139 35))', 4326));

-- Is point within 1km of another point?
SELECT STX_Dwithin(
    ST_GeomFromText('POINT(139.7 35.7)', 4326),
    ST_GeomFromText('POINT(139.71 35.71)', 4326),
    1000
);

-- Rotate polygon 45 degrees around its centroid
SELECT STX_Rotate(
    ST_GeomFromText('POLYGON((0 0,10 0,10 10,0 10,0 0))'),
    PI()/4,
    ST_GeomFromText('POINT(5 5)')
);

-- DE-9IM spatial relationship
SELECT STX_Relate(
    ST_GeomFromText('POINT(5 5)'),
    ST_GeomFromText('POLYGON((0 0,10 0,10 10,0 10,0 0))')
);

-- Convert to KML
SELECT STX_Askml(ST_GeomFromText('POINT(35.6 139.7)', 4326));
-- <Point><coordinates>139.7,35.6</coordinates></Point>

-- EWKT round-trip
SELECT ST_AsText(STX_Geomfromewkt('SRID=4326;POINT(139.7 35.6)'));
-- POINT(35.6 139.7)

Functions returning geometry use STRING_RESULT (MySQL UDF limitation). The binary data is valid geometry (SRID + WKB) and works directly with other spatial functions:

SELECT ST_AsText(STX_Translate(ST_GeomFromText('POINT(1 2)'), 10, 20));
-- POINT(11 22)

make test       # Run test suite (361 tests)

GNU General Public License v2.0