Skip to content

v6.2 #329

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
simonhammes wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

v6.2 #329

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
92918ac
notizen für special upgrade notices
christophdb Apr 23, 2026
ff037c4
Update configuration reference
simonhammes May 15, 2026
4118589
Document environment variables for dtable-db metrics
simonhammes May 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 72 additions & 10 deletions docs/configuration/components/dtable-api-gateway.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,85 @@
---
description: Complete reference for all api-gateway configuration options in dtable-api-gateway.conf including rate limits and cluster settings.
description: Complete reference for all api-gateway configuration options including rate limits and cluster settings.
---

# Configuration of api-gateway

This is a cheat sheet for the [api-gateway](/introduction/architecture.md#api-gateway) configuration file `dtable-api-gateway.conf`. It contains all possible settings that can be configured as well as their default values.
This is a cheat sheet for the possible configuration options of the [api-gateway](../../introduction/architecture.md#api-gateway).
It contains all possible settings that can be configured as well as their default values.

The default values provided here are best-effort (not built automatically). They will be used, if no value is defined at all.

In the default values below, a value in the form `$XYZ` refers to an environment variable.
The default values provided here are best-effort (not built automatically). They will be used if no value is defined at all.

??? tip "Configuration changes require a restart"

New configuration options will only apply after a restart of SeaTable.

## Environment Variables

<!-- md:version 6.2 -->

This section lists the environment variables read by the [api-gateway](../../introduction/architecture.md#api-gateway).

Please note that these variables are not included in `seatable-server.yml` by default.
We recommend that you do not modify the included `*.yml` files since any changes will be removed when upgrading SeaTable.
Instead, add an additional `custom-seatable-server.yml` file that includes the additional environment variables:

```yaml
services:
seatable-server:
environment:
- API_GATEWAY_BASE_API_LIMIT_PER_MINUTE=1000
```

This file then needs to be added to the `COMPOSE_FILE` variable inside your `.env` file.
This ensures that SeaTable upgrades stay seamless.

### General

| Environment Variable | Description | Default |
| --------------------------------------- | --------------------------------------------------- | ------- |
| `API_GATEWAY_HOST` | The address the api-gateway listens on. | 0.0.0.0 |
| `API_GATEWAY_PORT` | The port the api-gateway listens on. | 7780 |
| `API_GATEWAY_MAX_BASE_CACHE_SIZE` | Maximum base cache size in MB. | 1024 |
| `API_GATEWAY_BASE_API_LIMIT_PER_MINUTE` | Limits the number of API calls per base per minute. | 500 |

### dtable-db

| Environment Variable | Description | Default |
| --------------------- | ------------------------------ | --------------------- |
| `INNER_DTABLE_DB_URL` | URL of the dtable-db instance. | http://127.0.0.1:7777 |

### dtable-server

| Environment Variable | Description | Default |
| ------------------------- | ---------------------------------- | --------------------- |
| `INNER_DTABLE_SERVER_URL` | URL of the dtable-server instance. | http://127.0.0.1:5000 |

### Metrics

| Environment Variable | Description | Default |
| --------------------------------------- | -------------------------------------------------------------------- | ------- |
| `API_GATEWAY_METRICS_ENABLE_BASIC_AUTH` | Whether basic authentication is enabled for the `/metrics` endpoint. | false |
| `API_GATEWAY_METRICS_USERNAME` | Username for basic authentication for the `/metrics` endpoint. | |
| `API_GATEWAY_METRICS_PASSWORD` | Password for basic authentication for the `/metrics` endpoint. | |

### Access Logs

| Environment Variable | Description | Default |
| --------------------------------------------- | ---------------------------------------------------------------------------------------- | ------- |
| `API_GATEWAY_ENABLE_ACCESS_LOG` | Whether the api-gateway logs information about incoming HTTP requests to a Redis stream. | false |
| `API_GATEWAY_ACCESS_LOG_REDIS_STREAM_KEY` | Key of the Redis stream that will contain access log entries. | |
| `API_GATEWAY_ACCESS_LOG_REDIS_STREAM_MAX_LEN` | Maximum length of the Redis stream. | 100000 |

## Configuration File (Legacy)

!!! warning "Configuration file is not read anymore from v6.2 onwards"

`dtable-api-gateway.conf` will not be read anymore after upgrading from v6.1 to v6.2.

Please migrate any custom settings to the respective [environment variables](#environment-variables).

The following section describes the structure and possible configuration values of the configuration file `dtable-api-gateway.conf`.

??? abstract "Notes about the configuration file format"

The configuration file uses the **INI format**, which is a simple text-based format for storing configuration data. It consists of sections (denoted by square brackets, e.g., [general]) and key-value pairs.
Expand All @@ -22,14 +88,10 @@ In the default values below, a value in the form `$XYZ` refers to an environment

When dealing with special characters like single quotes `'`, double quotes `"` or the hash symbol `#`, it's generally best to enclose the value in double quotes.

The following options are grouped by their sections.

## Example configuration
**Example Configuration**

SeaTable does not create the `dtable-api-gateway.conf` file by default. The `api-gateway` will use the default configuration values if the file does not exist.

## Available configuration options

### `[general]`

This section contains general settings about api-gateway service.
Expand Down
110 changes: 102 additions & 8 deletions docs/configuration/components/dtable-db.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,115 @@
---
description: Complete reference for dtable-db configuration in dtable-db.conf including storage, caching, SQL limits, and big data backup options.
description: Complete reference for dtable-db configuration including storage, caching, SQL limits, and big data backup options.
---

# Configuration of dtable-db

This is a cheat sheet for the [dtable-db](/introduction/architecture.md#dtable-db) configuration file `dtable-db.conf`. It contains all possible settings that can be configured as well as their default values.
This is a cheat sheet for the possible configuration options of [dtable-db](../../introduction/architecture.md#dtable-db).
It contains all possible settings that can be configured as well as their default values.

The default values provided here are best-effort (not built automatically). They will be used, if no value is defined at all. It is not necessary the value, that is written in the configuration file on first startup.

In the default values below, a value in the form `$XYZ` refers to an environment variable.
The default values provided here are best-effort (not built automatically). They will be used if no value is defined at all.

??? tip "Configuration changes require a restart"

New configuration options will only apply after a restart of SeaTable.

## Environment Variables

<!-- md:version 6.2 -->

This section lists the environment variables read by [dtable-db](../../introduction/architecture.md#dtable-db).

Please note that these variables are not included in `seatable-server.yml` by default.
We recommend that you do not modify the included `*.yml` files since any changes will be removed when upgrading SeaTable.
Instead, add an additional `custom-seatable-server.yml` file that includes the additional environment variables:

```yaml
services:
seatable-server:
environment:
- DTABLE_DB_BACKUP_KEEP_NUM=100
```

This file then needs to be added to the `COMPOSE_FILE` variable inside your `.env` file.
This ensures that SeaTable upgrades stay seamless.

### General

| Environment Variable | Description | Default |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `DTABLE_DB_HOST` | The address dtable-db listens on. | 0.0.0.0 |
| `DTABLE_DB_PORT` | The port dtable-db listens on. | 7777 |
| `DTABLE_DB_SLOW_QUERY_THRESHOLD` | If the processing time exceeds this threshold, a slow log will be recorded in addition to the normal log. Unit is in milliseconds. | 1000 |
| `DTABLE_DB_ROW_UPDATE_LIMIT` | Sets the rate or row updates, deletes, and inserts per second and per base. | 5000 |
| `DTABLE_DB_GLOBAL_ROW_UPDATE_LIMIT` | Sets the global rate of row updates, deletes, and inserts per minute, affecting SQL and API operations. | 30000 |
| `DTABLE_DB_QUERY_PER_MINUTE_LIMIT` | Sets the total max. of API calls per minute for the entire system. The default is suitable for most cases. | 50000 |

### Storage

These settings define where the database files for bases with activated big data backend are stored and when old data is cleaned:

| Environment Variable | Description | Default |
| ------------------------------ | ------------------------------------------------------------- | --------------------- |
| `DTABLE_DB_DATA_DIR` | Location of the data directory inside the container. | /opt/seatable/db-data |
| `DTABLE_DB_STORAGE_CLEANUP_AT` | The execution time of clean up deleted data. Format is hh:mm. | 00:00 |

### DTable Cache

| Environment Variable | Description | Default |
| ---------------------------- | ---------------------------------- | --------------------- |
| `INNER_DTABLE_SERVER_URL` | URL of the dtable-server instance. | http://127.0.0.1:5000 |
| `DTABLE_DB_TOTAL_CACHE_SIZE` | The base cache size in MB. | 2000 |

### SQL

General configuration options of the output of the SQL endpoint:

| Environment Variable | Description | Default |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------- |
| `DTABLE_DB_SQL_DEFAULT_RESULT_ROWS` | Maximal number of rows returned by a query if there's no `LIMIT` specified. | 100 |
| `DTABLE_DB_SQL_RESULT_ROWS_HARD_LIMIT` | Maximal number of rows returned in one query (system wide). Overrides any larger `LIMIT` value in a query. | 10000 |
| `DTABLE_DB_SQL_EXEC_COST_HARD_LIMIT` | Maximal execution cost of a query. If the estimated cost of a query exceeds this limit, the query is rejected. | 5000000 |

### Backup

These settings allow configuring how data stored inside the big data backend is backed up:

| Environment Variable | Description | Default |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `DTABLE_DB_BACKUP_AT` | The execution time of backup. Format is `hh:mm`. | 02:00 |
| `DTABLE_DB_BACKUP_KEEP_NUM` | The number of backups that will be kept, oldest backups will be removed. | 3 |
| `DTABLE_DB_BACKUP_KEEP_DAYS` | Specifies the retention period for backups in days. Older backups are deleted. Overrides `DTABLE_DB_BACKUP_KEEP_NUM` if set; otherwise, `DTABLE_DB_BACKUP_KEEP_NUM` is used. | 0 |
| `DTABLE_DB_BACKUP_KEEP_FREQUENCY_DAYS` | Specifies daily backup period. After this, only one backup per month is kept. Requires `DTABLE_DB_BACKUP_KEEP_DAYS` to be set and > `DTABLE_DB_BACKUP_KEEP_FREQUENCY_DAYS`. | 0 |

**FIXME: dtable-storage-server URL is no longer configurable!?**

!!! warning "Two different backup methods: which should I choose?"

SeaTable offers two backup approaches:

- The first uses `DTABLE_DB_BACKUP_KEEP_NUM`, creating daily backups whenever changes were made and retaining a fixed number of the most recent ones, deleting the oldest when the limit is reached. Note that no new backup will be created if no changes were made to a base. This is the default option.

- The second approach, using `DTABLE_DB_BACKUP_KEEP_DAYS` and `DTABLE_DB_BACKUP_KEEP_FREQUENCY_DAYS`, offers a tiered retention strategy.
It creates daily backups for the recent period specified by `DTABLE_DB_BACKUP_KEEP_FREQUENCY_DAYS`, then switches to monthly backups for the older period.
This method provides detailed recent backups and efficient long-term storage, balancing data granularity with space conservation.
For example, setting `DTABLE_DB_BACKUP_KEEP_DAYS=180` and `DTABLE_DB_BACKUP_KEEP_FREQUENCY_DAYS=7` would keep daily backups for the past week, then monthly backups for the past six months (except for the past week).

### Metrics

| Environment Variable | Description | Default |
| ------------------------------------- | -------------------------------------------------------------------- | ------- |
| `DTABLE_DB_METRICS_ENABLE_BASIC_AUTH` | Whether basic authentication is enabled for the `/metrics` endpoint. | false |
| `DTABLE_DB_METRICS_USERNAME` | Username for basic authentication for the `/metrics` endpoint. | |
| `DTABLE_DB_METRICS_PASSWORD` | Password for basic authentication for the `/metrics` endpoint. | |

## Configuration File (Legacy)

!!! warning "Configuration file is not read anymore from v6.2 onwards"

`dtable-db.conf` will not be read anymore after upgrading from v6.1 to v6.2.

Please migrate any custom settings to the respective [environment variables](#environment-variables).

??? abstract "Notes about the configuration file format"

The configuration file uses the **INI format**, which is a simple text-based format for storing configuration data. It consists of sections (denoted by square brackets, e.g., [general]) and key-value pairs.
Expand All @@ -24,7 +120,7 @@ In the default values below, a value in the form `$XYZ` refers to an environment

The following options are grouped by their sections.

## Example configuration
**Example Configuration**

This is a typical configuration file, created automatically on the first startup by SeaTable.

Expand All @@ -45,8 +141,6 @@ dtable_storage_server_url = "http://127.0.0.1:6666"
keep_backup_num = 3
```

## Available configuration options

### `[general]`

This section contains general settings about `dtable-db` service.
Expand Down
Loading
Loading