Server Configuration

This section describes how to configure Tabsdata server components through various configuration files.

Overview

Tabsdata configuration is managed through YAML files located in the Tabsdata instance directory. These configuration files control critical aspects of the Tabsdata server including API server settings, security, database connections, storage mounts, and AI agent integration.

Proper configuration ensures optimal performance, security, and reliability of your Tabsdata deployment. This guide covers the main configuration files and their available options.

Instance Directory

The default instance directory location is:

• Windows: %USERPROFILE%/.tabsdata/instances/tabsdata
• Linux and MacOS: ${HOME}/.tabsdata/instances/tabsdata

Configuration Files

The following configuration files are available within the instance directory:

Configuration File	Purpose
workspace/config/proc/regular/apiserver/config/config.yaml	API server settings: addresses, authentication, database, storage, and transactions
workspace/config/proc/regular/aiagent/config/config.yaml	AI agent settings: port, read-only mode, and AI provider credentials
workspace/config/ssl/	SSL certificates ( key.pem and cert.pem ) for HTTPS
workspace/config/proc/regular/apiserver/config/log.yaml	Logging configuration for the API server

Environment Variables

Configuration files support environment variable substitution using the ${} syntax. Tabsdata provides the following built-in variables:

Variable	Description
TD_PATH_INSTANCE	Full path to the Tabsdata instance directory
TD_PATH_REPOSITORY	Full path to the repository directory (default: ${TD_PATH_INSTANCE}/repository )
TD_PATH_CONFIG	Full path to the configuration directory (default: ${TD_PATH_INSTANCE}/workspace/config )
TD_PATH_WORK	Full path to the working directory (default: ${TD_PATH_INSTANCE}/workspace/work )
TD_URI_INSTANCE	Same as TD_PATH_INSTANCE but URI-friendly (no scheme)
TD_URI_REPOSITORY	Same as TD_PATH_REPOSITORY but URI-friendly (no scheme)
TD_URI_CONFIG	Same as TD_PATH_CONFIG but URI-friendly (no scheme)

Example:

database:
  url: file://${TD_URI_REPOSITORY}/database/tabsdata.db

API Server Configuration

The API server configuration file is located at workspace/config/proc/regular/apiserver/config/config.yaml within your instance directory.

Complete Configuration Example

# storage_url: null    # Default: file://${TD_URI_REPOSITORY}/storage
addresses:
  - 127.0.0.1:2457     # Public IP/PORT
internal_addresses:
- 127.0.0.1:2458     # Internal IP/PORT, don't change 127.0.0.1
agent_addresses:
  - 127.0.0.1:2459
password:              # Password Hashing Configuration
  algorithm: argon2id
  version: 19
  memory_cost_mib: 20
  time_cost: 2
  parallelism_cost: 1
jwt:
  #secret: null                     # By default a generated UUID
  access_token_expiration: 3600     # Max inactivity period for a user session
request_timeout: 60                 # HTTP (API and UI) requests timeout
database:
  #  url: null         # Default: file://${TD_URI_REPOSITORY}/database/tabsdata.db
  # Connection pool configurations
  min_connections: 1
  max_connections: 10
  acquire_timeout: 30
  max_lifetime: 3600
  idle_timeout: 60
  test_before_acquire: true
  log_level: off
transaction_by: C      # C or F if transactions are by collection or by function
ssl_folder:            # Path for SSL configuration
storage:               # It also supports 'url' instead of 'mounts'
  mounts:
    - id: ROOT
      path: /
      uri: file://${TD_URI_REPOSITORY}/storage/data/
    # IMPORTANT: /bundles must be a local mount.
    - id: BUNDLES
      path: /bundles
      uri: file://${TD_URI_REPOSITORY}/storage/bundles/

tip

Important Configuration Decision: The transaction_by setting determines how Tabsdata manages transaction boundaries for execution plans. This is a critical configuration choice that affects performance and data consistency. See Transaction Mode for detailed guidance on choosing between collection-based (C) and function-based (F) transactions.

Configuration Options

The API server configuration in config.yaml controls the core Tabsdata server behavior.

Storage Configuration

# storage_url: null    # Default: file://${TD_URI_REPOSITORY}/storage

The URL to the location to store the Tabsdata data. The storage URL can be configured globally or through mount points (see Storage Mounts below).

Server Addresses

addresses:
  - 127.0.0.1:2457     # Public IP/PORT
internal_addresses:
- 127.0.0.1:2458     # Internal IP/PORT, don't change 127.0.0.1
agent_addresses:
  - 127.0.0.1:2459

• addresses: List of IP:PORT combinations for the API server to listen on
• agent_addresses: List of IP:PORT combinations for agent communication

Password Hashing

password:              # Password Hashing Configuration
  algorithm: argon2id
  version: 19
  memory_cost_mib: 20
  time_cost: 2
  parallelism_cost: 1

Configures password hashing using Argon2id algorithm:

Parameter	Description
algorithm	Password hashing algorithm - argon2id
version	Argon2 version number
memory_cost_mib	Memory cost in MiB for password hashing
time_cost	Number of iterations
parallelism_cost	Number of parallel threads

JWT Configuration

jwt:
  #secret: null                     # By default a generated UUID
  access_token_expiration: 3600     # Max inactivity period for a user session

• secret: JWT signing secret (auto-generated UUID if not specified)
• access_token_expiration: Maximum inactivity period in seconds before session expires

Request Timeout

request_timeout: 60                 # HTTP (API and UI) requests timeout

HTTP request timeout in seconds for both API and UI requests.

Database Configuration

database:
  #  url: null         # Default: file://${TD_URI_REPOSITORY}/database/tabsdata.db
  # Connection pool configurations
  min_connections: 1
  max_connections: 10
  acquire_timeout: 30
  max_lifetime: 3600
  idle_timeout: 60
  test_before_acquire: true
  log_level: off

Database connection and pool settings:

Parameter	Description
url	Database connection URL (defaults to SQLite in repository)
min_connections	Minimum number of connections in the pool
max_connections	Maximum number of connections in the pool
acquire_timeout	Timeout in seconds when acquiring a connection
max_lifetime	Maximum lifetime of a connection in seconds
idle_timeout	Idle timeout in seconds before closing unused connections
test_before_acquire	Test connection health before use
log_level	Database logging level (off, trace, debug, info, warn, error)

Transaction Mode

transaction_by: C      # C or F if transactions are by collection or by function

• C: Transactions are managed by collection
• F: Transactions are managed by function

Execution Plan Transaction Boundaries

Tabsdata supports two transaction strategies for execution plans: per function or per collection. The instance is configured with a particular strategy using the transaction_by parameter above.

Per Function Transactions (transaction_by: F)

Every function of the execution plan runs in its own separate transaction. The tables produced by the function are immediately committed and available after the function execution finishes. This provides:

• Maximum isolation between functions
• Independent function execution boundaries
• Ability to handle failures at the function level
• Better for independent function executions with minimal shared state

Per Collection Transactions (transaction_by: C)

The functions of the execution plan are grouped per collection, and a single transaction is used for each collection to execute all its functions. All the tables produced by all the functions of a collection are committed and available when the transaction finishes. This provides:

• Shared transaction context across collection functions
• Reduced transaction overhead for collection operations

SSL Configuration

ssl_folder:            # Path for SSL configuration

Path to directory containing SSL certificates. If not specified, defaults to:

${INSTANCE_PATH}/workspace/config/ssl/

Storage Mounts

storage:               # It also supports 'url' instead of 'mounts'
  mounts:
    - id: ROOT
      path: /
      uri: file://${TD_URI_REPOSITORY}/storage/data/
    # IMPORTANT: /bundles must be a local mount.
    - id: BUNDLES
      path: /bundles
      uri: file://${TD_URI_REPOSITORY}/storage/bundles/
#    # Mount configuration sample:
#    - id: PREFIX
#      path: /c
#      uri: s3://my-bucket/tabsdata
#      options:
#        - AwsAccessKey: ...
#          AwsSecretKey: ...

Storage mount configuration:

Parameter	Description
id	Unique identifier for the mount
path	Virtual path in Tabsdata
uri	Physical storage location (supports file:// , s3://, etc.)
options	Mount-specific options (e.g., AWS credentials for S3)

warning

The /bundles path must always be a local file system mount.

note

Storage can be configured using either url (single storage location) or mounts (multiple mount points), but not both.

AI Agent Configuration

The AI agent configuration file is located at workspace/config/proc/regular/aiagent/config/config.yaml within your instance directory.

Configuration Options

port: 2459
read_only: false
ai_providers:
  openai:
    api_key: ${OPENAI_API_KEY}    # If set the AI agent will start

AI Agent settings:

Parameter	Description
port	Port number for the AI agent to listen on
read_only	When true, AI agent can only read data, not modify
ai_providers	Configuration for AI provider integrations

AI Provider Configuration

OpenAI Provider

ai_providers:
  openai:
    api_key: ${OPENAI_API_KEY}

• api_key: OpenAI API key (use environment variable for security)

note

The AI agent will only start if at least one AI provider is properly configured with valid credentials.

tip

Use environment variables (e.g., ${OPENAI_API_KEY}) for sensitive values like API keys instead of hardcoding them in configuration files.

SSL Certificate Configuration

SSL certificate files are located at workspace/config/ssl/ within your instance directory.

Required Files

The SSL folder should contain:

• key.pem: Private key file
• cert.pem: Certificate file

To enable HTTPS:

1. Place your SSL certificate files in the SSL folder
2. Configure the ssl_folder path in the API server configuration
3. Restart the Tabsdata server

$ tdserver restart

Log Configuration

The log configuration file is located at workspace/config/proc/regular/apiserver/config/log.yaml within your instance directory. This file controls logging behavior for the API server and other components.

Configuration Example

profile: production

profiles:
  development:
    output: stdout
    level: debug
    directives:
      - tower::buffer::worker=info
  production:
    output: file
    level: debug
    directives:
      - tower::buffer::worker=info
    sinks:
      - file: sql.log
        directives:
          - sqlx::query=trace

Configuration Options

Parameter	Description
profile	Active logging profile ( development or production )
output	Log output destination: stdout (console) or file
level	Default log level: trace , debug , info , warn , error
directives	Module-specific log level overrides (e.g., tower::buffer::worker=info )
sinks	Additional log file destinations with specific directives

Profiles:

• development: Outputs logs to stdout (console) for easy debugging during development
• production: Outputs logs to files, with additional sinks for SQL query logging

Configuration Best Practices

1. Use Environment Variables for Secrets Always use environment variables for sensitive data like API keys, passwords, and tokens:

ai_providers:
  openai:
    api_key: ${OPENAI_API_KEY}

2. Backup Before Modifications Always backup configuration files before making changes:

$ cp config.yaml config.yaml.backup

3. Restart After Changes Configuration changes require a server restart:

$ tdserver restart

4. Monitor Resource Usage Adjust database connection pool settings based on your workload: - Increase max_connections for high-traffic environments

• Adjust acquire_timeout and idle_timeout based on query patterns

5. Storage Planning - Keep /bundles as a local mount for optimal performance

• Use S3 or cloud storage for data mounts when appropriate
• Configure appropriate credentials for cloud storage mounts

6. Security Considerations - Use strong JWT secrets in production

• Configure appropriate access_token_expiration values
• Enable SSL/TLS for production deployments
• Use Argon2id for password hashing with appropriate cost parameters

7. Transaction Mode Selection Choose transaction mode based on your use case: - Collection-based (C): Better for scenarios with multiple operations per collection. Requires acyclic trigger graph at collection level.

• Function-based (F): Better for independent function executions with maximum isolation. See Transaction Mode for detailed information about transaction boundaries and important constraints.

Troubleshooting

Configuration Not Taking Effect

If configuration changes don’t take effect:

1. Verify YAML syntax is correct
2. Check for typos in parameter names
3. Restart the server: tdserver restart
4. Check server logs for configuration errors

Environment Variables Not Resolving

If environment variables aren’t resolving:

1. Verify the environment variable is set: echo $VARIABLE_NAME
2. Ensure the variable is exported in the shell
3. Check the syntax uses ${VARIABLE_NAME} format
4. Restart the server after setting environment variables

Connection Pool Issues

If experiencing database connection issues:

1. Check max_connections isn’t set too low
2. Increase acquire_timeout if seeing timeout errors
3. Review max_lifetime and idle_timeout settings
4. Enable log_level: debug for detailed connection information

Transaction Mode Issues

If experiencing execution plan or trigger issues:

1. Collection Transaction Constraint Violation: If using transaction_by: C and encountering errors about circular dependencies or trigger paths, verify that your trigger graph does not have arc trigger paths that exit and reenter the same collection. Solution: Either restructure your triggers to avoid collection reentry, or switch to transaction_by: F (per-function transactions).
2. Performance Issues: If function execution is slower than expected, consider switching transaction modes: - For many independent functions: Use transaction_by: F

• For related functions in collections: Use transaction_by: C

3. Transaction Rollback Issues: Remember that at the end of each transaction, the system is in a pristine state. If you need state to persist across function boundaries, ensure your transaction mode aligns with your data flow.

See Transaction Mode for more details on transaction strategies.

For additional help, see Troubleshooting or Contact Us.

Related Topics

• Setting up Tabsdata over HTTPS - Security configuration and best practices
• Secrets Management - Managing secrets with HashiCorp Vault
• Tabsdata AI Agent (Tabby) - Detailed AI agent setup and usage
• Getting Started - Initial server setup