fastify-ydb-orm

Fastify plugin for YDB simple ORM

---

Fastify 5 plugin for ydb-orm. It creates a YDB connection during application startup, decorates the Fastify instance with db, optionally synchronizes registered models, and closes the connection with the application.

Features

• Fastify-managed YDB startup and shutdown lifecycle
• Typed ydb-orm v3 model registry
• Shared Fastify and ORM logger
• Optional schema synchronization
• Native Node.js ESM package with tested CommonJS loading

---

Requirements

• Node.js 20.19 or newer.
• A reachable YDB database.

Installation

npm install fastify fastify-ydb-orm

Define A Model

Define models with the typed v3 model pattern:

import * as argon2 from 'argon2'
import { nanoid } from 'nanoid'
import { YdbDataType, YdbModel, type YdbSchemaType } from 'fastify-ydb-orm'

type UserFields = {
  id: string
  login: string
  password: string
  createdAt: Date
}

class User extends YdbModel<UserFields> {
  static override schema: YdbSchemaType = {
    id: YdbDataType.ascii,
    login: YdbDataType.ascii,
    password: YdbDataType.ascii,
    createdAt: YdbDataType.date,
  }

  constructor(fields: Partial<UserFields> = {}) {
    super(fields)
    this.id = fields.id || nanoid()
    this.login = fields.login || ''
    this.password = fields.password || ''
    this.createdAt = fields.createdAt || new Date()
  }

  async hash(password: string) {
    this.password = await argon2.hash(password)
  }

  async check(password: string) {
    return argon2.verify(this.password, password)
  }
}

interface User extends UserFields {}

Register With Fastify

Register the model object with Fastify:

import Fastify from 'fastify'
import { YdbFastify } from 'fastify-ydb-orm'

const app = Fastify({ logger: true })

await app.register(YdbFastify, {
  connectionString: process.env.YDB_CONNECTION_STRING,
  models: { User },
  timeout: 10_000,
  sync: process.env.YDB_SYNC === 'true',
})

app.get('/users', async () => User.findAll())

await app.listen({ host: '0.0.0.0', port: 3000 })

The split connection form is also supported:

await app.register(YdbFastify, {
  endpoint: process.env.YDB_ENDPOINT,
  database: process.env.YDB_DATABASE,
  models: { User },
})

All Ydb.init() options except logger are accepted. The plugin always uses fastify.log, so ORM records share the application logger. The plugin-only sync option defaults to false and should generally stay disabled in production.

After registration, the initialized ORM is available as app.db. Registered model classes are also bound to that ORM context, so both User.findAll() and app.db.model.User.findAll() use the same connection.

Migrating From v2

The ydb-orm v3 migration is intentionally explicit:

• replace Ydb.init(endpoint, database, options) with Ydb.init(options);
• replace model: [User] with models: { User };
• remove manual db.load() calls;
• define models as YdbModel<UserFields> and merge their field interface;
• use native ESM imports with .js relative specifiers in TypeScript source.

Authentication And TLS

Authentication options are passed directly to ydb-orm. Supported options include token, credential, and meta. The ORM also recognizes its standard YDB_SA_KEY and YDB_CERTS environment variables.

Development

The project uses npm and Node.js only; Bun and Tap are not part of the toolchain.

npm ci
npm run lint
npm run typecheck
npm run typecheck:test
npm run test:unit

Integration tests require local YDB:

npm run docker:db-up
npm test
npm run test:coverage
npm run test:smoke
npm run docker:db-down

Container checks:

npm run test:docker
npm run test:docker:smoke
npm run test:docker:clean