QLCodes

A small utility that unifies SQL codes describing states (SQLSTATE) from different DBMS into a single, normalized structure through a curated dataset constructed at build time.

The module is built from authoritative vendor documentation (IBM, PostgreSQL, Oracle) and generates static reference data at build time. Find references bellow.

SQLSTATES coverage

The project aims to cover sql states for most of RDBMS drivers supported by Typeorm such as Google Spanner. Find bellow the actual coverage:

🕓 MySQL | 🕓 MariaDB | ✅ PostgreSQL | 🕓 CockroachDB (Postgres-compatible) 🕓 Microsoft SQL Server | ✅ Oracle | 🕓 SQLite | 🕓 SAP HANA | 🕓 Google Spanner | ✅ IBM*

( * ) IBM defines and publishes SQLSTATE codes as part of the SQL standard, so their The codes should covere IBM products such as DB2, IBM Informix, IBM Netezza, IBM i (AS/400) .

Installation

$ npm install qlcodes

Usage

import { lens } from "qlcodes";
    
const state = lens("42501");
    
console.log(state);

Output :

{
  code: "42501",
  keys: [ "insufficient_privilege" ],
  use: [ "ibm", "postgres" ],
  reason: "The authorization ID does not have the privilege to perform the specified operation on the identified object.",
  qlcs: "qlcodes_sucess"
}

Mismatches

If the provided SQLSTATE does not match any known entry, we return a normalized fallback object This guarantees that lens() always returns a predictable object shape.

There are three mismatch levels that we detect.

Format : The provided code is malformed and is not validate the expression /[0-9A-Z]{5}/

ℹ️ "SQLSTATE values are comprised of a two-character class code value, followed by a three-character subclass code value. (ISO/IEC 9075:1992)"

console.log(lens("123456"));

Output:

{
  code: "123456",
  keys: [],
  qlcs: "qlcodes_malformed",
  use: [],
  r

Class : The provided code matches no code class

console.log(lens("ABCDE"));

Output:

{
  code: "ABCDE",
  keys: [],
  qlcs: "qlcodes_no_class_found",
  use: [],
  reason: "The code 'ABCDE' does not match any entries in qlcodes. This may be a qlcode issue only to provide you with the correct information"
}

Code : The provided code matches no code within known classes

console.log(lens("2000U"));

Output:

{
  code: "2000U",
  keys: [],
  qlcs: "qlcodes_no_code_found",
  use: [],
  reason: "The code '2000U' does not match any entries in qlcodes. This may be a qlcode issue only to provide you with the correct information"
}

API

lens(code: string): QLLens

|Parameters|Returns| |-|-| |code SQLSTATE status code | A structured status description| || code — normalized SQLSTATE, or -1 if not found || keys — semantic identifiers || use — DBMS where the code is applicable || reason — human-readable explanation || qlcs — 'qlcode status', shows the lens call status

Customization & Rebuild (Contributors)

⚠️ Do not modify files inside node_modules. Changes will be lost on reinstall.

If you want to extend or adjust the reference data:

1. Clone the repository

$ git clone https://github.com/ManuUseGitHub/QLCodes.git
$ cd qlcodes
$ npm install

2. Modify files:

• under references/ -> CSV files generated from vendor documentation
• under src/ -> transformation and normalization logic

⚠️ follow the data modification pipeline describe by the build.sh script. unless you know what you know what you are doing.

3. Rebuild the module

$ npm run build

Quality of life

You may pass argument to the build script to enforce a few behaviours to help you seing through the process...

|argument|effect| |-|-| |--debug|prevents the cleanup of middle stage file created during the data processing| |--make-keys|allows the creation of keys when a description is given...through the 'generate' step (generate.cjs)|

Use your customized build via a local dependency or a forked package.

Showcase

in stackblitz

References

• IBM Listing of SQLSTATE values (Last Updated: 2025-09-29)

• Postgres codes Appendix A. PostgreSQL Error Codes (V.10)

• Oracle Oracle appendix 11g Release 1 (11.1)

License

MIT 2025