db-errors

What is db-errors?

The db-errors npm package provides a set of custom error classes for handling database-related errors in a more structured and consistent manner. It helps developers to catch and manage different types of database errors effectively.

What are db-errors's main functionalities?

UniqueConstraintError

This feature allows you to handle unique constraint violations in your database operations. The UniqueConstraintError class can be used to catch and manage errors when a unique constraint is violated.

const { UniqueConstraintError } = require('db-errors');

try {
  // Simulate a unique constraint violation
  throw new UniqueConstraintError();
} catch (error) {
  if (error instanceof UniqueConstraintError) {
    console.error('Unique constraint violated:', error);
  }
}

ForeignKeyConstraintError

This feature allows you to handle foreign key constraint violations. The ForeignKeyConstraintError class can be used to catch and manage errors when a foreign key constraint is violated.

const { ForeignKeyConstraintError } = require('db-errors');

try {
  // Simulate a foreign key constraint violation
  throw new ForeignKeyConstraintError();
} catch (error) {
  if (error instanceof ForeignKeyConstraintError) {
    console.error('Foreign key constraint violated:', error);
  }
}

NotNullConstraintError

This feature allows you to handle not-null constraint violations. The NotNullConstraintError class can be used to catch and manage errors when a not-null constraint is violated.

const { NotNullConstraintError } = require('db-errors');

try {
  // Simulate a not-null constraint violation
  throw new NotNullConstraintError();
} catch (error) {
  if (error instanceof NotNullConstraintError) {
    console.error('Not-null constraint violated:', error);
  }
}

Other packages similar to db-errors

sequelize

Sequelize is a promise-based Node.js ORM for Postgres, MySQL, MariaDB, SQLite, and Microsoft SQL Server. It includes built-in error handling for various database constraints, similar to db-errors, but also provides a full ORM solution for database operations.

objection

Objection.js is an SQL-friendly ORM for Node.js that supports various databases. It provides error handling for database constraints and offers a more flexible and powerful query building experience compared to db-errors.

pg-promise

pg-promise is a PostgreSQL interface for Node.js that provides robust error handling, including constraint violations. While it focuses on PostgreSQL, it offers a comprehensive set of features for managing database interactions, similar to db-errors.

README

Unified error API for node.js SQL DB drivers

This project is an attempt to create a unified API for node.js SQL DB driver errors. Each driver throws their own kind of errors and libraries like knex, Bookshelf and objection.js simply pass these errors through. It's usually very difficult to reason with these errors. This library wraps those errors to error classes that are the same for all drivers. The wrapped error classes also expose useful information about the errors.

NOTE: Only MySQL, Sqlite3, MSSQL and PostgreSQL are officially supported (tested).

Contributions and suggestions are most welcome

If you have an idea for an error we should handle, please open an issue and we'll see what we can do to add it.

Usage

const {
  wrapError,
  DBError,
  UniqueViolationError,
  NotNullViolationError
} = require('db-errors');

function errorHandler(err) {
  // wrapError function takes any error and returns a DBError subclass instance if
  // the input was an error thrown by the supported database drivers. Otherwise
  // the input error is returned.
  err = wrapError(err);

  if (err instanceof UniqueViolationError) {
    console.log(`Unique constraint ${err.constraint} failed for table ${err.table} and columns ${err.columns}`);
  } else if (err instanceof NotNullViolationError) {
    console.log(`Not null constraint failed for table ${err.table} and column ${err.column}`);
  } else if (err instanceof DBError) {
    console.log(`Some unknown DB error ${dbError.nativeError}`);
  }
}

API

DBError

class DBError extends Error {
  // The error thrown by the database client.
  nativeError: Error
}

Base class for all errors.

ConstraintViolationError

class ConstraintViolationError extends DBError {
  // No own properties.
}

A base class for all constraint violation errors

UniqueViolationError

class UniqueViolationError extends ConstraintViolationError {
  // The columns that failed.
  //
  // Available for: postgres, sqlite
  columns: string[]

  // The table that has the columns.
  //
  // Available for: postgres, sqlite
  table: string

  // The constraint that was violated.
  //
  // Available for: postgres, mysql
  constraint: string
}

NotNullViolationError

class NotNullViolationError extends ConstraintViolationError {
  // The column that failed.
  //
  // Available for: postgres, sqlite, mysql
  column: string

  // The table that has the columns.
  //
  // Available for: postgres, sqlite
  table: string
}

ForeignKeyViolationError

class ForeignKeyViolationError extends ConstraintViolationError {
  // The table that has the foreign key.
  //
  // Available for: postgres, mysql
  table: string

  // The constraint that was violated.
  //
  // Available for: postgres, mysql
  constraint: string
}

CheckViolationError

// This is not available for MySql since MySql doesn't have check constraints.
class CheckViolationError extends ConstraintViolationError {
  // The table that has the check constraint.
  //
  // Available for: postgres
  table: string

  // The constraint that was violated.
  //
  // Available for: postgres
  constraint: string
}

DataError

// Invalid data (string too long, invalid date etc.)
//
// NOTE: SQLite uses dynamic typing and doesn't throw this error.
class DataError extends DBError {
  // There is no easy way to parse data from these kind
  // of errors.
}

Development setup

Run the following commands in the repo root:

docker-compose up
node setup-test-db.js

Run tests:

npm test