Neon Postgres Sync

Sync local files with Neon Postgres records. This extension allows you to upload and download configuration files (or any text content) to/from a PostgreSQL database, preserving comments and formatting by treating content as raw text.

Features

• One-Command Sync: A single Sync File command auto-picks direction by comparing local file mtime with the remote update_time. When the timestamps are too close to trust (within 5s) or either side is missing a timestamp, it pauses and asks you to pick the direction explicitly.
• Multi-Profile Sync: Pick Sync Multiple Profiles… from the same picker to open a batch page listing each selected profile's direction and added/removed line counts. Adjust direction, open a diff, confirm individually, or hit Confirm All to commit every pending row in a single atomic transaction. Alt+A toggles select-all in the multi-pick (respects the active search).
• Manual Direction Override: Click the ⇄ icon in the diff title bar (or press Alt+S) to flip the sync direction mid-review. Candidate-side edits (saved or unsaved) are protected with a confirmation before being discarded.
• Text-based Sync: Preserves comments, whitespace, and formatting in your files.
• Interactive Diff: Review changes (and edit the candidate side) before confirming with Alt+Enter.
• Smart Language Detection: Diff views respect file associations (e.g., JSONC files display without false syntax errors).
• Secure Storage: Your database connection string is stored securely using VS Code's Secret Storage.
• Profile Management: Manage multiple file-to-record mappings through a theme-aware settings panel with modal-based add/edit and a native file picker — or edit neon-sync.json directly via Neon Sync: Open Settings (JSON).
• Persistent Profile Order: Most recently used profile order is saved globally and survives Reload Window.
• Server-side Timestamping: Database timestamps (create_time, update_time) are generated by the database (CURRENT_TIMESTAMP).

Configuration

1. Database Setup

Ensure your PostgreSQL database has a table with the following schema (you can customize the table name in your profiles):

CREATE TABLE IF NOT EXISTS json_records (
    id TEXT PRIMARY KEY,
    data TEXT,
    create_time TIMESTAMP,
    update_time TIMESTAMP
);

Note: The data column must be of type TEXT to support raw content sync.

2. Connection String and Profiles

Run Neon Sync: Open Settings to open the configuration panel, then:

• Paste your PostgreSQL connection string into the Connection field. It auto-saves on blur into VS Code's Secret Storage.
• Click + Add under Profiles to create a profile. Required fields: name, local file path (use Browse… to pick), record ID, and table name (defaults to json_records).

Connection string format:

postgres://user:password@host:port/dbname

The extension uses HTTP transport (@neondatabase/serverless) only (no TCP mode).

If you trigger a sync without a connection string configured, the error toast will offer an Open Settings button that jumps straight to the Connection field.

3. Editing the JSON directly

Profiles are persisted to neon-sync.json under VS Code's global storage. Power users can open the raw file via Neon Sync: Open Settings (JSON).

Example neon-sync.json:

{
    "profiles": [
        {
            "name": "My Config",
            "filePath": "config/settings.json",
            "id": "app-settings",
            "tableName": "json_records"
        },
        {
            "name": "Env Variables",
            "filePath": ".env",
            "id": "env-vars",
            "tableName": "app_config"
        }
    ]
}

4. Filtering keys (JSON/JSONC only)

For JSON/JSONC profiles you can list keys that should be hidden from the diff and preserved on the target side on confirm. This is useful for machine-specific or transient keys (themes, machine IDs, locally chosen font sizes) that you don't want propagating across machines.

Add excludeKeys to a profile (via the settings panel's Add/Edit modal → Advanced, or by editing neon-sync.json directly):

{
    "profiles": [
        {
            "name": "VS Code Settings",
            "filePath": ".vscode/settings.json",
            "id": "vscode-settings",
            "tableName": "json_records",
            "excludeKeys": [
                "editor.fontSize",
                "workbench.colorTheme",
                "telemetry.machineId"
            ]
        }
    ]
}

Path syntax (v1):

• Dot-separated string. a.b.c addresses { "a": { "b": { "c": ... } } }.
• Multiple paths supported; multi-level paths supported.
• Wildcards (a.*.b), array indices, and keys containing literal dots are not supported in this release.

Behavior:

• Diff view: both sides are shown with the listed keys removed. Comments and formatting on remaining keys are preserved.
• Identical check: if the only differences are filtered keys, the sync is treated as "already in sync" and skipped.
• Confirm: the target side's current values for the filtered keys are spliced back in before writing. Locally edited values for filtered keys in the diff editor are also overwritten with the target's values (since these keys are "owned" by the target).
• Parse failure: if either side does not parse as JSONC (comments and trailing commas allowed), the sync is aborted with an error. The multi-profile panel keeps the row visible with an inline error.
• No filter: profiles without excludeKeys (or with an empty list) behave exactly as before — pure raw-text sync.

Usage

1. Run Neon Sync: Sync File and select a profile.

2. The extension compares local mtime against the remote update_time and opens a diff in the picked direction:

   • Local ← Remote (remote is newer, will overwrite local on confirm)
   • Remote ← Local (local is newer, will overwrite remote on confirm)

   If the timestamps are ambiguous (see below), a modal asks you to pick Download (Local ← Remote) or Upload (Remote ← Local) first; dismissing the modal aborts the sync.

3. Optionally edit the right-hand side of the diff to fine-tune the final content.

4. Confirm with Alt+Enter (or the ✓ button), press the ⇄ button / Alt+S to flip direction before confirming, or click the ✕ button to cancel.

Syncing multiple profiles

1. Run Neon Sync: Sync File and pick Sync Multiple Profiles… from the list (its position floats up as you use it).
2. Check the profiles you want to sync (Space toggles, Alt+A toggles select-all for whatever matches the current search).
3. The batch page fetches all selected records in a single HTTP transaction and lists every row that still needs syncing with its proposed direction and +added / -removed line counts. Identical profiles are skipped with a notification; missing-both profiles are called out separately.
4. Per row you can Swap the direction, open a Diff (same editor as single-profile sync), or Confirm just that row. Confirm All commits every upload in a single atomic transaction, then writes the local files.
5. If a local write fails after a successful remote commit, the affected row stays visible with a remote committed badge so a retry only re-runs the local write — it won't re-upload or bump update_time.

Auto-direction rules

When auto-pick is skipped (explicit prompt instead):

Auto-resolution only runs when both timestamps are available and differ by at least 5 seconds. Otherwise the extension pauses and shows a modal with two buttons (Download (Local ← Remote) / Upload (Remote ← Local)) — you pick, or dismiss to abort the sync. The diff opens in the direction you picked, and you can still swap once it's open.

Cases that trigger the explicit prompt:

• Close timestamps: local mtime and remote update_time differ by less than 5 seconds (including ties). Local mtime comes from the OS clock while update_time is the Neon server's CURRENT_TIMESTAMP, so small deltas are unreliable.
• Missing timestamps: the remote row has no update_time, the local file has no usable mtime, or both.

Origin

This extension was originally designed to synchronize Google Antigravity configurations.

Models used to build this project: Gemini 3 Pro did the initial scaffolding; ongoing maintenance is mostly Claude Opus / Sonnet, with GPT (Codex) handling review passes.