A small utility that unifies SQL error codes (SQLSTATE) from different DBMS into a single, normalized structure through a curated dataset constructed at build time.
npm install qlcodesA 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.
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) .
``bash`
$ npm install qlcodes
`js
import { lens } from "qlcodes";
const state = lens("42501");
console.log(state);
`
Output :
`js`
{
"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
`js
import { lens } from "qlcodes";
const state = lens("insufficient_privilege");
console.log(state);
`
Output :
`js`
{
"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"
}
]
}
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}/
`js`
console.log(lens("123456"));
Output:
`js`
{
"code": "123456",
"qlcs": "qlcodes_malformed",
"matches": []
}
Code : The provided code matches no code within known classes
`js`
console.log(lens("2000U"));
Output:
`js`
{
"code": "ABCDE",
"qlcs": "qlcodes_no_code_found",
"matches": []
}
---
lens(code: string): QLLens
|Parameters|Returns|
|-|-|
|code SQLSTATE status code | A structured status description|
|| code ā normalized SQLSTATE, or -1 if not foundDBMS
|| keys ā semantic identifiers
|| use ā where the code is applicable
|| reasons ā human-readable explanations
|| qlcs ā 'qlcode status', shows the lens call status
If you want to extend or adjust the reference data:
1) Clone the repository
`bash`
$ 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.
`bash`
$ 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
`bash`generate the qlCodes.json
$ npm run build -- --prod
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|
|
---
---
- 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
---