Configuration

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).

​

[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.