feat: handle database errors

[aaqilniz]

Summary

Standardizes database error handling across @loopback/repository and @loopback/rest by translating connector-level driver errors into domain-specific, protocol-neutral errors, which are then mapped to REST HTTP statuses.

Key Changes

• @loopback/repository:
  • Introduced base DatabaseError and domain-specific sub-classes (UniqueConstraintError, ForeignKeyConstraintError, NotNullConstraintError, LockConflictError, DatabaseConnectionError, etc.).
  • Added handleRepositoryError() utility to intercept low-level driver error codes and normalize them into protocol-neutral DatabaseError instances while retaining context/details.
• @loopback/rest:
  • Added mapDatabaseErrorToHttpError() to map protocol-neutral DatabaseError codes to appropriate HTTP status codes (400, 409, 422, 503, 504).
  • Updated RejectProvider to run the mapping automatically before serializing the error response.
• Documentation & Unit Tests: Added reference documentation for all error mappings and unit tests covering repository error normalization and REST error serialization.

Architectural Notes

Connector-specific error translation is supposed to be handled at the connector level. Here are the changes to mysql-connector. @loopback/repository purely consumes standardized code strings, maintaining complete separation between storage layer implementations and transport protocols.

Dependent on PR@loopback-connector-mysql

Checklist

• DCO (Developer Certificate of Origin) signed in all commits
• npm test passes on your machine
• New tests added or existing tests modified to cover all changes
• Code conforms with the style guide
• API Documentation in code was updated
• Documentation in /docs/site was updated
• Affected artifact templates in packages/cli were updated
• Affected example projects in examples/* were updated

👉 Check out how to submit a PR 👈

[achrinza]

I agree it's a good feature to have.

Though I'd push back on two points:

1. Database-specific code should be in each database's NPM package. @loopback/rest can then parse the generalised Error object and map it
   • This would improve future extensibility and ensure that first-party and third-party LB4 connectors have the same features accessible.
   • This allows for non-REST applications to do their own mapping (i.e. don't add REST-specific code in @loopback/repository)
2. Opt-out mechanism
   Arguably this is security through obscurity, but this feature does necessarily expose some of the inner-workings of the application. IIRC 5xx errors are sanitised, but 4xx are not. So perhaps we should build an extensible "mapping" mechanism in @loopback/rest which users can customise?

[aaqilniz]

Hi, @achrinza. Thanks for the feedback. I have just made the changes based on your feedback.

The database-specific codes are mapped in the respective connector (Here is the PR in loopback-connector-mysql). Ultimately, the error is mapped at the REST level.
I have added a binding to disable this error mapping. It's enabled by default.