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",
  "qlcs": "qlcodes_success",
  "matches": [
    {
      "code": "42501",
      "keys": [
        "insufficient_privilege",
        "authorization_id_does_not_have_privilege_to_perform_specified_operation_on_identified_object"
      ],
      "reasons": [
        "The authorization ID does not have the privilege to perform the specified operation on the identified object."
      ],
      "use": [
        "pgsql",
        "ibm"
      ],
      "class": "42 - Syntax Error or Access Rule Violation"
    }
  ]
}

Alternatively, you may need to retrive matching codes via a known key for some technologies

import { lens } from "qlcodes";

const state = lens("insufficient_privilege");

console.log(state);

Output :

{
  "key": "insufficient_privilege",
  "qlcs": "qlcodes_success",
  "matches": [
    {
      "code": "42501",
      "keys": [
        "insufficient_privilege",
        "authorization_id_does_not_have_privilege_to_perform_specified_operation_on_identified_object"
      ],
      "reasons": [
        "The authorization ID does not have the privilege to perform the specified operation on the identified object."
      ],
      "use": [
        "pgsql",
        "ibm"
      ],
      "class": "42 - Syntax Error or Access Rule Violation"
    },
    {
      "code": "258",
      "keys": [
        "insufficient_privilege"
      ],
      "reasons": [
        "Insufficient privilege"
      ],
      "use": [
        "sap_hana"
      ],
      "class": "NA - Non associable class codes"
    }
  ]
}

Mismatches

If the provided SQLSTATE code or provided key 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",
  "qlcs": "qlcodes_malformed",
  "matches": []
}

Code : The provided code matches no code within known classes

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

Output:

{
  "code": "ABCDE",
  "qlcs": "qlcodes_no_code_found",
  "matches": []
}

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 || reasons — human-readable explanations || qlcs — 'qlcode status', shows the lens call status

Customization & Rebuild (Contributors)

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. Adapt the column (headers) configuration.

• .qlCodes file (root) : gives the configuration of CSVs headers/columns (with their format and aliases)
• src/constants.mjs : gives the configuration of the options passed throught @maze014/domFetch to fetch the documentation table of codes for the matching RDBMs.

3. Run the dev script to set everything up.

$ npm run dev

This action will generate the folowing resources folders :

• HTML : files from which a DOM can be fetched via domFetch.
• CSV : CSVs files generated from the build script. These files can be modified according updated info.

4. Rebuild the module

# generate the qlCodes.json
$ npm run build -- --prod

Quality of life

By default, the build script has no flag passed but You may pass flag argument to the build script to enforce a few behaviours to help you seing through the processor...

|argument|effect| |-|-| |--debug|prevents the cleanup of middle stage file created during the data processing| |--prod|will destroy the resources folder in order to keep things clean|

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)

• MariaDb MariaDB Error Code Reference

• Google Spanner Spanner error codes

• SAP Hana SAP HANA SQL Reference Guide for SAP HANA Platform V2.0 SPS 08

License

MIT 2025