docs: fix batch of upstream doc-change requests (#2688)

Author: killme2008

docs/reference/http-endpoints.md

@@ -291,6 +291,13 @@ Refer to the original Prometheus documentation for more information on the [Prom
 - **Description**: Compatible with Loki's API for log ingestion.
 - **Usage**: Send log data in Loki's format to this endpoint.
 
+### Splunk HEC Compatibility
+
+- **Path**: `/v1/splunk/services/collector/event`, `/v1/splunk/services/collector/raw`, `/v1/splunk/services/collector/health`
+- **Methods**: `POST` for the ingestion endpoints, `GET` for the health endpoint
+- **Description**: Compatible with the Splunk HTTP Event Collector (HEC) protocol for log ingestion.
+- **Usage**: Send JSON events to `/event` or plain text to `/raw`. See [Ingest Data with Splunk](/user-guide/ingest-data/for-observability/splunk.md).
+
 ### OpenTSDB Protocol
 
 - **Path**: `/v1/opentsdb/api/put`

docs/reference/sql/alter.md

@@ -194,6 +194,7 @@ Currently following options are supported:
 - `compaction.twcs.trigger_file_num`: the number of files in a specific time window to trigger a compaction.
 - `sst_format`: the SST format of the table. The value can be `flat` or `primary_key`. A table supports changing the format in both directions: `primary_key` to `flat` and `flat` to `primary_key`.
 - `write_buffer_size`: the per-region write buffer stall threshold of the table. For a positive value such as `512MB`, GreptimeDB schedules a flush when mutable memtable usage reaches half the value, stalls writes at the value, and rejects writes at twice the value. The table option overrides `region_engine.mito.default_region_write_buffer_size`. Setting it to `0` explicitly disables the per-region limit even when the engine default is nonzero. Unsetting it removes the table override and falls back to the engine default.
+- `auto_flush_interval`: how long a region of this table may go without a flush before one is triggered. The value is a [time duration string](/reference/time-durations.md) and must be greater than zero. The table option overrides the engine-wide `region_engine.mito.auto_flush_interval`.
 
 ```sql
 ALTER TABLE monitor SET 'ttl'='1d';
@@ -211,8 +212,22 @@ ALTER TABLE monitor SET 'sst_format'='flat';
 ALTER TABLE monitor SET 'sst_format'='primary_key';
 
 ALTER TABLE monitor SET 'write_buffer_size'='512MB';
+
+ALTER TABLE monitor SET 'auto_flush_interval'='5m';
 ```
 
+To drop the `auto_flush_interval` override and fall back to the engine-wide setting, set it
+to `NULL`:
+
+```sql
+ALTER TABLE monitor SET 'auto_flush_interval' = NULL;
+```
+
+:::warning
+`auto_flush_interval` does not support `UNSET`. `ALTER TABLE monitor UNSET 'auto_flush_interval'`
+returns an error; use `SET ... = NULL` as shown above.
+:::
+
 ### Unset table options
 
 ```sql

docs/reference/sql/copy.md

@@ -138,13 +138,40 @@ COPY tbl FROM '/path/to/file.csv' WITH (
 | `COMPRESSION_TYPE` | Compression algorithm for the imported file. Supported values: `gzip`, `zstd`, `bzip2`, `xz`. Only supported for CSV and JSON formats. | Optional |
 | `HEADERS` | Whether the CSV file has a header row. Supported values: `true`, `false`. Default is `true`. | Optional |
 | `SKIP_BAD_RECORDS` | Whether to skip rows with parsing or casting errors during CSV import. Supported values: `true`, `false`. Default is `false`. Only supported for CSV format. | Optional |
+| `STRICT_HEADERS` | Whether to validate CSV headers against the table schema before importing. Supported values: `true`, `false`. Default is `false`. Only supported for CSV format, and requires `HEADERS = 'true'`. | Optional |
 
 :::tip NOTE
 By default, CSV files are parsed with headers and columns are matched by name.
 
 To import headerless CSV files, set `HEADERS = 'false'`. In this mode, columns are mapped by position following the target table schema order. You can use `SHOW CREATE TABLE <table_name>` to inspect the table column order.
 :::
 
+#### STRICT_HEADERS Option
+
+By default, header matching is lenient: CSV columns the table does not have are ignored, and table columns the CSV does not have fall back to the normal insert and default-value handling.
+
+Set `STRICT_HEADERS = 'true'` to validate the header row before any data is read. The import fails if the CSV has:
+
+- a column the table does not have,
+- no column for a column the table does have,
+- the same header name more than once.
+
+```sql
+COPY monitor FROM 'monitor.csv' WITH (FORMAT = 'CSV', STRICT_HEADERS = 'true');
+```
+
+A mismatch reports all three categories at once:
+
+```
+ERROR:  CSV header mismatch in path: monitor.csv, unknown columns: ["extra"], missing columns: [], duplicate columns: []
+```
+
+:::warning
+The missing-column check covers **every** column in the table, including nullable columns and columns with a default value. A CSV that omits any of them is rejected.
+
+`STRICT_HEADERS = 'true'` cannot be combined with `HEADERS = 'false'` — a headerless CSV has no header names to validate. The combination returns `strict_headers=true requires headers=true`.
+:::
+
 #### `CONNECTION` Option
 
 `COPY FROM` also supports importing data from cloud storage services. See [connect-to-s3](#connect-to-s3), [connect-to-gcs](#connect-to-gcs), or [connect-to-azure-blob-storage](#connect-to-azure-blob-storage) for more details.

docs/reference/sql/create.md

@@ -162,6 +162,7 @@ Users can add table options by using `WITH`. The valid options contain the follo
 | `comment`                                   | Table level comment                                             | String value.                                                                                                                                                                                                                                               |
 | `skip_wal`                                | Whether to disable Write-Ahead-Log for this table                               | String type. When set to `'true'`, the data written to the table will not be persisted to the write-ahead log, which can avoid storage wear and improve write throughput. However, when the process restarts, any unflushed data will be lost. Please use this feature only when the data source itself can ensure reliability. |
 | `write_buffer_size`                       | Per-region write buffer stall threshold for this table                          | String type, such as `'512MB'` or `'1GB'`. For a positive value, GreptimeDB schedules a flush when mutable memtable usage reaches half the value, stalls writes at the value, and rejects writes at twice the value. The table option overrides `region_engine.mito.default_region_write_buffer_size`. An explicit `'0'` disables the per-region limit even when the engine default is nonzero. Unset the option to remove the table override and fall back to the engine default. |
+| `auto_flush_interval`                     | How long a region of this table may go without a flush before one is triggered | String type, a time duration such as `'5m'` or `'1h'`. Must be greater than zero. The table option overrides the engine-wide `region_engine.mito.auto_flush_interval`. Set it to `NULL` with `ALTER TABLE` to drop the override and fall back to the engine setting. |
 | `index.type`                                | Index type                                                      | **Only for metric engine** String value, supports `none`, `skipping`.                                                                                                                                                                                       |
 
 #### Create a table with TTL

docs/user-guide/deployments-administration/authentication/static.md

@@ -60,13 +60,15 @@ Since v1.1, a password can use an explicit verifier format, so that plaintext pa
 - `plain:<password>` — plaintext. This is the default when no prefix is given.
 - `pbkdf2_sha256:<iterations>:<hex_salt>:<hex_hash>` — a PBKDF2-SHA256 hash stored at rest.
 - `mysql_native_password:<hex_sha1_sha1_password>` — a hashed verifier that still serves the MySQL `mysql_native_password` handshake.
+- `pg_scram_sha256:<iterations>:<hex_salt>:<hex_stored_key>:<hex_server_key>` — a SCRAM-SHA-256 verifier that serves the PostgreSQL SASL handshake. Available since v1.2.
 
 Example:
 
 ```
 admin=plain:admin_pwd
 alice=pbkdf2_sha256:4096:73616c74:c5e478d59288c841aa530db6845c4c8d962893a001ce4e11a4963873aa98134a
 bob=mysql_native_password:6bb4837eb74329105ee4568dda7dc67ed2ca2ad9
+carol=pg_scram_sha256:4096:73616c74:53706a13f10b3c031b4c355d75ebd6500d3478062ce7d262710c3e60de02b93f:a19ce79824bd7ad68d96b8c00b0f1cc776bd0feca54d663301bb9866a860545b
 ```
 
 Permission modes combine with verifier formats. The verifier goes after the `=`:
@@ -79,18 +81,39 @@ alice:readonly=pbkdf2_sha256:4096:73616c74:c5e478d59288c841aa530db6845c4c8d96289
 
 A single verifier format does not serve every protocol. Choose the format based on how clients connect:
 
-| Verifier | HTTP/gRPC Basic | PostgreSQL cleartext | MySQL clear password | MySQL `mysql_native_password` |
-| --- | --- | --- | --- | --- |
-| `plain:<password>` (or legacy `user=password`) | yes | yes | yes | yes |
-| `pbkdf2_sha256:...` | yes | yes | yes | no |
-| `mysql_native_password:...` | no | no | no | yes |
+| Verifier | HTTP/gRPC Basic | PostgreSQL SCRAM-SHA-256 | PostgreSQL cleartext | MySQL clear password | MySQL `mysql_native_password` |
+| --- | --- | --- | --- | --- | --- |
+| `plain:<password>` (or legacy `user=password`) | yes | yes | yes | yes | yes |
+| `pbkdf2_sha256:...` | yes | no | yes | yes | no |
+| `mysql_native_password:...` | no | no | no | no | yes |
+| `pg_scram_sha256:...` | yes | yes | yes | yes | no |
 
 `pbkdf2_sha256` protects passwords at rest; it does not change wire security. Cleartext-capable protocols still need TLS in production.
 
 :::warning Breaking change
-Passwords are prefix-parsed. A legacy plaintext password that literally starts with `plain:`, `pbkdf2_sha256:`, or `mysql_native_password:` changes meaning. Use the `plain:` prefix to keep the literal value. For example, to keep the literal password `plain:secret`, configure it as `user=plain:plain:secret`.
+Passwords are prefix-parsed. A legacy plaintext password that literally starts with `plain:`, `pbkdf2_sha256:`, `mysql_native_password:`, or `pg_scram_sha256:` changes meaning. Use the `plain:` prefix to keep the literal value. For example, to keep the literal password `plain:secret`, configure it as `user=plain:plain:secret`.
 :::
 
+#### PostgreSQL SCRAM-SHA-256
+
+SCRAM-SHA-256 lets PostgreSQL clients authenticate without sending the password in cleartext.
+
+PostgreSQL negotiates a single authentication method when a connection starts. The server does receive the username at that point, but picking the method per user would reveal whether that user exists and what verifier format it uses. GreptimeDB therefore decides globally: it offers SCRAM only when **every** user in the credential file can do SCRAM — that is, every verifier is `plain:` or `pg_scram_sha256:`. An unknown username is answered with a throwaway verifier and still runs the full handshake, so a failed login looks the same as a wrong password.
+
+:::warning
+A single `pbkdf2_sha256:` or `mysql_native_password:` user makes the whole instance fall back to cleartext for PostgreSQL, including users whose own verifier supports SCRAM. If you want SCRAM, do not mix verifier formats.
+:::
+
+Channel binding (`SCRAM-SHA-256-PLUS`) is not supported.
+
+You can check which method the server offers with libpq's `require_auth` parameter, which needs libpq or `psql` 16 or newer:
+
+```shell
+psql "host=127.0.0.1 port=4003 user=carol dbname=public require_auth=scram-sha-256"
+```
+
+When the instance has fallen back to cleartext, that command fails with `server requested a cleartext password`.
+
 ### Generating Password Verifiers
 
 Since v1.1, you can use the `greptime user hash-password` command to generate a verifier string. It runs standalone without starting any server component:
@@ -113,10 +136,10 @@ admin=pbkdf2_sha256:4096:<random_hex_salt>:<hex_hash>
 
 Options:
 
-- `--format <FORMAT>` — verifier format, `pbkdf2_sha256` (default) or `mysql_native_password`.
+- `--format <FORMAT>` — verifier format, `pbkdf2_sha256` (default), `mysql_native_password`, or `pg_scram_sha256`.
 - `--password <PASSWORD>` — plaintext password. Mutually exclusive with `--password-stdin`; exactly one is required. Prefer `--password-stdin` in scripts, since `--password` can leak through shell history or process listings.
 - `--password-stdin` — read the plaintext password from stdin.
-- `--iterations <N>` — PBKDF2-SHA256 iteration count (default `4096`, range `1..=1000000`).
+- `--iterations <N>` — PBKDF2-SHA256 / SCRAM-SHA-256 iteration count (default `4096`, range `1..=1000000`).
 - `--salt-len <N>` — random salt length in bytes (default `16`, range `1..=1024`).
 - `--salt-hex <HEX>` — fixed salt as hex instead of a random one, for deterministic automation.
 
@@ -126,6 +149,12 @@ To generate a `mysql_native_password` verifier instead:
 ./greptime user hash-password --password-stdin --format mysql_native_password
 ```
 
+To generate a PostgreSQL SCRAM-SHA-256 verifier:
+
+```shell
+./greptime user hash-password --password-stdin --format pg_scram_sha256
+```
+
 ### Starting the Server
 
 Start the server with the `--user-provider` parameter and set it to `static_user_provider:file:<path_to_file>` (replace `<path_to_file>` with the path to your user configuration file):

docs/user-guide/deployments-administration/configuration.md

@@ -617,7 +617,7 @@ Available options:
 | `max_background_flushes`                 | Integer | `Auto` | Max number of running background flush jobs (default: 1/2 of cpu cores).                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `max_background_compactions`            | Integer | `Auto` | Max number of running background compaction jobs (default: 1/4 of cpu cores).                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `max_background_purges`                | Integer | `Auto` | Max number of running background purge jobs (default: cpu cores).                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `auto_flush_interval`                    | String  | `1h`          | Interval to auto flush a region if it has not flushed yet.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `auto_flush_interval`                    | String  | `1h`          | Interval to auto flush a region if it has not flushed yet. Can be overridden per table with the [`auto_flush_interval` table option](/reference/sql/create.md#table-options).                                                                                                                                                                                                                                                                                                                       |
 | `global_write_buffer_size`               | String  | `1GB`         | Global write buffer size for all regions. If not set, it's default to 1/8 of OS memory with a max limitation of 1GB.                                                                                                                                                                                                                                                                                                                                                                               |
 | `global_write_buffer_reject_size`        | String  | `2GB`         | Global write buffer size threshold to reject write requests. If not set, it's default to 2 times of `global_write_buffer_size`                                                                                                                                                                                                                                                                                                                                                                     |
 | `default_region_write_buffer_size`       | String  | `0`           | Default per-region write buffer stall threshold. For a positive value, GreptimeDB schedules a flush when mutable memtable usage reaches half the value, stalls writes at the value, and rejects writes at twice the value. Setting it to `0` disables the default per-region limit. A table's `write_buffer_size` overrides this value, including an explicit `0` that disables the limit for that table.                                                                                                                                                              |

docs/user-guide/deployments-administration/deploy-on-kubernetes/common-helm-chart-configurations.md

@@ -621,7 +621,7 @@ datanode:
     [region_engine.mito.gc]
     enable = true
     lingering_time = "10m"
-    unknown_file_lingering_time = "1h"
+    unknown_file_lingering_time = "1d"
 ```
 
 Make sure the datanode `lingering_time` is longer than the metasrv `gc_cooldown_period` to avoid deleting files that may still be in use.