Error helpers

better-drizzle exports helpers that normalize database errors across PostgreSQL, SQLite, and MySQL, so you can classify failures without string-matching driver messages. See error handling for end-to-end usage.

import {
	isDatabaseError,
	getDatabaseErrorInfo,
	isUniqueViolation,
	isForeignKeyViolation,
	isNotNullViolation,
	isCheckViolation,
} from 'better-drizzle';

Predicates

Each returns a boolean and accepts an optional constraint name (or column name, for isNotNullViolation) to match a specific one.

try {
	await client.users.create({ data });
} catch (error) {
	if (isUniqueViolation(error, 'users_email_unique')) {
		// handle duplicate email specifically
	}
	throw error;
}

getDatabaseErrorInfo

Parses any caught error into a normalized object, regardless of driver:

const info = getDatabaseErrorInfo(error);

BetterDrizzleError

Every error thrown by better-drizzle itself is a BetterDrizzleError (it extends Error). Database failures that surface through an operation are normalized into the same shape.

import { BetterDrizzleError, BetterDrizzleErrorCode } from 'better-drizzle';

try {
	await client.users.findUnique({ where: { id: 1 } }).throw();
} catch (error) {
	if (
		BetterDrizzleError.is(error) &&
		error.code === BetterDrizzleErrorCode.ResultNotFound
	) {
		// error.status === 404
	}
	throw error;
}

Fields

Static helpers

Drizzle ORM 1.x wraps driver failures in DrizzleQueryError (message Failed query: ...) and keeps the driver error as its cause. BetterDrizzleError.from(...), fromDatabaseError(...), getDatabaseErrorInfo, and the isUniqueViolation / isForeignKeyViolation / isNotNullViolation / isCheckViolation helpers read that wrapped driver error, so sqlState, constraint, table, and column still resolve. When you inspect a raw Drizzle error yourself, read error.cause for the driver fields.

Instances also have withCause(cause) and withDetails(details), which return a new error (details are shallow-merged), and toJSON(), which returns a plain object with every field except cause.

try {
	await db.insert(users).values(data);
} catch (error) {
	throw BetterDrizzleError.fromDatabaseError(error, {
		operation: 'create',
		table: 'users',
	});
}

Error codes

BetterDrizzleErrorCode is an exported string enum. The status column is the default status for each code; any code not given a specific status defaults to 500.

BetterDrizzleTransactionRollbackError

Thrown when a transaction is explicitly rolled back via tx.rollback(reason). It extends BetterDrizzleError with code TRANSACTION_ROLLBACK (status 409). The reason you pass is available as error.reason (also as cause and details.reason), and a non-empty string reason becomes the message:

import { BetterDrizzleTransactionRollbackError } from 'better-drizzle';

try {
	await client.transaction(async (tx) => {
		tx.rollback('duplicate email');
	});
} catch (error) {
	if (error instanceof BetterDrizzleTransactionRollbackError) {
		console.log(error.reason); // 'duplicate email'
	}
}