koa-orm

library3.2.1jsnpmunverified

koa-orm is a Koa.js middleware that integrates Sequelize ORM for database operations, simplifying multi-database management in Koa applications. The current stable version is 3.2.1, with releases via npm. It supports single and multiple database configurations, provides a middleware to attach ORM instances to the Koa context, and leverages Sequelize for SQL querying. Differentiated by its focus on Koa and automatic context binding, it is actively maintained.

database

npm install koa-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KOA-ORM

koa-orm

databasejavascriptv3.2.1

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

✓ import orm from 'koa-orm'

✗ const orm = require('koa-orm')

ESM default import; CommonJS require also works but ESM is recommended

orm

✓ const orm = require('koa-orm')

✗ import { orm } from 'koa-orm'

CommonJS require returns the default function; named import only available in TypeScript declarations

orm.Middleware

✓ import type { Middleware } from 'koa-orm'

✗ import { Middleware } from 'koa-orm'

Middleware is exported as a type; use 'import type' in TypeScript to avoid runtime code

Creates a Koa app with koa-orm middleware for single MySQL database, performs a raw SQL select query.

import { join } from 'path'; import Koa from 'koa'; import orm from 'koa-orm'; const app = new Koa(); const config = { name: 'test', modelPath: join(__dirname, 'models'), database: 'orm_test', username: 'root', password: process.env.DB_PASS ?? 'pass', dialect: 'mysql', host: '127.0.0.1', port: 3306, pool: { max: 10, min: 0, idle: 30000 } }; app.use(orm(config).middleware); app.use(async (ctx) => { const db = ctx.orm(); const raws = await db.sql.select().from('table'); ctx.body = raws; }); app.listen(3000);

Debug

Known issues

breakingWhen upgrading from v1 to v2, the middleware and context API changed.

fix

Migrate to koa-orm v2: use `orm(configs).middleware` and access via `ctx.orm(name)` instead of `ctx.db`.

affects: >=2.0.0

breakingVersion 3 dropped support for Node <10.

fix

Upgrade Node.js to version >=10.0.0.

affects: >=3.0.0

gotchaThe modelPath must be an absolute path; relative paths may fail.

fix

Use `path.join(__dirname, 'models')` or provide an absolute path.

affects: >=2.0.0

gotchaWhen using multiple databases, ensure each config has a unique `name` field.

fix

Set different `name` values for each database configuration.

affects: >=2.0.0

deprecatedThe `orm.sql` method is deprecated in favor of Sequelize models.

fix

Define models in the modelPath and use `ctx.orm().ModelName` for queries instead of raw SQL.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: orm is not a function

Using import { orm } from 'koa-orm' instead of default import.

fix

Use `import orm from 'koa-orm'` (ESM) or `const orm = require('koa-orm')` (CommonJS).

Error: Cannot find module 'sk2'

Missing sk2 peer dependency.

fix

Run `npm install sk2` to install the required dependency.

SequelizeConnectionError: Client does not support authentication protocol requested by server

MySQL 8 uses caching_sha2_password by default, which may not be supported by the Node MySQL driver.

fix

Set `dialectOptions: { insecureAuth: true }` in the config or alter the MySQL user's authentication plugin to mysql_native_password.

Upgrade

Version history

3.2.1latest on npm

Audit

Dependencies

sequelizerequiredSequelize ORM library for database operations

sk2requiredsk2 library for SQL query building

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/d-band/koa-orm ↗

packagekoa-orm ↗

homepagehttps://github.com/d-band/koa-orm#readme ↗