Data Source
Data Source provides shared database connectivity, Hibernate/JDBC query execution, and pooled connections for components and actions that need persistence or SQL access.
Choose the database role before tuning the pool
Use Data Source as a shared database connector for event history, portal WebRTC tokens, MQTT authentication, SQL automation, and UI database browsing. It configures a connection pool, Hibernate dialect, persistent entities, and table/query APIs.
Start with embedded Derby for simple local persistence. Use PostgreSQL, MySQL, or MSSQL when persistence needs stronger backups, monitoring, external reporting, or higher query volume.
Name the database purpose
Set Title to a stable purpose such as local persistence, event history, portal tokens, MQTT users, or external reporting database. Avoid renaming it after other components reference it.
Select dialect and URL
Set Dialect and JDBC Url for the target database. For external databases, use a dedicated schema/database and verify that the driver is available in the runtime.
Set schema and pool policy
Use Action on schema and pool size settings according to production ownership. Keep the pool below the database server connection limit.
Configuration parameters
| Parameter | Required | Description | Default |
|---|---|---|---|
Title | Yes | Display name and stable purpose of the data source. | None |
Dialect | Yes | Database dialect, such as embedded Derby, PostgreSQL, MySQL, or MSSQL. | LOCAL_DERBY |
JDBC Url | Yes | JDBC connection URL. The default embedded URL stores the local database under the agent instance configuration folder. | Embedded Derby URL |
Username | Optional | Database username. Use a dedicated least-privileged account for production databases. | Empty |
Password | Optional | Database password for the selected account. | Empty |
Driver properties | Optional | Newline-separated driver or JVM system properties applied before the data source starts. Change only when the selected driver or deployment requires it. | Derby tuning properties |
Action on schema | Yes | Hibernate schema management mode. Use update for embedded/self-managed databases, validate when schema is managed externally, and none when schema management must be disabled. | update |
Min pool size | Yes | Minimum number of pooled database connections. | 1 |
Max pool size | Yes | Maximum number of pooled connections. Increase for concurrent event history writes, WebRTC sessions, MQTT auth, SQL actions, and UI queries. | 10 |
Idle timeout (ms) | Yes | Time after which unused connections can be released. | 30000 |
Connection timeout (ms) | Yes | Maximum wait time for a pooled connection before the caller fails. | 30000 |
One connector for persistence and SQL
Data Source creates a HikariCP connection pool, configures Hibernate for the selected dialect, registers Banalytics persistent entities, and exposes database browsing/query APIs for the UI and automation.
Most fields require restart because changing URL, credentials, pool, or schema management rebuilds the underlying data source and Hibernate session factory.
Shared database
Used by history, portal, MQTT, SQL actions, and other persistence-oriented features.
Connection pool
Pool size and timeouts define concurrency, back pressure, and failure visibility.
Schema mode
Choose whether Banalytics updates, validates, or ignores database schema management.
Match the database to retention and concurrency
Default embedded persistence
Use embedded Derby, keep the default JDBC URL, Action on schema as update, Min pool size as 1, Max pool size as 10, and keep default Derby driver properties.
Small event history
Keep local Derby if retention is short and event volume is moderate. Move Event History to an external database if history grows quickly or queries become slow.
External production database
Use the matching dialect, a dedicated JDBC URL and user, validate after schema is prepared, and pool sizing based on expected concurrent writes and UI queries.
WebRTC token and connection history
Use a reliable data source with backups. Token and connection records are small but security-sensitive.
SQL automation
Attach SQL Action to this data source when automation must run native SQL. Test queries manually and use the least-privileged database account possible.
High-concurrency integrations
Increase Max pool size, monitor database load, and keep Connection timeout (ms) realistic. Pool exhaustion usually means too many concurrent consumers, slow SQL, or insufficient database capacity.
Operational notes
Embedded Derby recovery
For embedded Derby, the component attempts recovery after a JVM crash, validates the connection, and removes stale Derby lock files when necessary.
Database browsing APIs
The data source exposes table and view scanning plus paged table queries for browsing database content from the UI.
Restart for structural changes
Changing URL, credentials, pool settings, schema mode, or driver properties rebuilds the data source. Plan restarts around dependent components.