When initializing a new Preswald project with preswald init, a default preswald.toml file is created. This file defines core settings for the app, including logging, theming, and data connections. Data connections can include databases like PostgreSQL or local CSV files.

​
Default Configuration (preswald.toml)

The following is the default structure of preswald.toml created during initialization:

​
Example preswald.toml

[project]
title = "Preswald Project"
version = "0.1.0"
port = 8501
slug = "preswald-project"
entrypoint = "hello.py"

[branding]
name = "Preswald Project"
logo = "images/logo.png"
favicon = "images/favicon.ico"
primaryColor = "#F89613"

[data.sample_csv]
type = "csv"
path = "data/sample.csv"

[logging]
level = "INFO"  # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

​
Basic Configuration

​
[project]

  • title: Name of the app displayed in the interface.
  • version: Version of the app.
  • port: Port the app runs on (default is 8501).
  • disable_reactivity: (optional) Set to true to disable Preswald’s reactive runtime. When disabled, Preswald will rerun the entire script on every update instead of selectively recomputing affected parts using its dependency graph (DAG). This can be useful for debugging, performance benchmarking, or in environments where reactivity fallback is expected.

​
[branding]

  • name: Displayed name of the app.
  • logo: Path to the logo file (relative to the project directory).
  • favicon: Path to the favicon file.
  • primaryColor: The primary UI color, specified as a CSS-compatible color (e.g., #3498db).

​
Connecting to Data Sources

​
CSV Example: [data.sample_csv]

You can use a local or remote CSV file as a data source by defining it in preswald.toml.

​
Fields:

  • type: Use "csv".
  • path: Relative or absolute path to the CSV file, or a link to one

​
Example CSV Connections:

[data.customers_csv]
type = "csv"
path = "data/customers.csv"

[data.sample_csv]
type = "csv"
path = "https://storage.googleapis.com/test/sample_data.csv"

If the CSV file is located in a subdirectory, make sure the path is correct relative to the root directory.

​
JSON Example: [data.sample_json]

You can use a JSON file as a data source with options to normalize nested structures.

​
Fields:

  • type: Use "json".
  • path: Relative or absolute path to the JSON file.
  • record_path (optional): Specifies a nested key path in the JSON to extract records. If provided, only the records under this key are loaded.
  • flatten (optional): A Boolean flag that determines if nested JSON structures should be flattened. Defaults to true.

​
Example JSON Connection:

[data.sample_json]
type = "json"
path = "data/sample.json"
record_path = "results.items"  # Optional: Path to the records within the JSON
flatten = true                 # Optional: Set to false to retain nested structures

​
PostgreSQL Example: [data.sample_postgres]

  • type: Use "postgres".
  • host: Hostname or IP of the database server.
  • port: Port number for the database (default is 5432).
  • dbname: Name of the database.
  • user: Username for database access.

You should put the password for the postgres database in secrets.toml which is created via preswald init.

​
Example Postgres connection:

# preswald.toml
[data.earthquake_db]
type = "postgres"
host = "localhost"            # PostgreSQL host
port = 5432                   # PostgreSQL port
dbname = "earthquakes"        # Database name
user = "user"                 # Username

#secrets.toml
[data.earthquake_db]
password = ""

​
Clickhouse Example: [data.sample_clickhouse]

​
Fields:

  • type: Use "clickhouse".
  • host: Hostname or IP of the database server.
  • port: Port number for the database (default is 5432).
  • database: Name of the database.
  • user: Username for database access.

You should put the password for the postgres database in secrets.toml which is created via preswald init.

​
Example Clickhouse Connection:

# preswald.toml
[data.eq_clickhouse]
type = "clickhouse"
host = "localhost"
port = 8123
database = "default"
user = "default"

# secrets.toml
[data.eq_clickhouse]
password = ""

​
Parquet Example: [data.sample_parquet]

Preswald supports high-performance Parquet files for fast, memory-efficient data loading—ideal for large datasets or production pipelines.

​
Fields:

  • type: Use "parquet".
  • path: Path to a local .parquet file (absolute or relative).
  • columns: (optional) List of column names to load as a subset. Useful for large files with many columns.

​
Example Parquet Connection:

[data.sales_parquet]
type = "parquet"
path = "data/sales_data.parquet"

[data.analytics_subset]
type = "parquet"
path = "data/analytics.parquet"
columns = ["region", "revenue", "score"]

​
Logging Configuration

The [logging] section allows you to control the verbosity and format of logs generated by the app.

​
Fields:

  • level: Minimum severity level for log messages. Options:
    • DEBUG: Logs detailed debugging information.
    • INFO: Logs general app activity.
    • WARNING: Logs warnings or potential issues.
    • ERROR: Logs critical errors.
    • CRITICAL: Logs only severe issues that cause immediate failure.
  • format: Specifies the format of the log messages. Common placeholders:
    • %(asctime)s: Timestamp of the log entry.
    • %(name)s: Name of the logger.
    • %(levelname)s: Severity level of the log.
    • %(message)s: Log message content.

​
Example Logging Setup:

[logging]
level = "DEBUG"
format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

This configuration generates detailed logs, including timestamps, logger names, and log messages.

​
Telemetry Configuration

The [telemetry] section allows you to control whether usage data is collected to help improve Preswald.

​
Fields:

  • enabled: Controls whether telemetry data is collected
    • true (default): Enables telemetry data collection
    • false: Disables all telemetry data collection

The telemetry system collects basic usage data like:

  • Preswald version
  • Project identifier (slug)
  • Types of data sources being used
  • Command executions (without any sensitive data)

​
Example Telemetry Configuration:

To disable telemetry data collection, add this to your preswald.toml:

[telemetry]
enabled = false  # Disables all telemetry data collection

If the [telemetry] section is not present in your configuration, telemetry will be enabled by default to help improve Preswald.

When initializing a new Preswald project with preswald init, a default preswald.toml file is created. This file defines core settings for the app, including logging, theming, and data connections. Data connections can include databases like PostgreSQL or local CSV files.

​
Default Configuration (preswald.toml)

The following is the default structure of preswald.toml created during initialization:

​
Example preswald.toml

[project]
title = "Preswald Project"
version = "0.1.0"
port = 8501
slug = "preswald-project"
entrypoint = "hello.py"

[branding]
name = "Preswald Project"
logo = "images/logo.png"
favicon = "images/favicon.ico"
primaryColor = "#F89613"

[data.sample_csv]
type = "csv"
path = "data/sample.csv"

[logging]
level = "INFO"  # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

​
Basic Configuration

​
[project]

  • title: Name of the app displayed in the interface.
  • version: Version of the app.
  • port: Port the app runs on (default is 8501).
  • disable_reactivity: (optional) Set to true to disable Preswald’s reactive runtime. When disabled, Preswald will rerun the entire script on every update instead of selectively recomputing affected parts using its dependency graph (DAG). This can be useful for debugging, performance benchmarking, or in environments where reactivity fallback is expected.

​
[branding]

  • name: Displayed name of the app.
  • logo: Path to the logo file (relative to the project directory).
  • favicon: Path to the favicon file.
  • primaryColor: The primary UI color, specified as a CSS-compatible color (e.g., #3498db).

​
Connecting to Data Sources

​
CSV Example: [data.sample_csv]

You can use a local or remote CSV file as a data source by defining it in preswald.toml.

​
Fields:

  • type: Use "csv".
  • path: Relative or absolute path to the CSV file, or a link to one

​
Example CSV Connections:

[data.customers_csv]
type = "csv"
path = "data/customers.csv"

[data.sample_csv]
type = "csv"
path = "https://storage.googleapis.com/test/sample_data.csv"

If the CSV file is located in a subdirectory, make sure the path is correct relative to the root directory.

​
JSON Example: [data.sample_json]

You can use a JSON file as a data source with options to normalize nested structures.

​
Fields:

  • type: Use "json".
  • path: Relative or absolute path to the JSON file.
  • record_path (optional): Specifies a nested key path in the JSON to extract records. If provided, only the records under this key are loaded.
  • flatten (optional): A Boolean flag that determines if nested JSON structures should be flattened. Defaults to true.

​
Example JSON Connection:

[data.sample_json]
type = "json"
path = "data/sample.json"
record_path = "results.items"  # Optional: Path to the records within the JSON
flatten = true                 # Optional: Set to false to retain nested structures

​
PostgreSQL Example: [data.sample_postgres]

  • type: Use "postgres".
  • host: Hostname or IP of the database server.
  • port: Port number for the database (default is 5432).
  • dbname: Name of the database.
  • user: Username for database access.

You should put the password for the postgres database in secrets.toml which is created via preswald init.

​
Example Postgres connection:

# preswald.toml
[data.earthquake_db]
type = "postgres"
host = "localhost"            # PostgreSQL host
port = 5432                   # PostgreSQL port
dbname = "earthquakes"        # Database name
user = "user"                 # Username

#secrets.toml
[data.earthquake_db]
password = ""

​
Clickhouse Example: [data.sample_clickhouse]

​
Fields:

  • type: Use "clickhouse".
  • host: Hostname or IP of the database server.
  • port: Port number for the database (default is 5432).
  • database: Name of the database.
  • user: Username for database access.

You should put the password for the postgres database in secrets.toml which is created via preswald init.

​
Example Clickhouse Connection:

# preswald.toml
[data.eq_clickhouse]
type = "clickhouse"
host = "localhost"
port = 8123
database = "default"
user = "default"

# secrets.toml
[data.eq_clickhouse]
password = ""

​
Parquet Example: [data.sample_parquet]

Preswald supports high-performance Parquet files for fast, memory-efficient data loading—ideal for large datasets or production pipelines.

​
Fields:

  • type: Use "parquet".
  • path: Path to a local .parquet file (absolute or relative).
  • columns: (optional) List of column names to load as a subset. Useful for large files with many columns.

​
Example Parquet Connection:

[data.sales_parquet]
type = "parquet"
path = "data/sales_data.parquet"

[data.analytics_subset]
type = "parquet"
path = "data/analytics.parquet"
columns = ["region", "revenue", "score"]

​
Logging Configuration

The [logging] section allows you to control the verbosity and format of logs generated by the app.

​
Fields:

  • level: Minimum severity level for log messages. Options:
    • DEBUG: Logs detailed debugging information.
    • INFO: Logs general app activity.
    • WARNING: Logs warnings or potential issues.
    • ERROR: Logs critical errors.
    • CRITICAL: Logs only severe issues that cause immediate failure.
  • format: Specifies the format of the log messages. Common placeholders:
    • %(asctime)s: Timestamp of the log entry.
    • %(name)s: Name of the logger.
    • %(levelname)s: Severity level of the log.
    • %(message)s: Log message content.

​
Example Logging Setup:

[logging]
level = "DEBUG"
format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

This configuration generates detailed logs, including timestamps, logger names, and log messages.

​
Telemetry Configuration

The [telemetry] section allows you to control whether usage data is collected to help improve Preswald.

​
Fields:

  • enabled: Controls whether telemetry data is collected
    • true (default): Enables telemetry data collection
    • false: Disables all telemetry data collection

The telemetry system collects basic usage data like:

  • Preswald version
  • Project identifier (slug)
  • Types of data sources being used
  • Command executions (without any sensitive data)

​
Example Telemetry Configuration:

To disable telemetry data collection, add this to your preswald.toml:

[telemetry]
enabled = false  # Disables all telemetry data collection

If the [telemetry] section is not present in your configuration, telemetry will be enabled by default to help improve Preswald.