Dataset DBs (Reference) define database connections for data storage, retrieval, and manipulation within the FrameworX platform. It provides:

  • SQL database connectivity
  • Pre-configured system databases
  • Connection string management
  • Development/production isolation
  • Multi-provider support

Each DB represents a connection to a database used for tags, alarms, historian, or custom data operations.

In this page:


Datasets → Tutorial | Concept | How-to Guide | Reference


Configuration Properties

PropertyDescriptionRequired
NameUnique database identifierYes
ProviderDatabase technology (SQLite, SqlClient, etc.)Yes
DatabaseDatabase type/instanceYes
ConnectionStringConnection parametersYes
LogonPasswordAuthentication password (admin only)No
ServerIPRemote gateway for securityNo
FilterColumnsQuery optimization columnsNo
CustomOptionsAdditional configurationNo
DescriptionDocumentation textNo

Pre-Defined Databases

Four system databases are included in every solution:

DB NamePurposeDefault Location
RetentiveStores retentive tag values<SolutionNameAndPath>.dbRetentive
RuntimeUsersDynamic user management<SolutionNameAndPath>.dbRuntimeUsers
AlarmHistorianAlarm and audit trail records<SolutionNameAndPath>.dbAlarmHistorian
TagHistorianTime-series data storage<SolutionNameAndPath>.dbTagHistorian

Creating Database Connections

  1. Navigate to Datasets → DBs
  2. Click Plus icon
  3. Configure:
    • Name: Unique identifier
    • Provider: Select from list
    • Database: Choose type
    • Description: Documentation
  4. Click OK

ConnectionString Configuration

Structure

Provider=<provider>;Data Source=<source>;Additional Parameters

Examples

SQLite (Local):

Provider=System.Data.SQLite;
Data Source=_SolutionPathAndName_.db

SQL Server Express:

DataSource=.\SQLEXPRESS;
Initial Catalog=myDatabase;
User Id=sa;Password=pwd

PostgreSQL:

Host=localhost;Database=mydb;
Username=user;Password=pass;Port=5432

ConnectionString Macros

Use these macros for portable configurations:

MacroDescriptionExample
_SolutionPath_Solution directoryC:\Solutions\MyApp\
_SolutionName_Solution name onlyMyApp
_SolutionPathAndName_Full path with nameC:\Solutions\MyApp\MyApp
_ExecutionPath_Working directoryCurrent runtime folder
_ExecutionPathAndName_Working path with nameRuntime location
_ProductPath_Installation directoryC:\Program Files\FrameworX\
_Transfers_Default transfer folderPublic\Documents\Transfers\
_ThirdParty_Third-party componentsMyDocuments\ProductName\ThirdParty\

Supported Providers

ProviderSupported Databases
System.Data.SQLiteSQLite
System.Data.SqlClientSQL Server, SQL Server Express
NpgsqlPostgreSQL
MySql.Data.MySqlClientMySQL
Oracle.DataAccess.ClientOracle
System.Data.OdbcAny ODBC-compatible
System.Data.OleDbAccess, Excel, CSV

Development vs Production

Execution Profiles

Automatic database switching for development:

Production DBDevelopment Override
<name>.dbRetentive<name>.dbRetentiveDev
<name>.dbRuntimeUsers<name>.dbRuntimeUsersDev
<name>.dbAlarmHistorian<name>.dbAlarmHistorianDev
<name>.dbTagHistorian<name>.dbTagHistorianDev

Configuration

  1. Configure production databases normally
  2. Run in Development profile
  3. Data automatically redirects to Dev databases
  4. No manual switching required

Security Considerations

Password Management

  • Only administrators can set LogonPassword
  • Passwords encrypted in configuration
  • Use Windows Authentication when possible

Remote Access

Configure ServerIP for gateway security:

  • Requires TWebServices on remote computer
  • Provides secure tunnel for database access
  • Isolates database from direct access

Utilities

SQLite Admin

Built-in tool for SQLite management:

  • Browse tables
  • Execute queries
  • Import/export data

Visual Query Builder

Interactive SQL query creation:

  • Drag-and-drop interface
  • Join visualization
  • Query testing

Best Practices Checklist

  • Use macros - Portable connection strings
  • Test connections - Verify before deployment
  • Document databases - Clear descriptions
  • Secure passwords - Admin-only access
  • Use Dev profiles - Protect production data
  • Regular backups - Especially SQLite files
  • Monitor performance - Check query execution

Troubleshooting

Connection failed:

  • Verify provider installed
  • Check connection string syntax
  • Confirm database exists
  • Test network connectivity

Access denied:

  • Check credentials
  • Verify permissions
  • Review firewall rules

Performance issues:

  • Add indexes
  • Optimize queries
  • Check network latency
  • Review connection pooling

Claude can make mistakes.
Please double-check responses.

Research

Opus 4.1

In this section...