Merge pull request #233 from Sebastian-Webster/add-support-for-alpine-linux

Add support for Alpine Linux

Author: Sebastian-Webster

.github/workflows/os-compatibility.yml

@@ -92,6 +92,42 @@ jobs:
         if: ${{ failure() }}
         uses: actions/[email protected]
         with:
-          name: docker-fedora-${{ matrix.version }}-${{ matrix.version-requirement }}
+          name: docker-fedora-${{ matrix.version }}-${{ matrix.version-requirement }}-${{ matrix.ubuntu-version}}
           path: /tmp/mysqlmsn
-          compression-level: 0
+          compression-level: 0
+
+  alpine-docker:
+    runs-on: ubuntu-${{ matrix.ubuntu-version}}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        #There is no 10.0.0 at the time of writing, but since greater than characters are not allowed in GitHub Actions artifacts names, 9.0.1 - 10.0.0 will be used instead of >9.0.0
+        version-requirement: [ '8.4.0 - 9.0.0', '9.0.1 - 10.0.0']
+        ubuntu-version: [24.04, 24.04-arm]
+
+    container: alpine:3.22
+
+    steps:
+      - name: Install required libraries for test setup
+        run: apk add git nodejs npm
+
+      - name: Install required libraries for MySQL on alpine
+        run: apk add libaio libstdc++
+
+      - name: Checkout
+        run: git clone https://github.com/${{ github.repository }} --branch ${{ github.head_ref || github.ref_name }} --single-branch --depth 1 mysqlmsn
+
+      - name: Install packages
+        working-directory: mysqlmsn
+        run: npm ci
+
+      - name: Print available storage space
+        run: df -h
+
+      - name: Run tests
+        working-directory: mysqlmsn
+        env:
+          VERSION_REQUIREMENT: ${{ matrix.version-requirement }}
+          X_OFF: true
+        run: npm run os-compat:ci

README.md

@@ -87,8 +87,8 @@ The name of the user to use to login to the database
 If on Windows, this is the name of the named pipe that MySQL is listening on. If not on Windows, this is the path to the socket that MySQL is listening on.
 - `xSocket: string`
 If on Windows, this is the name of the named pipe that the MySQL X Plugin is listening on. If not on Windows, this is the path that the MySQL X Plugin is listening on. If ```options.xEnabled``` is set to "OFF", this value will be an empty string.
-- `mysql: {version: string, versionIsInstalledOnSystem: boolean, xPluginIsEnabled: boolean}`
-An object with three properties. ```version``` is the version of MySQL used to create the database. ```versionIsInstalledOnSystem``` will be true if the MySQL version used is already installed on the system and false if the version had to be downloaded from MySQL's CDN. ```xPluginIsEnabled``` will be true if ```options.xEnabled``` is set to "FORCE", and will be false if ```options.xEnabled``` is set to "OFF".
+- `mysql: {version: string, versionIsInstalledOnSystem: boolean}`
+An object with three properties. ```version``` is the version of MySQL used to create the database. ```versionIsInstalledOnSystem``` will be true if the MySQL version used is already installed on the system and false if the version had to be downloaded from MySQL's CDN.
 - `stop: () => Promise<void>`
 The method to stop the database. The returned promise resolves when the database has successfully stopped.
 
@@ -194,4 +194,4 @@ Description: The MySQL binary architecture to execute. MySQL does not offer serv
 
 Default: "FORCE"
 
-Description: This option follows the convention set out by the [MySQL Documentation](https://dev.mysql.com/doc/refman/en/plugin-loading.html). If set to "OFF", the MySQL X Plugin will not initialise. If set to "FORCE", the MySQL Server will not start up without a successful initialisation of the plugin, meaning that it's guaranteed the server will start up with MySQL X enabled. If the MySQL X initialisation fails, the server will not start up.
+Description: This option follows the convention set out by the [MySQL Documentation](https://dev.mysql.com/doc/refman/en/plugin-loading.html). If set to "OFF", the MySQL X Plugin will not initialise. If set to "FORCE", the MySQL Server will either start up with the MySQL X Plugin guaranteed to have successfully initialised, or if initialisation fails, the server will fail to start up.

dist/src/libraries/Version.js

@@ -85,16 +85,26 @@ function getBinaryURL(versionToGet = "x", currentArch) {
         const minVersion = minVersions[0];
         throw `Your operating system is too out of date to run a version of MySQL that fits the following requirement: ${versionToGet}. The oldest version for your operating system that you would need to get a version that satisfies the version requirement is ${minVersion} but your current operating system is ${coercedOSRelease.version}. Please try changing your MySQL version requirement, updating your OS to a newer version, or if you believe this is a bug, please report this on GitHub.`;
     }
-    if (process.platform === 'linux' && LinuxOSRelease_1.default.NAME === 'Ubuntu' && LinuxOSRelease_1.default.VERSION_ID >= '24.04') {
-        //Since Ubuntu >= 24.04 uses libaio1t64 instead of libaio, this package has to copy libaio1t64 into a folder that MySQL looks in for dynamically linked libraries with the filename "libaio.so.1".
-        //I have not been able to find a suitable folder for libaio1t64 to be copied into for MySQL < 8.0.4, so here we are filtering all versions lower than 8.0.4 since they fail to launch in Ubuntu 24.04.
-        //If there is a suitable filepath for libaio1t64 to be copied into for MySQL < 8.0.4 then this check can be removed and these older MySQL versions can run on Ubuntu.
-        //Pull requests are welcome for adding >= Ubuntu 24.04 support for MySQL < 8.0.4.
-        //A way to get MySQL running on Ubuntu >= 24.04 is to symlink libaio1t64 to the location libaio would be. It is not suitable for this package to be doing that automatically, so instead this package has been copying libaio1t64 into the MySQL binary folder.
-        selectedVersions = selectedVersions.filter(v => !(0, semver_1.lt)(v, '8.0.4'));
-    }
-    if (selectedVersions.length === 0) {
-        throw `You are running a version of Ubuntu that is too modern to run any MySQL versions with this package that match the following version requirement: ${versionToGet}. Please choose a newer version of MySQL to use, or if you believe this is a bug please report this on GitHub.`;
+    const isOnAlpineLinux = process.platform === 'linux' && LinuxOSRelease_1.default.NAME === 'Alpine Linux';
+    if (process.platform === 'linux') {
+        if (LinuxOSRelease_1.default.NAME === 'Ubuntu' && LinuxOSRelease_1.default.VERSION_ID >= '24.04') {
+            //Since Ubuntu >= 24.04 uses libaio1t64 instead of libaio, this package has to copy libaio1t64 into a folder that MySQL looks in for dynamically linked libraries with the filename "libaio.so.1".
+            //I have not been able to find a suitable folder for libaio1t64 to be copied into for MySQL < 8.0.4, so here we are filtering all versions lower than 8.0.4 since they fail to launch in Ubuntu 24.04.
+            //If there is a suitable filepath for libaio1t64 to be copied into for MySQL < 8.0.4 then this check can be removed and these older MySQL versions can run on Ubuntu.
+            //Pull requests are welcome for adding >= Ubuntu 24.04 support for MySQL < 8.0.4.
+            //A way to get MySQL running on Ubuntu >= 24.04 is to symlink libaio1t64 to the location libaio would be. It is not suitable for this package to be doing that automatically, so instead this package has been copying libaio1t64 into the MySQL binary folder.
+            selectedVersions = selectedVersions.filter(v => !(0, semver_1.lt)(v, '8.0.4'));
+            if (selectedVersions.length === 0) {
+                throw `You are running a version of Ubuntu that is too modern to run any MySQL versions with this package that match the following version requirement: ${versionToGet}. Please choose a newer version of MySQL to use, or if you believe this is a bug please report this on GitHub.`;
+            }
+        }
+        else if (isOnAlpineLinux) {
+            //https://github.com/Sebastian-Webster/mysql-server-musl-binaries only has support for v8.4.x and 9.x binaries
+            selectedVersions = selectedVersions.filter(v => (0, semver_1.satisfies)(v, '8.4.x') || (0, semver_1.satisfies)(v, '9.x'));
+            if (selectedVersions.length === 0) {
+                throw 'mysql-memory-server has detected you are running this package on Alpine Linux. The source for MySQL with musl libc only provides binaries for MySQL 8.4.x and 9.x and as such only those versions can be used with this package. Please use 8.4.x or 9.x.';
+            }
+        }
     }
     //Sorts versions in descending order
     selectedVersions.sort((a, b) => a < b ? 1 : -1);
@@ -110,6 +120,9 @@ function getBinaryURL(versionToGet = "x", currentArch) {
         const macOSVersionNameKey = MySQLmacOSVersionNameKeys.find(range => (0, semver_1.satisfies)(selectedVersion, range));
         fileLocation = `${(0, semver_1.major)(selectedVersion)}.${(0, semver_1.minor)(selectedVersion)}/mysql-${selectedVersion}${isRC ? '-rc' : isDMR ? '-dmr' : ''}-${constants_1.MYSQL_MACOS_VERSIONS_IN_FILENAME[macOSVersionNameKey]}-${currentArch === 'x64' ? 'x86_64' : 'arm64'}.tar.gz`;
     }
+    else if (isOnAlpineLinux) {
+        fileLocation = `https://github.com/Sebastian-Webster/mysql-server-musl-binaries/releases/download/current/mysql-musl-${selectedVersion}-${currentArch === 'x64' ? 'x86_64' : 'arm64'}.tar.gz`;
+    }
     else if (currentOS === 'linux') {
         const glibcObject = constants_1.MYSQL_LINUX_GLIBC_VERSIONS[currentArch];
         const glibcVersionKeys = Object.keys(glibcObject);
@@ -124,8 +137,12 @@ function getBinaryURL(versionToGet = "x", currentArch) {
         const fileExtension = constants_1.MYSQL_LINUX_FILE_EXTENSIONS[currentArch][fileExtensionKey];
         fileLocation = `${(0, semver_1.major)(selectedVersion)}.${(0, semver_1.minor)(selectedVersion)}/mysql-${selectedVersion}${isRC ? '-rc' : isDMR ? '-dmr' : ''}-linux-${minimalInstallAvailable !== 'no-glibc-tag' ? `glibc${glibcVersion}-` : ''}${currentArch === 'x64' ? 'x86_64' : 'aarch64'}${minimalInstallAvailable !== 'no' && (process.arch !== 'arm64' ? true : (0, semver_1.satisfies)(selectedVersion, constants_1.MYSQL_LINUX_MINIMAL_INSTALL_AVAILABLE_ARM64)) ? `-minimal${(0, semver_1.satisfies)(selectedVersion, constants_1.MYSQL_LINUX_MINIMAL_REBUILD_VERSIONS) ? '-rebuild' : ''}` : ''}.tar.${fileExtension}`;
     }
+    else {
+        throw 'You are running this package on an unsupported OS. Please use either Windows, macOS, or a Linux-based OS.';
+    }
     return {
         version: selectedVersion,
-        url: constants_1.archiveBaseURL + fileLocation
+        url: isOnAlpineLinux ? fileLocation : (constants_1.archiveBaseURL + fileLocation),
+        hostedByOracle: !isOnAlpineLinux // Only the Alpine Linux binaries are not hosted on the MySQL CDN.
     };
 }

dist/types/index.d.ts

@@ -58,6 +58,7 @@ export type DownloadedMySQLVersion = {
 export type BinaryInfo = {
     url: string;
     version: string;
+    hostedByOracle: boolean;
 };
 export type OptionTypeChecks = {
     [key in keyof Required<ServerOptions>]: {

docs/SUPPORTED_MYSQL_DOWNLOADS.md

@@ -8,14 +8,18 @@
 - Windows
 - Linux
 
-*```mysql-memory-server``` gets tested on Ubuntu 22.04 (x64 and arm64) and 24.04 (x64 and arm64), Fedora 41 (x64 and arm64) and 42 (x64 and arm64), macOS 13 (x64), 14 (arm64), and 15 (arm64), Windows 11 (arm64), and Windows Server 2022 (x64) and 2025 (x64). Linux distributions and Windows and macOS versions other than the ones tested may or may not work and are not guaranteed to work with this package.*
+*```mysql-memory-server``` gets tested on Ubuntu 22.04 (x64 and arm64) and 24.04 (x64 and arm64), Fedora 41 (x64 and arm64) and 42 (x64 and arm64), Alpine 3.22 (x64 and arm64), macOS 13 (x64), 14 (arm64), and 15 (arm64), Windows 11 (arm64), and Windows Server 2022 (x64) and 2025 (x64). Linux distributions and Windows and macOS versions other than the ones tested may or may not work and are not guaranteed to work with this package.*
 
 ## Binaries not available for download
 
 - Versions 8.0.29, 8.0.38, 8.4.1, and 9.0.0 are not available for download for any operating systems as MySQL removed them from the CDN due to critical issues.
 
 - Versions 5.7.32 - 5.7.44 are not available for download only for macOS systems as MySQL stopped supporting macOS Mojave starting from 5.7.32 for the rest of the 5.7.x line. As a result, those versions are not available for macOS in the MySQL CDN.
 
+## Alpine Linux Limitations
+
+Only MySQL versions 8.4.x and 9.x can be downloaded and ran with this package on Alpine Linux. The binaries for Alpine Linux are sourced from [Sebastian-Webster/mysql-server-musl-binaries](https://github.com/Sebastian-Webster/mysql-server-musl-binaries) on GitHub as Oracle does not support MySQL on musl-based Linux distributions. That repository only has support for MySQL 8.4.x and 9.x. If you discover any issues with MySQL (and not this package) when you are running this on Alpine Linux, please report the issue on that repository and not the ```mysql-memory-server``` one. The MySQL X Plugin is also not available when running on Alpine Linux due to compilation errors for musl.
+
 ## Native Binary Architectures
 
 *Architectures used can be overridden by the ```arch``` option provided your OS and system supports running applications that use those architectures.*
@@ -56,7 +60,7 @@ Windows - No documented maximum version
 
 macOS - No documented maximum version
 
-Fedora Linux - No documented maximum version
+Fedora & Alpine Linux - No documented maximum version
 
 Ubuntu Linux:
 
@@ -86,4 +90,6 @@ Ubuntu Linux:
 
 Fedora Linux: ```libaio1``` package and ```tar``` package
 
-*Document last updated in v1.11.0*
+Alpine Linux: ```libstdc++``` package and ```libaio``` package
+
+*Document last updated in v1.12.0*

package.json

@@ -18,7 +18,7 @@
   "scripts": {
     "test": "jest --verbose --colors",
     "test:ci": "jest tests/ci --setupFilesAfterEnv ./ciSetup.js --verbose --colors",
-    "os-compat:ci": "jest --setupFilesAfterEnv ./ciSetup.js --verbose --colors --runTestsByPath tests/versions.test.ts"
+    "os-compat:ci": "jest tests/versions.test.ts --setupFilesAfterEnv ./ciSetup.js --verbose --colors"
   },
   "engines": {
     "node": ">=16.6.0",

src/constants.ts

@@ -122,8 +122,8 @@ export const OPTION_TYPE_CHECKS: OptionTypeChecks = {
 } as const;
 
 export const MIN_SUPPORTED_MYSQL = '5.7.19';
-export const downloadsBaseURL = 'https://cdn.mysql.com//Downloads/MySQL-'
-export const archiveBaseURL = 'https://cdn.mysql.com/archives/mysql-'
+export const MySQLCDNDownloadsBaseURL = 'https://cdn.mysql.com//Downloads/MySQL-'
+export const MySQLCDNArchivesBaseURL = 'https://cdn.mysql.com/archives/mysql-'
 // Versions 8.0.29, 8.0.38, 8.4.1, and 9.0.0 have been purposefully left out of this list as MySQL has removed them from the CDN due to critical issues.
 export const DOWNLOADABLE_MYSQL_VERSIONS = [
     '5.7.19', '5.7.20', '5.7.21', '5.7.22', '5.7.23', '5.7.24', '5.7.25', '5.7.26', '5.7.27', '5.7.28', '5.7.29', '5.7.30', '5.7.31', '5.7.32', '5.7.33', '5.7.34', '5.7.35', '5.7.36', '5.7.37', '5.7.38', '5.7.39', '5.7.40', '5.7.41', '5.7.42', '5.7.43', '5.7.44',

src/index.ts

@@ -5,6 +5,7 @@ import { BinaryInfo, InternalServerOptions, ServerOptions } from '../types'
 import getBinaryURL from './libraries/Version'
 import { downloadBinary } from './libraries/Downloader'
 import { MIN_SUPPORTED_MYSQL, DEFAULT_OPTIONS_KEYS, OPTION_TYPE_CHECKS, DEFAULT_OPTIONS } from './constants'
+import etcOSRelease from './libraries/LinuxOSRelease'
 
 export async function createDB(opts?: ServerOptions) {
     const suppliedOpts = opts || {};
@@ -41,7 +42,7 @@ export async function createDB(opts?: ServerOptions) {
         throw `A version of MySQL is installed on your system that is not supported by this package. If you want to download a MySQL binary instead of getting this error, please set the option "ignoreUnsupportedSystemVersion" to true.`
     }
 
-    logger.log('Version currently installed:', version)
+    logger.log('Version currently installed:', version, 'Platform:', process.platform, 'etcOSRelease:', etcOSRelease)
     if (version === null || (options.version && !satisfies(version.version, options.version)) || unsupportedMySQLIsInstalled) {
         let binaryInfo: BinaryInfo;
         let binaryFilepath: string;
@@ -55,7 +56,7 @@ export async function createDB(opts?: ServerOptions) {
         }
 
         logger.log('Running downloaded binary')
-        return await executor.startMySQL(options, {path: binaryFilepath, version: binaryInfo.version, installedOnSystem: false})
+        return await executor.startMySQL(options, {path: binaryFilepath, version: binaryInfo.version, installedOnSystem: false, xPluginSupported: binaryInfo.xPluginSupported})
     } else {
         logger.log(version)
         return await executor.startMySQL(options, version)