@map-colonies/drizzle-utils

Utility functions for Drizzle ORM in MapColonies Node.js services.

API documentation

Check the autogenerated documentation here.

Installation

pnpm add @map-colonies/drizzle-utils drizzle-orm pg

[!NOTE] drizzle-orm and pg are peer dependencies and must be installed alongside this package.

Usage

Connection

import { initConnection, createConnectionOptions } from '@map-colonies/drizzle-utils';

// Create and verify a connected pg.Pool
const pool = await initConnection(dbConfig);

// Or just build the PoolConfig without connecting
const poolConfig = createConnectionOptions(dbConfig);

Health Check

import { healthCheck } from '@map-colonies/drizzle-utils';
import { Pool } from 'pg';

const pool = new Pool(poolConfig);
const check = healthCheck(pool);

// Returns a function — call it to verify the DB is reachable
await check();

Migrations

import { drizzle } from 'drizzle-orm/node-postgres';
import { runMigrations } from '@map-colonies/drizzle-utils';

const db = drizzle({ client: pool });

// Discovers and applies pending migrations
await runMigrations(db, 'migrations_schema');

Migration folders are resolved automatically by searching for ./db/migrations, ./src/db/migrations, ./migrations, or ./src/migrations relative to process.cwd(). A custom base path can be passed as the third argument.

Pagination

import { paginationParamsToOffsetAndLimit } from '@map-colonies/drizzle-utils';

const { limit, offset } = paginationParamsToOffsetAndLimit({ page: 2, pageSize: 20 });
// { limit: 20, offset: 20 }

Sorting

import { sortOptionParser } from '@map-colonies/drizzle-utils';

const fieldsMap = new Map([
  ['created_at', 'createdAt'],
  ['name', 'name'],
]);
const sortOptions = sortOptionParser(['created_at:desc', 'name:asc'], fieldsMap);
// { createdAt: 'desc', name: 'asc' }

SSL Validation

import { validateSslCerts } from '@map-colonies/drizzle-utils';

// Throws SslValidationError if anything is wrong
validateSslCerts(keyBuffer, certBuffer, caBuffer);

Error Handling

import { isDrizzleQueryError, pgErrorCodes } from '@map-colonies/drizzle-utils';

try {
  await db.insert(table).values(row);
} catch (err) {
  if (isDrizzleQueryError(err) && err.cause?.code === pgErrorCodes.UNIQUE_VIOLATION) {
    // handle duplicate
  }
}