atlas-mysql

library2.1.0jsnpmunverified

Atlas MySQL is a type-safe MySQL ORM for Node.js built on top of mysql2. Current stable version is 2.1.0, released with monthly maintenance updates. It provides a fluent query builder, transaction support, schema introspection, and structured logging. Unlike raw mysql2, Atlas enforces TypeScript types at compile time, reducing runtime errors. It supports connection pooling, prepared statements, and migrations. The library ships TypeScript declarations and works with ESM and CJS runtimes. It is designed for developers who want type safety without sacrificing performance or flexibility.

database

npm install atlas-mysql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ATLAS-MYSQL

atlas-mysql

databasejavascriptv2.1.0

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.

AtlasClient

✓ import { AtlasClient } from 'atlas-mysql'

✗ const AtlasClient = require('atlas-mysql').AtlasClient

ESM import recommended. CJS require works but not all exports may be accessible.

AtlasDatabase

✓ import { AtlasDatabase } from 'atlas-mysql'

✗ const { AtlasDatabase } = require('atlas-mysql')

Named export. Default export is the client instance factory.

atlas

✓ import atlas from 'atlas-mysql'

✗ const atlas = require('atlas-mysql')

Default export returns a factory function; CJS require returns { default: atlas } in Node 16+ with ESM.

Creates a client, connects, creates a table, inserts and selects data using query builder, and runs a transaction.

import atlas from 'atlas-mysql'; async function main() { const client = atlas({ host: 'localhost', user: 'root', password: process.env.DB_PASS ?? 'password', database: 'test' }); await client.connect(); // Create table await client.query( `CREATE TABLE IF NOT EXISTS users ( id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255) NOT NULL )` ); // Insert const insertResult = await client.insert('users', { name: 'Alice' }); console.log('Inserted ID:', insertResult.insertId); // Select with query builder const users = await client .select('users') .where({ id: insertResult.insertId }) .execute(); console.log('User:', users); // Transaction await client.transaction(async (tx) => { await tx.insert('users', { name: 'Bob' }); const count = await tx.select('users').count().execute(); console.log('Total users:', count); }); await client.close(); } main().catch(console.error);

Debug

Known issues

gotchaDo not reuse a closed client instance; AtlasClient throws a ConnectionError on query attempt.

fix

Call client.reconnect() or create a new instance.

affects: >=1.0.0

breakingAtlas v2 drops support for mysql2 v2; requires mysql2 v3.x+

fix

Update mysql2 to v3: npm install mysql2@^3.0.0

affects: >=2.0.0

deprecatedThe useRaw method is deprecated in favor of raw query via client.sql() in v2.1.0

fix

Replace useRaw with client.sql()`...`

affects: >=2.0.0 <2.1.0

gotchaModel definitions require explicit column types for enums; inferred types may use string

fix

Define enum columns with type: 'enum' and values as an array

affects: >=1.0.0

gotchaTransactions with nesting and savepoints are not supported; each nested transaction is treated as independent

fix

Use single transaction for atomic operations; rollback in parent on child failure manually

affects: >=1.0.0 <2.1.0

Errors

Common errors & fixes

Error: Cannot find module 'mysql2'

Missing peer dependency mysql2

fix

npm install mysql2@^3.0.0

TypeError: client.query is not a function

Using default import incorrectly when named import is expected

fix

Use import atlas from 'atlas-mysql' then invoke atlas(config) to get client

Error: ER_ACCESS_DENIED_ERROR: Access denied for user 'root'@'localhost'

Wrong credentials or missing permissions

fix

Verify DB_USER and DB_PASS environment variables; grant privileges

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

mysql2requiredPeer dependency: required for MySQL connection (mysql2 v3.x)

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mattthehat/atlas-mysql ↗

packageatlas-mysql ↗

homepagehttps://github.com/mattthehat/atlas-mysql#readme ↗