RDBMS Troubleshooting
Common issues, error patterns, and resolution steps for RDBSource connections and operations.
Connection Issues
Driver Not Found
DMEEditor.assemblyHandler.GetInstance() returns null or throws. The ADO.NET driver assembly is not loaded.
- Verify the driver NuGet package is installed in the Beep host application
- Check
DataSourceDriver.DbConnectionTypein Beep config matches the installed driver version - For SQL Server:
Microsoft.Data.SqlClient(not System.Data.SqlClient) - For MySQL:
MySql.DataorMySqlConnector - For PostgreSQL:
Npgsql - For Oracle:
Oracle.ManagedDataAccess.Core
Connection String Errors
Connection opens but queries fail with login/schema errors, or OpenConn() throws ArgumentException.
- Use
ConnectionProperties(host, port, database, userid, password) instead of raw connection strings when possible - If using a raw
ConnectionString, it takes precedence and must be a complete ADO.NET connection string - Oracle: verify
ALTER SESSION SET CURRENT_SCHEMAsucceeds — check schema name spelling - SQL Server: verify
ALTER LOGINor database-level user mapping
Health Check Failures
Circuit breaker opens repeatedly. CheckConnectionHealth() returns false even though the database is reachable.
- Verify the health check query is correct for your database:
- SQL Server/MySQL/PostgreSQL/SQLite:
SELECT 1 - Oracle:
SELECT 1 FROM DUAL - DB2:
SELECT 1 FROM SYSIBM.SYSDUMMY1
- SQL Server/MySQL/PostgreSQL/SQLite:
- Check
HealthCheckTimeout— increase if network latency is high - Reset resilience policies with
ResetResiliencePolicies()after fixing the underlying issue
Query Issues
Schema Not Found / Table Not Found
Queries fail with "invalid object name" or "table does not exist" even though the table is visible in the database.
- Check
SchemaNamein ConnectionProperties — it's used to prefix table names in generated SQL - For SQL Server: default is
dbo - For PostgreSQL: default is
public - For Oracle: schema = username (uppercase)
- Use
GetTableName()to see how schema is being injected
Paging Errors (Oracle)
Oracle paged queries fail with ORA-00904 or invalid identifier.
- Oracle uses a three-level ROWNUM subquery for paging — this fails if columns contain reserved words
- Use column delimiters (quotes) for columns that match Oracle reserved words
- Check
BuildOraclePagingQuery()output in logs
Parameter Limit Exceeded (Oracle)
ORA-01795: maximum number of expressions in a list is 1000.
- Reduce
DefaultBatchSizebelow 1000 - Oracle also has a 30-character identifier limit —
GetUniqueParameterName()handles this automatically
Known Bugs to Watch For
| Issue | Impact | Workaround |
|---|---|---|
UpdateEntities() calls InsertEntity() |
Bulk updates create duplicate rows | Use individual UpdateEntity() calls in a loop |
Commit() / EndTransaction() are stubs |
Transactions never commit | Manage transactions at the ADO.NET level via RDBMSConnection.DbConn |
MemoryCache can't enumerate keys |
Stale cached results | Set EnableResultCache = false or use short TTL |
| Thread-safety gaps with instance fields | Concurrent operations may corrupt state | Avoid concurrent entity operations on same RDBSource instance |
Performance Tuning
For large datasets (10K+ rows), enable EnableBulkOptimizations and use BulkInsertEntities<T>() or BulkUpdateEntities<T>(). These use multi-row INSERT or temp-table MERGE strategies that are 10-100x faster than row-by-row operations.
For read-heavy dashboards, set EnableResultCache = true. The 5-minute sliding TTL means frequently accessed queries stay cached while unused entries expire. Use InvalidateEntityCache(entityName) after writes to prevent stale reads.
ADO.NET connection pooling is enabled by default for most drivers. Avoid calling Closeconnection() between operations — keep the connection open during a user session. Use CheckConnectionHealth() to detect broken connections.
Entity structures are cached via EntityStructureCache (ConcurrentDictionary). Call GetEntityStructure(name, refresh: true) only when schema changes are expected. Normal reads use refresh: false.