Troubleshooting

Troubleshooting

This guide covers common issues you may encounter while using the Generic SQL API Framework and provides recommended solutions.

---

Database Connection Failed

Symptoms

• Unable to connect to SQL Server
• Connection timeout
• Login failed

Possible Causes

• SQL Server is not running
• Incorrect server name
• Invalid credentials
• ODBC Driver is missing
• Firewall blocking the connection

Solution

• Verify SQL Server is running.
• Confirm the server and instance name.
• Check your database credentials.
• Install the Microsoft ODBC Driver for SQL Server.
• Test the connection using SQL Server Management Studio (SSMS).

---

Query File Not Found

Symptoms

{
    "success": false,
    "message": "Query file not found."
}

Solution

• Verify the SQL file exists.
• Check the file name matches the JSON request.
• Ensure the file is located in the queries/ directory.

Example:

queries/
    customers.sql

Request:

{
    "query": "customers"
}

---

Invalid JSON Request

Symptoms

{
    "success": false,
    "message": "Invalid JSON format."
}

Solution

• Validate the JSON syntax.
• Ensure all braces and commas are correct.
• Use double quotes for keys and string values.

---

Missing Required Parameter

Symptoms

{
    "success": false,
    "message": "Missing required parameter: CustomerID"
}

Solution

Provide all required parameters.

Example:

{
    "query": "customer_by_id",
    "parameters": {
        "CustomerID": 101
    }
}

---

SQL Syntax Error

Symptoms

The query fails during execution.

Solution

• Run the SQL directly in SSMS.
• Check for syntax errors.
• Verify table and column names.

---

Empty Response

Symptoms

{
    "success": true,
    "data": []
}

Possible Causes

• No matching records
• Incorrect filter values
• Query conditions are too restrictive

Solution

• Verify the data exists.
• Review filter parameters.
• Test the SQL directly in SQL Server.

---

ODBC Driver Not Found

Symptoms

Database connection fails immediately.

Solution

Install a supported Microsoft ODBC Driver.

Recommended versions:

• ODBC Driver 18 for SQL Server
• ODBC Driver 17 for SQL Server

---

Slow Query Performance

Symptoms

Requests take longer than expected.

Solution

• Add indexes to frequently searched columns.
• Avoid SELECT *.
• Use pagination for large datasets.
• Review the SQL execution plan.
• Optimize JOIN operations.

---

HTTP 404

Symptoms

The requested endpoint cannot be found.

Solution

• Verify the API URL.
• Ensure the web server is configured correctly.
• Confirm the project is deployed in the expected directory.

---

HTTP 500

Symptoms

Internal Server Error.

Solution

• Check the application logs.
• Verify the database connection.
• Review the PHP error log.
• Confirm the SQL query is valid.

---

Permission Denied

Symptoms

The framework cannot access SQL files or configuration files.

Solution

• Verify file permissions.
• Ensure the web server has read access.
• Confirm the project directory is accessible.

---

Debugging Checklist

Before reporting an issue, verify:

• SQL Server is running.
• Database configuration is correct.
• ODBC Driver is installed.
• SQL files exist.
• JSON request is valid.
• Parameters are supplied.
• SQL executes successfully in SSMS.
• Application logs do not contain critical errors.

---

Still Need Help?

If the issue persists:

1. Search existing GitHub Issues.
2. Review the project documentation.
3. Open a new GitHub Issue with:
   • Framework version
   • Operating system
   • PHP version
   • SQL Server version
   • Error message
   • Steps to reproduce the issue

Providing complete information helps maintainers reproduce and resolve issues more quickly.