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)

Important

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.