Architecture
Last updated
This page shows in one overview diagram which layers make up
MySQLPool and how they connect.graph TB
App[Application] --> Init["init()"]
Init --> Cfg["Config Resolution: object / env vars"]
Cfg --> RP[(Read Pool)]
Cfg --> WP[(Write Pool)]
App --> QB["Chainable Query Builder: static state"]
App --> Raw["read() / write()"]
QB --> Exec["query() Executor: slow query log"]
Raw --> Exec
Exec --> RP
Exec --> WP- graph TB
- App[Application] --> Init["init()"]
- Init --> Cfg["Config Resolution: object / env vars"]
- Cfg --> RP[(Read Pool)]
- Cfg --> WP[(Write Pool)]
- App --> QB["Chainable Query Builder: static state"]
- App --> Raw["read() / write()"]
- QB --> Exec["query() Executor: slow query log"]
- Raw --> Exec
- Exec --> RP
- Exec --> WP
Layers
| Layer | Location | Responsibility |
|---|---|---|
| Config resolution | init(), correctConfig() (src/MySQLPool.ts:40-97) | Picks read and write configs by priority, fills defaults, creates and verifies mysql2/promise pools |
| Query builder | table() through increase() (src/MySQLPool.ts:117-227) | Accumulates columns, conditions, joins, sorting, and paging in static fields |
| SQL assembly | get(), insert(), update(), upsert() (src/MySQLPool.ts:229-360) | Turns the accumulated state into SQL and bindings |
| Executor | query() (src/MySQLPool.ts:362-392) | Picks the pool, checks out a connection, runs, times, and releases it |
| Raw entry points | read(), write() (src/MySQLPool.ts:394-406) | Run hand-written SQL on a fixed pool |
| Lifecycle | close() (src/MySQLPool.ts:99-115) | Close the pools |
Cross-Cutting Principles
| Principle | Detail |
|---|---|
| Single database exit | Every SQL statement passes through query(), so slow query logging and connection release live in one place |
| Process-wide singleton | MySQLPool has only static members and a private constructor, so the whole process shares one pair of pools and one builder state |
Where It Sits Among Node.js MySQL Libraries
| Library | What it is | How MySQLPool relates |
|---|---|---|
| mysql2 | MySQL driver for Node.js | MySQLPool is built on it: both pools come from mysql2/promise createPool(), and raw results and errors are mysql2's own |
| Knex.js | SQL query builder for PostgreSQL, MySQL, SQLite, SQL Server, and other databases | MySQLPool targets MySQL only and keeps two pools, picking read or write per call through table(name, target), read(), and write() |
| Sequelize | ORM with models, associations, and read replication | MySQLPool has no models or associations; it is a static class whose chain goes straight from table() to SQL |
| Kysely | Type-safe SQL query builder for TypeScript | MySQLPool takes column names as plain strings and types results only through the get<T>() generic, with no compile-time schema checking |
Further Reading
- Per-module diagrams, data flow, and state machine: doc/architecture.md
- Read-Write Pools, Builder State