Configuration

Syntra ODBC is configured via config.toml in the installation directory. The most common options (cache, auth, MCP server, updates) are also exposed through the Settings tab inside the Syntra ODBC app, so you do not have to leave the GUI to change them.

Syntra ODBC Settings tab showing cache sync interval and max staleness sliders, the qbconnect username and password fields, the MCP server enable toggle with host and port 5434, and the updates panel with a Check for updates button

Any value you change in the Settings tab is written back to config.toml on disk. Any value you set in config.toml directly shows up in the Settings tab the next time you open it. Both surfaces are equivalent for the options they cover; use config.toml directly when you need to set something the GUI does not expose (TLS, logging level, live reads on Enterprise).

Full Reference

[quickbooks]
# Application name shown in QuickBooks authorization dialog
app_name = "Syntra ODBC"

[server]
# Network interface to bind to
host = "127.0.0.1"
# SQL server listening port
port = 5433
# Maximum concurrent connections
max_connections = 20

[auth]
# Credentials for connecting to the Syntra ODBC server
username = "qbconnect"
password = "change-me"

[cache]
# Enable local cache
enabled = true
# Default max staleness in seconds (0 = always live)
default_max_staleness = 600
# Staleness threshold for triggering live fallback
stale_threshold_seconds = 600

[tls]
# Enable TLS encryption
enabled = false
# Path to certificate file
cert_file = ""
# Path to private key file
key_file = ""

[logging]
# Log level: trace, debug, info, warn, error
level = "info"
# Log to file
file_enabled = true
# Log file directory
log_dir = "logs"

[odbc]
# Live reads on QuickBooks Enterprise: "auto" | "enabled" | "disabled"
mode = "auto"
# Credentials, only needed if the company file is password-protected
username = ""
password = ""

Environment Variables

You can override any config value with environment variables using the SYNTRA_ prefix:

SYNTRA_SERVER_PORT=5434
SYNTRA_AUTH_PASSWORD=my-password
SYNTRA_CACHE_ENABLED=false

Per-Session Overrides

You can override cache behavior per SQL session:

-- Force live queries (bypass cache)
SET QB_MAX_STALENESS = 0;

-- Use cache with 5-minute tolerance
SET QB_MAX_STALENESS = 300;

-- Reset to config default
RESET QB_MAX_STALENESS;