Patch Format

A patch is a plain SQL file with a required header. Patchforge does not infer intent or inspect SQL semantics.

Required Header

-- PATCH_ID: 20260914_103512_add_users
-- PATCH_TYPE: SCHEMA

PATCH_ID must be unique and immutable once applied.

PATCH_ID

PATCH_ID uniquely identifies a patch. It is used for ordering, idempotency, and auditing.

Patchforge strongly recommends timestamp-based identifiers. 

YYYYMMDD_HHMMSSmmm_description

This prevents collisions across teams, branches, and repositories.

PATCH_TYPE

PATCH_TYPE defines how Patchforge treats the patch. 

SCHEMA
DATA

SCHEMA patches may snapshot tables before applying.

DATA patches do not snapshot automatically.

Schema Patch Example

-- PATCH_ID: 20260914_103512_add_users
-- PATCH_TYPE: SCHEMA

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    email TEXT NOT NULL
);

Data Patch Example

-- PATCH_ID: 20260914_104102_seed_admin
-- PATCH_TYPE: DATA

INSERT INTO users (email)
VALUES ('admin@example.com');

Rollback Metadata (Beta)

Rollback support exists but is currently considered beta.

Rollback SQL may be defined using a commented block. 

-- PATCH_ID: 20260914_105000_remove_admin
-- PATCH_TYPE: DATA
-- ROLLBACK:
-- DELETE FROM users WHERE email = 'admin@example.com';

DELETE FROM users WHERE email = 'admin@example.com';

Rollback behavior and guarantees may change in future releases.

Important Rules