Registry / database / gridsome-source-mysql

gridsome-source-mysql

library1.5.4jsnpmunverified

Gridsome source plugin to load data directly from a MySQL database. Current stable version is 1.5.4. It allows specifying SQL queries to fetch data as content types, with support for image downloading/optimization (including comma-separated URLs), relations via foreign key naming conventions (`xxx_id`, `xxx_ids`), dynamic routes, and JSON parsing. Compared to using a CMS or other source plugins, it provides direct database access for custom queries, regex-based image filename cleanup, and sub-query support. Release cadence is irregular; updates occur based on community contributions.

database

npm install gridsome-source-mysql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRIDSOME-SOURCE-MY

gridsome-source-mysql

databasejavascriptv1.5.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ module.exports = { plugins: [{ use: 'gridsome-source-mysql', options: { connection: {...}, queries: [...] } }] }

✗ import gridsomesourcemysql from 'gridsome-source-mysql'

This is a Gridsome plugin, not a library for direct import. Configure in gridsome-config.js using CJS with 'use' key.

Configures Gridsome to use the MySQL source plugin with a connection and a simple Post query.

// gridsome-config.js module.exports = { plugins: [ { use: 'gridsome-source-mysql', options: { connection: { host: 'localhost', port: 3306, user: 'root', password: process.env.DB_PASSWORD ?? 'secret', database: 'my_db' }, debug: false, ignoreImages: false, imageDirectory: 'sql_images', queries: [ { name: 'Post', path: 'title', sql: 'SELECT id, title, content, author_id FROM posts', images: [] } ] } } ] }

Debug

Known issues

gotchaThe 'id' field from MySQL tables is automatically renamed to 'mysqlId'. If your queries return a column named 'id', it will be available as 'mysqlId' in GraphQL, not 'id'.

fix

Access the MySQL primary key as 'mysqlId' in your GraphQL queries, or alias the column in SQL (e.g., SELECT id AS original_id).

affects: >=0.0.0

gotchaRelation fields must follow the naming convention 'xxx_id' (single) or 'xxx_ids' (comma-delimited). If you use a different pattern, relations won't be detected automatically.

fix

Rename your foreign key columns to match the pattern, e.g., 'author_id' for a relation to the 'Author' content type.

affects: >=0.0.0

gotchaThe 'args' option in queries is required when using placeholders in SQL; if omitted, the query will fail with placeholder count mismatch.

fix

Provide an 'args' array with the same number of elements as '?' placeholders in your SQL string.

affects: >=0.0.0

breakingIn version 1.5.0, the option 'regex' was introduced. Older versions do not support this option, so using it will cause an error.

fix

Upgrade to version 1.5.0 or later to use the 'regex' option.

affects: <1.5.0

gotchaImage columns specified in the 'images' array must contain URIs that are directly resolvable; the plugin will attempt to download and optimize them. If the column contains relative paths or non-URL strings, the download may fail silently.

fix

Ensure image column values are absolute URLs or paths reachable from the build environment.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'mysql2'

The package 'mysql2' is not installed or not found when the plugin tries to connect.

fix

Install it explicitly: npm install mysql2

ER_PARSE_ERROR: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near '?' at line 1

Placeholder '?' in SQL is not properly replaced because the 'args' array is missing or mismatched.

fix

Ensure the 'args' option contains exactly the same number of values as '?' placeholders in your SQL string.

Error: Cannot use 'id' as a content type field, renamed to mysqlId. Please use 'mysqlId' in your queries.

The plugin automatically renames the 'id' column from MySQL to 'mysqlId' to avoid conflict with Gridsome's internal 'id' field.

fix

In GraphQL queries, access the MySQL primary key field as 'mysqlId' instead of 'id'.

Upgrade

Version history

1.5.4latest on npm

Audit

Dependencies

gridsomerequiredPeer dependency; plugin requires Gridsome framework at runtime.

mysql2optionalUsed for MySQL database connection. If not installed separately, the plugin may pull it automatically but can cause version conflicts.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/u12206050/gridsome-source-mysql ↗

packagegridsome-source-mysql ↗

homepagehttps://github.com/u12206050/gridsome-source-mysql#readme ↗