Terminal
Terminal/Skill
Connects Node.js apps to TiDB with the mysql2 driver, covering TLS for TiDB Cloud, pooling, transactions and parameterized queries.
By PingCAP (TiDB)
Works with
npx skills add pingcap/agent-rules --skill tidbx-javascript-mysql2Use this skill to connect to TiDB from Node.js with the mysql2 driver (promise API), configure TLS correctly for TiDB Cloud, and provide small runnable snippets you can copy into a project.
These two drivers are easy to mix up:
npm i mysql2) and uses the promise API (mysql2/promise).npm i mysql) which is callback-based, jump to the tidbx-javascript-mysqljs skill instead.For most application code (models, migrations, types), prefer an ORM/query builder:
tidbx-prismatidbx-kyselymysql2 / mysql2/promise.DATABASE_URL or TIDB_* env vars.mysql2/promise and parameterized queries (? placeholders via execute() / query()).createPool), and await pool.end() on shutdown.idleTimeout: 300_000) and keep connectionLimit small in serverless environments.multipleStatements: true unless the user explicitly needs it.DATABASE_URL (easy for deployment).TIDB_HOST/TIDB_USER/... options (handy for local/dev).npm i mysql2
If you want .env support:
npm i dotenv
DATABASE_URL (recommended)import { createConnection } from 'mysql2/promise'
const conn = await createConnection(process.env.DATABASE_URL)
const [[row]] = await conn.query('SELECT VERSION() AS v')
console.log(row.v)
await conn.end()
Notes:
Use this when you want explicit TLS config (common for TiDB Cloud Dedicated with a downloaded CA).
import { createPool } from 'mysql2/promise'
import fs from 'node:fs'
const pool = createPool({
host: process.env.TIDB_HOST,
port: Number(process.env.TIDB_PORT ?? 4000),
user: process.env.TIDB_USER,
password: process.env.TIDB_PASSWORD,
database: process.env.TIDB_DATABASE ?? 'test',
ssl: process.env.TIDB_ENABLE_SSL === 'true'
? {
minVersion: 'TLSv1.2',
ca: process.env.TIDB_CA_PATH ? fs.readFileSync(process.env.TIDB_CA_PATH) : undefined,
}
: undefined,
})
Suggested env vars:
TIDB_HOST=...
TIDB_PORT=4000
TIDB_USER=...
TIDB_PASSWORD=...
TIDB_DATABASE=test
TIDB_ENABLE_SSL=true
# Optional (commonly used for TiDB Cloud Dedicated):
TIDB_CA_PATH=/absolute/path/to/ca.pem
execute() for parameterized SQL:const [result] = await pool.execute(
'INSERT INTO players (coins, goods) VALUES (?, ?)',
[100, 100],
)
const conn = await pool.getConnection()
try {
await conn.beginTransaction()
await conn.execute('UPDATE players SET coins = coins + ? WHERE id = ?', [50, id])
await conn.commit()
} catch (e) {
await conn.rollback()
throw e
} finally {
conn.release()
}
scripts/validate_connection.mjs -- reads DATABASE_URL or TIDB_*, connects, prints SELECT VERSION(), then exits.templates/quickstart.mjs -- minimal end-to-end: connect -> create table -> insert -> query -> update -> delete.