docs: Document PostgreSQL DML support and acceleration.write_mode

website/docs/components/data-connectors/postgres/index.md

@@ -2,6 +2,10 @@
 title: 'PostgreSQL Data Connector'
 sidebar_label: 'PostgreSQL Data Connector'
 description: 'PostgreSQL Data Connector Documentation'
+tags:
+  - data-connectors
+  - postgres
+  - write
 ---
 
 PostgreSQL is an advanced open-source relational database management system known for its reliability, extensibility, and support for SQL compliance.
@@ -171,6 +175,69 @@ The Postgres federated queries may result in unexpected result types due to the
 
 :::
 
+## Write Support
+
+The PostgreSQL connector supports writing data to PostgreSQL tables using SQL [`INSERT INTO`](../../../reference/sql/dml#insert), `UPDATE`, and `DELETE FROM` statements.
+
+To enable writes, set `access: read_write` on the dataset:
+
+```yaml
+datasets:
+  - from: postgres:public.events
+    name: events
+    access: read_write
+    params:
+      pg_host: localhost
+      pg_port: '5432'
+      pg_db: mydb
+      pg_user: spice_writer
+      pg_pass: ${secrets:PG_PASSWORD}
+```
+
+```sql
+-- Insert rows
+INSERT INTO events (id, name, amount)
+VALUES (1, 'Alice', 100.0), (2, 'Bob', 200.0);
+
+-- Update rows
+UPDATE events SET amount = 150.0 WHERE id = 1;
+
+-- Delete rows
+DELETE FROM events WHERE id = 2;
+```
+
+### Write modes with acceleration
+
+When PostgreSQL is used as the federated source for an accelerated dataset, `acceleration.write_mode` selects how writes propagate between the local accelerator and PostgreSQL:
+
+- `write_through` (default) — writes are sent to PostgreSQL synchronously. The client receives an ACK only after the source commits. The local accelerator is updated via the configured refresh path. Choose this for ACID guarantees.
+- `write_back` — writes are applied to the local accelerator first (fast ACK), then forwarded asynchronously to PostgreSQL. Choose this for write throughput when eventual consistency at the source is acceptable.
+
+`acceleration.refresh_mode: changes` is supported for `access: read_write` datasets: writes go to PostgreSQL and the WAL replication stream applies the resulting changes back to the accelerator.
+
+```yaml
+datasets:
+  - from: postgres:public.events
+    name: events
+    access: read_write
+    params:
+      pg_host: localhost
+      pg_port: '5432'
+      pg_db: mydb
+      pg_user: spice_writer
+      pg_pass: ${secrets:PG_PASSWORD}
+      # Replication-mode parameters (see Configuration above)
+      pg_replication_publication: spice_pub
+      pg_replication_slot_name: spice_slot
+    acceleration:
+      engine: duckdb
+      mode: file
+      refresh_mode: changes
+      write_mode: write_through # default; use write_back for fast async writes
+```
+
+For more details, see [Data Ingestion](../../../features/data-ingestion).
+
 ## Examples
 
 ### Connecting using Username/Password

website/docs/reference/spicepod/datasets.md

@@ -467,6 +467,15 @@ Optional. How to refresh the dataset. The following values are supported:
 - `caching` - Cache data based on request metadata (HTTP requests). Uses row-level replacement based on cache keys. See [Caching Mode](../../features/data-acceleration/refresh-modes/caching) for details.
 - `snapshot` - Reload exclusively from the [snapshot store](../../features/data-acceleration/snapshots). The federated source is never queried; the runtime polls for newer snapshots at `refresh_check_interval` (default: 60s). Requires `acceleration.snapshots: enabled` or `bootstrap_only` and a snapshot-capable file-based engine (DuckDB, SQLite, Cayenne, or Turso). Writes (`INSERT INTO`) are rejected. See [Snapshot Refresh Mode](../../features/data-acceleration/data-refresh#snapshot).
 
+## `acceleration.write_mode`
+
+Optional. Controls how writes to a `read_write` accelerated dataset propagate between the local accelerator and the federated source. Only applies when the dataset has `access: read_write` and the source connector supports writes.
+
+Supported values:
+
+- `write_through` (default) – Writes are sent to the federated source synchronously. The client receives an ACK only after the source commits the change, providing ACID guarantees. The local accelerator is updated through the configured refresh path (for example, the WAL stream when `refresh_mode: changes`).
+- `write_back` – Writes are applied to the local accelerator first (fast ACK), then forwarded asynchronously to the federated source. Choose this for write throughput when eventual consistency at the source is acceptable.
+
 ## `acceleration.refresh_check_interval`
 
 Optional. How often data should be refreshed. For `append` datasets without a specific `time_column`, this config is not used. If not defined, the accelerator will not refresh after it initially loads data. Cannot be specified in conjunction with a `refresh_cron`.