WIP - docs: reorganize ColdFront docs into the standard pgedge nav structure by susan-pgedge · Pull Request #114 · pgEdge/coldfront

susan-pgedge · 2026-10-09T12:25:56Z

Summary

Reorganizes mkdocs.yml's nav into the standard pgedge-docs template, preserving every original page as a flat link list on the new Source page.
Splits installation, configuration, and Lakekeeper/object-store setup into dedicated guides, and splits day-to-day usage by operating mode (Tiered, Decoupled, Standalone Partitioned), with a new Administration section for shared operational topics (caveats, vended credentials, reading and writing, supported types, distributed setup, compaction).
Converts the Using ColdFront and Architecture Guides sections to real index.md pages so their nav headers open the intro content directly, with no duplicate nav entry.

Test plan

mkdocs build --strict passes with no warnings
Spot-check the nav in a local preview (mkdocs serve): Using ColdFront, Architecture Guides, and Administration all render and link correctly
Confirm README.md and docs/index.md still list every guide

coderabbitai · 2026-10-09T12:26:06Z

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

codacy-production · 2026-10-09T12:27:04Z

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer}
_{TIP This summary will be updated as you push new changes.}

Splits usage.md's three operating modes into their own guides, moves shared operational topics into a new Administration nav section, and converts the Using ColdFront and Architecture Guides sections to real index.md pages so their nav headers open directly without a duplicate child link.

…d index.md Moves the Least-Privilege Application Roles content into a new Connecting to ColdFront guide, renames and restructures the Getting Started walkthrough into Exploring ColdFront - Getting Started, folds the Caveats pointer into a new Resources/Exploring ColdFront with Walkthroughs section on the landing page, and polishes wording across installation.md, configuration.md, and one_time_setup.md.

- Rename the distributed setup page to Configuring a Distributed Deployment and move it under Configuring ColdFront. - Fold reading_writing.md into other pages and remove it. - Rework supported_types.md and rename it Supported Column Types. - Move the build step into the compaction intro and drop the Usage, Requirements, and Next Steps headings. - Bring the README table of contents and documentation table in line with the nav.

vyruss

Wow, that's a lot of work! I think it looks good.

vyruss · 2026-10-13T19:00:35Z

+Other data types (unbounded `numeric`, `xml`, `tsvector`, range/multirange types,
+custom enums, composite types, pgvector's `sparsevec`, `inet`, `cidr`, `oid`,
+and the arrays that [Supported Array Types](#supported-array-types) lists
+as refused at registration) is


I read this as "Other data types (...) are rejected"

vyruss

New and changed text for these pages, placed where each part belongs.

vyruss · 2026-10-13T19:25:46Z

+    - a `--sub-values-source` without a `--column`.
+    - a table with neither a `--hot-period` nor a `--retention`.
+
+- any relation in the partition tree is `UNLOGGED`, because that data is


Registration also refuses a column that is not the partition key:

Suggested change

- any relation in the partition tree is `UNLOGGED`, because that data is

- `--column`, or `partition_column` on `import`, names a column that is not the

table's partition key. On a two-level table, registration refuses only a

column that the table lacks. The refusal names the flag or key and, for a

flat table, the table's partition key.

- any relation in the partition tree is `UNLOGGED`, because that data is

vyruss · 2026-10-13T19:39:19Z

+  value in a `date`, `timestamp with time zone` or `timestamp without time
+  zone` column, as array elements too. ColdFront refuses those values with
+  a check constraint named `coldfront_guard_<column>`; a write that goes to
+  the cold tier, in either mode, is refused by DuckDB.


The exception for a numeric NaN read from a PostgreSQL table:

Suggested change

the cold tier, in either mode, is refused by DuckDB.

the cold tier, in either mode, is refused by DuckDB, unless the write reads a

`numeric` `NaN` from a PostgreSQL table and stores it as `0`.

vyruss · 2026-10-13T19:39:19Z

+1, such as `'[0:2]={1,2,3}'`. The hot table's check constraint refuses such an
+array when it is written. A write to the cold tier refuses it too: a tiered
+`INSERT` with an error that names the column, and a bound parameter with an
+error that names no column. A tiered table with a column declared with more


An array read from a PostgreSQL table is stored renumbered, not refused:

Suggested change

error that names no column. A tiered table with a column declared with more

error that names no column. A write that reads the array from a PostgreSQL

table stores it renumbered from 1 instead. A tiered table with a column

declared with more

vyruss · 2026-10-13T19:39:19Z

+- **Azure ADLS Gen2** needs a storage account, a filesystem (container)
+  in that account, and the account's access key.


The storage account needs hierarchical namespace:

Suggested change

- **Azure ADLS Gen2** needs a storage account, a filesystem (container)

in that account, and the account's access key.

- **Azure ADLS Gen2** needs a storage account with hierarchical namespace

enabled (for example, `az storage account create --hns true`), a filesystem

(container) in that account, and the account's access key. A StorageV2

account without hierarchical namespace is not an ADLS Gen2 account, and

Lakekeeper's `adls` warehouse fails on it.

vyruss · 2026-10-13T19:39:36Z

Lines 75-80 become:

attaches as `pglocal`. A write that reads a PostgreSQL table uses it: an `INSERT ... SELECT`, an `UPDATE ... FROM`, a `DELETE ... USING`, or a `MERGE` whose source is a PostgreSQL table. The GUC is `PGC_SUSET` and superuser-only, because the DSN can hold credentials. `set_storage_secret` installs the `postgres` extension when the GUC is set, and `coldfront.ensure_pg_attached()` attaches `pglocal` when such a write runs. With the GUC unset, that write fails, because DuckDB has no `pglocal` catalog to resolve. The extension reads a `numeric` `NaN` as `0` and renumbers an array to start at 1, so such a write can store a changed value, as [Supported Column Types](supported_types.md) describes.

vyruss · 2026-10-13T19:52:58Z

+A cold `UPDATE ... FROM`, a `MERGE` whose source is a PostgreSQL table, and an
+`INSERT ... SELECT` into a decoupled table read that PostgreSQL table through
+DuckDB's postgres extension, which reads a `numeric` `NaN` as `0` and drops an
+array's lower bound. ColdFront cannot refuse those values on that path, so
+filter them out of such a source.


The writes that read a PostgreSQL table this way, and what they do with the changed values:

Suggested change

A cold `UPDATE ... FROM`, a `MERGE` whose source is a PostgreSQL table, and an

`INSERT ... SELECT` into a decoupled table read that PostgreSQL table through

DuckDB's postgres extension, which reads a `numeric` `NaN` as `0` and drops an

array's lower bound. ColdFront cannot refuse those values on that path, so

filter them out of such a source.

A cold `UPDATE ... FROM` or `DELETE ... USING`, a `MERGE` whose source is a

PostgreSQL table, and an `INSERT ... SELECT` into a decoupled table read that

PostgreSQL table through DuckDB's postgres extension, which reads a `numeric`

`NaN` as `0`, also inside an array, and drops an array's lower bound. ColdFront

cannot refuse those values on that path: the write stores the changed values

with no error, and its conditions compare the changed values. A condition that

names `'NaN'` fails in such a write, because DuckDB does not accept `'NaN'` as

a `numeric` value. To keep those values out of the cold tier, check the source

table in PostgreSQL before the write, and fix or remove the rows that hold

them.

vyruss · 2026-10-13T19:52:58Z

+DuckDB's postgres extension, which reads a `numeric` `NaN` as `0` and drops an
+array's lower bound. ColdFront cannot refuse those values on that path, so
+filter them out of such a source.
+


A query that finds those rows in a source table:

Suggested change

The following query counts those rows in a source table `staging` with a

`numeric` column `amount`, a `numeric` array `amounts` and an array `tags`:

```sql

SELECT count(*)

FROM staging

WHERE amount = 'NaN'

OR 'NaN' = ANY (amounts)

OR array_lower(tags, 1) <> 1;

```

List every `numeric` column, `numeric` array and array column of your source

table the same way; a count of `0` means that the write stores those columns

unchanged.

vyruss · 2026-10-13T20:01:59Z

+  and change feed (blob events) to be OFF on the storage account. Lakekeeper
+  warehouse creation otherwise fails with HTTP 409 ("This endpoint does not
+  support BlobStorageEvents or SoftDelete"). Disable those features on the
+  storage account before using it as a cold tier.


The caveat for a cold-tier write that reads a PostgreSQL table:

Suggested change

storage account before using it as a cold tier.

storage account before using it as a cold tier.

- A cold-tier write that reads an ordinary PostgreSQL table, such as an

`UPDATE ... FROM` or a `MERGE` from one, stores a `numeric` `NaN` from that

table as `0` and stores an array renumbered to start at 1, with no error.

[Supported Column Types](supported_types.md) lists the writes that do this

and shows how to check a source table first.

susan-pgedge changed the title ~~docs: reorganize ColdFront docs into the standard pgedge nav structure~~ WIP - docs: reorganize ColdFront docs into the standard pgedge nav structure Oct 9, 2026

susan-pgedge force-pushed the docs/standard-toc-experiment branch from a8b3021 to f724af6 Compare October 13, 2026 11:15

susan-pgedge mentioned this pull request Oct 13, 2026

Preview ColdFront docs for PR 114 pgEdge/pgedge-docs#205

Open

2 tasks

Susan Douglas added 3 commits October 13, 2026 10:39

docs: remove the temporary Source page and its nav entry

0073410

vyruss reviewed Oct 13, 2026

View reviewed changes

-- any relation in the partition tree is `UNLOGGED`, because that data is
+- `--column`, or `partition_column` on `import`, names a column that is not the
+  table's partition key. On a two-level table, registration refuses only a
+  column that the table lacks. The refusal names the flag or key and, for a
+  flat table, the table's partition key.
+- any relation in the partition tree is `UNLOGGED`, because that data is

	the cold tier, in either mode, is refused by DuckDB.
	the cold tier, in either mode, is refused by DuckDB, unless the write reads a
	`numeric` `NaN` from a PostgreSQL table and stores it as `0`.

		- Azure ADLS Gen2 needs a storage account, a filesystem (container)
		in that account, and the account's access key.

-- **Azure ADLS Gen2** needs a storage account, a filesystem (container)
-  in that account, and the account's access key.
+- **Azure ADLS Gen2** needs a storage account with hierarchical namespace
+  enabled (for example, `az storage account create --hns true`), a filesystem
+  (container) in that account, and the account's access key. A StorageV2
+  account without hierarchical namespace is not an ADLS Gen2 account, and
+  Lakekeeper's `adls` warehouse fails on it.

-A cold `UPDATE ... FROM`, a `MERGE` whose source is a PostgreSQL table, and an
-`INSERT ... SELECT` into a decoupled table read that PostgreSQL table through
-DuckDB's postgres extension, which reads a `numeric` `NaN` as `0` and drops an
-array's lower bound. ColdFront cannot refuse those values on that path, so
-filter them out of such a source.
+A cold `UPDATE ... FROM` or `DELETE ... USING`, a `MERGE` whose source is a
+PostgreSQL table, and an `INSERT ... SELECT` into a decoupled table read that
+PostgreSQL table through DuckDB's postgres extension, which reads a `numeric`
+`NaN` as `0`, also inside an array, and drops an array's lower bound. ColdFront
+cannot refuse those values on that path: the write stores the changed values
+with no error, and its conditions compare the changed values. A condition that
+names `'NaN'` fails in such a write, because DuckDB does not accept `'NaN'` as
+a `numeric` value. To keep those values out of the cold tier, check the source
+table in PostgreSQL before the write, and fix or remove the rows that hold
+them.

+The following query counts those rows in a source table `staging` with a
+`numeric` column `amount`, a `numeric` array `amounts` and an array `tags`:
+```sql
+SELECT count(*)
+  FROM staging
+ WHERE amount = 'NaN'
+    OR 'NaN' = ANY (amounts)
+    OR array_lower(tags, 1) <> 1;
+```
+List every `numeric` column, `numeric` array and array column of your source
+table the same way; a count of `0` means that the write stores those columns
+unchanged.

-  storage account before using it as a cold tier.
+  storage account before using it as a cold tier.
+- A cold-tier write that reads an ordinary PostgreSQL table, such as an
+  `UPDATE ... FROM` or a `MERGE` from one, stores a `numeric` `NaN` from that
+  table as `0` and stores an array renumbered to start at 1, with no error.
+  [Supported Column Types](supported_types.md) lists the writes that do this
+  and shows how to check a source table first.

Conversation

susan-pgedge commented Oct 9, 2026

Summary

Test plan

Uh oh!

coderabbitai Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Draft PR not reviewed

Uh oh!

codacy-production Bot commented Oct 9, 2026

Up to standards ✅

Uh oh!

vyruss left a comment

Choose a reason for hiding this comment

Uh oh!

vyruss Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

vyruss left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vyruss Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vyruss Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vyruss Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vyruss Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

vyruss Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vyruss Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vyruss Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

vyruss Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coderabbitai Bot commented Oct 9, 2026 •

edited

Loading

vyruss left a comment •

edited

Loading

vyruss Oct 13, 2026 •

edited

Loading

vyruss Oct 13, 2026 •

edited

Loading

vyruss Oct 13, 2026 •

edited

Loading

vyruss Oct 13, 2026 •

edited

Loading

vyruss Oct 13, 2026 •

edited

Loading