Provider / PostgreSQL wire
PreviewPGlite
PGlite provides SQL-backed metadata and blocks through PostgreSQL wire connections. It is useful when a JavaScript-hosted PostgreSQL engine is already part of the process or service, but the server's storage policy must be treated as an explicit application decision.
mount_rs_metadata stores one row per volume_keywith namespace text, revision, writer owner, fence, expiry, and a stable volume_id. Versioning addsmount_rs_schema_versions, mount_rs_version_state,mount_rs_versions, and mount_rs_version_pins; each record keeps sequence, parent/restore/fork links, namespace JSON, block-store ID, kind, timestamp, durability, and lease-pin ownership explicit. The metadata connection and block connection are independent.
mount_rs_blocks(volume_key, id, bytes) stores BYTEA blocks. IDs are derived from the bytes and a conflict is checked before an existing row is reused.
Storage anatomy
Follow one file through both planes.
A mount-rs namespace stores names, attributes, directory entries, layouts, and block references. The bytes stay in the independent block plane. The example below is illustrative; the provider-specific schema, keys, and prefixes are the inspectable contract.
inode 42 · size 8,192NodeMetadata → NodeData::File(FileLayout)BlockId → raw bytesNamespace {
nodes[42] = NodeMetadata {
stats: { ino: 42, size: 8192, mode: regular },
data: File(FileLayout {
chunker: { algorithm: "fixed-size", version: 1, chunk_size: 4096 },
extents: [
{ file_offset: 0, block: "b012...", block_offset: 0, length: 4096 },
{ file_offset: 4096, block: "bfed...", block_offset: 0, length: 4096 }
]
})
}
}
BlockId "b012..." -> [4 KiB raw bytes]
BlockId "bfed..." -> [4 KiB raw bytes]Relational storage
PGlite / PostgreSQL wire schema
The split provider creates two tables in the caller-selected PostgreSQL-compatible database. The volume key scopes metadata and bytes independently.
mount_rs_metadata
One row per volume: namespace JSON plus revision and writer lease.
| Column | Type | Stored meaning |
|---|---|---|
volume_key | TEXT | PRIMARY KEY; independent volume scope |
revision | BIGINT | namespace CAS revision |
namespace | TEXT NULL | serialized Namespace |
owner | TEXT NULL | current writer owner |
fence | BIGINT | monotonic fencing token |
expires | BIGINT | PGlite/provider-clock lease expiry |
mount_rs_blocks
Immutable bytes scoped by volume and block ID.
| Column | Type | Stored meaning |
|---|---|---|
volume_key | TEXT | volume scope |
id | TEXT | block identity |
bytes | BYTEA | raw immutable block bytes |
Compatibility boundary
Legacy snapshot schema
These tables belong to the older snapshot state-store API. They should not be mistaken for the active metadata/block composition.
mount_rs_state
Legacy PgliteFs snapshot table; not used by the split providers.
| Column | Type | Stored meaning |
|---|---|---|
id | TEXT | state key |
snapshot | BYTEA | serialized snapshot |
revision | BIGINT | snapshot revision |
Only expect this table when the legacy PgliteFs state-store API is selected.
SELECT table_name, column_name, data_type
FROM information_schema.columns
WHERE table_name LIKE 'mount_rs_%'
ORDER BY table_name, ordinal_position;Real socket-server, fencing, reconnect/restart, split-store, and Rust/Node/CLI matrix evidence, plus hosted cross-platform recovery checks; production persistence, backup, observability, and ownership remain open. The latest exact published-tree PGlite rerun passed provider lifecycle/reconnect/fencing/cancellation, SQLite VFS round-trip, fresh-provider reconnect, disk-server restart, split stores, N-API, chunked storage, userspace FUSE, Rust SDK 6/6, Node SDK 5/5, CLI 11/11, the upstream suite at 1,200 passed and 82 skipped, and all 40 PGlite-inclusive seeded oracle lanes. R2 factory/runtime rows remained explicit credential-gated skips, so no config-validation row is counted as live R2 evidence. The earlier focused matrix also passed 5 Rust SDK, 4 Node SDK, and 9 CLI cases; the local R2 adapter contract also recorded 10 passes and one explicit R2 skip. These are focused consumer checks, not live-provider or native-mount acceptance; hosted and release acceptance remain separate. The current provider initializes and validates durable version metadata on reconnect, including head, sequence, volume identity, and pin invariants; a newer stored schema or cross-volume version record fails closed. The current hosted W04 packet also passed the exact PGlite/restart check on Linux, Linux ARM, macOS-latest, and macOS Intel, plus the package and clean-consumer gates; current-tip policy run 35641832862 passed the positive bounded-TTL and fail-closed configuration fixtures. A local disk-backed rehearsal emittedPGLITE_BACKUP_RESTORE_ROLLBACK_PASS, but that is supporting evidence rather than production backup or rollback approval. Hosted qualification run 35635114595 atd2db74dd is the recorded source for the cross-platform packet. The provider remains a Preview/NO-GO deployment boundary until persistent production storage, restore RPO/RTO, observability, ownership, and release approval are recorded. A newer current-main run 35713659406 at sourcec87adf7b has terminal success on ARM, macOS-latest, and macOS Intel Node lanes, including exact fragmented-request rejection, PGlite integration/restart recovery, rollback, N-API, andprovidersFailed: 0 markers. The Ubuntu Node lane remains queued, so this is 3/4 current-tip Unix recovery evidence only; native, package, provider, W26, Rust, and production gates remain open.
Layout and chunking
The mount layer still owns fixed-size chunking and publishes block IDs in namespace JSON. PGlite's tables are provider storage, not a second filesystem namespace. On startup the versioning schema recordsmount-rs-versioning at schema version 1, checks that stored versions and pins belong to the metadatavolume_id, and keeps the current head plus next sequence inmount_rs_version_state. Use separatevolume_key values to isolate independent compositions.
Durability and consistency
Lease checks and publication use the PostgreSQL/PGlite provider clock and row locks. with_durable(true) is a caller assertion; the default is volatile because a successful SQL acknowledgement does not prove that the server data directory is persistent.
Across every split-store composition, new blocks are flushed before metadata references are published. A provider acknowledgement is not automatically a power-loss or distributed-locking guarantee.
Inspect the SQL endpoint by volume key
psql "$PGLITE_DATABASE_URL" <<'SQL'
SELECT volume_key, revision, length(namespace) AS namespace_bytes
FROM mount_rs_metadata;
SELECT volume_key, id, octet_length(bytes) AS block_bytes
FROM mount_rs_blocks
ORDER BY volume_key, id
LIMIT 20;
SELECT schema_name, schema_version
FROM mount_rs_schema_versions
ORDER BY schema_name;
SELECT volume_key, volume_id, head_id, next_sequence, next_read_fence
FROM mount_rs_version_state;
SELECT volume_key, id, sequence, parent_id, restored_from, forked_from,
kind, block_store_id, created_at_ms, durable
FROM mount_rs_versions
ORDER BY volume_key, sequence
LIMIT 20;
SELECT volume_key, view_id, version_id, owner, fence, expires
FROM mount_rs_version_pins
ORDER BY volume_key, view_id;
SQLCredentials, cleanup, and safe operations
Keep the connection string and any credentials in the environment or a secret manager. On teardown, await the provider/Nodeshutdown() or close() path, then delete only rows for the owned volume_key inside a controlled test transaction.
Current limits
The adapter does not make a host-safe-mount claim about the PGlite data directory. Production persistence, connection-slot lifecycle, backup/restore, observability, platform support, and crash durability remain separate from SQL round-trip success.