ForgeSchema.com

Introducing ForgeSchema

Thu, 15 Oct 2026 09:30:00 +0300

A schema change is easy to describe casually and surprisingly difficult to execute reliably. A renamed column can look like a deletion followed by an addition. A new requirement can conflict with existing rows. A migration prepared yesterday can be wrong for a database changed this morning. ForgeSchema is being built to make those differences explicit before a change is applied.

The engine inspects PostgreSQL, compares current structure with a desired YAML schema, generates an explained migration artifact, applies supported changes transactionally and verifies the target independently. Explicit renames preserve intent; unsupported changes block the entire plan.

Explore ForgeSchema in the browser

Thu, 15 Oct 2026 11:08:00 +0300

The browser demo lets you explore the completed prototype without setting up a database. Choose PostgreSQL 16.10 or 17.6, compare the recorded before/after schemas, open each of the six explained SQL operations and examine the preserved customer records.

The verification view switches between a matching target and the same schema with an unexpected external_note column. The report shows one structural difference. Verification leaves that change untouched; the walkthrough harness later removes its own injected column and verifies the target again.

Session 6: reproducible prototype and handoff

Thu, 15 Oct 2026 10:55:00 +0300

The final checkpoint delivers a reproducible customer-database walkthrough, complete command documentation and a supported/unsupported feature matrix. All six planned sessions are complete.

Fresh CI checkouts ran the compiled CLI on PostgreSQL 16.10 and 17.6. Both walkthroughs applied six operations, preserved both synthetic customer rows, independently verified the target, rejected stale replay and detected injected drift without repair. The harness cleaned up only its isolated schema; migration history remained until disposable database teardown.

Checking the Database Without Changing It

Thu, 15 Oct 2026 10:30:00 +0300

ForgeSchema now has an independent verify command. It compares a live PostgreSQL schema with a desired schema file or a reviewed plan’s target, then reports a match or structured drift. It reads catalog metadata in a read-only snapshot and makes no repairs.

That distinction matters after deployment. A database may have reached the expected structure and then changed again. Verification identifies missing or unexpected objects, type and nullability changes, and ordered key or index differences. It does not guess that two different column names represent a rename, and it does not turn a difference into executable SQL.

Executing the Reviewed Plan as One Transaction

Thu, 15 Oct 2026 10:10:00 +0300

ForgeSchema can now execute a reviewed migration artifact. The new apply command does not recalculate the desired migration against whatever it happens to find. It validates the saved plan, freezes a private copy and checks that the live database still matches the source the reviewer saw.

The order of that check is important. Another transaction may hold a table lock while changing its structure. ForgeSchema waits for the locks first, then reads fresh catalog metadata before deciding whether the reviewed starting conditions still hold. The tests include exactly that case: an outside transaction commits a change during the wait, and the stale plan is rejected.

A Migration Plan You Can Read Before It Runs

Thu, 15 Oct 2026 09:53:00 +0300

ForgeSchema now turns the difference between an observed schema and a desired schema into a reviewable plan. The artifact contains both complete descriptions, their fingerprints, explicit rename instructions and an ordered set of generated statements. It is deterministic: the same supported inputs produce the same plan.

Rename intent is the key distinction. Removing customer_name and adding full_name does not prove that the two columns hold the same information. A separate mapping tells the planner that this is a rename, allowing it to account for the existing key and index references that PostgreSQL updates along with the column. Without that instruction, the destructive interpretation is blocked.

Reading PostgreSQL Without Losing the Details

Thu, 15 Oct 2026 09:40:00 +0300

The second ForgeSchema checkpoint connects the schema contract to an existing PostgreSQL database. The inspect command reads catalog metadata in a read-only transaction and returns the same canonical representation used by the YAML validator. Repeated inspections of a supported unchanged schema produce identical output.

The difficult part is deciding what the engine can describe faithfully. A column default, a partial index or a generated expression cannot simply disappear from the snapshot. The inspector rejects unsupported structures explicitly, identifying the object that prevents a complete supported snapshot. It also separates primary key backing indexes from ordinary indexes and preserves the order of columns within composite keys.

The Schema Foundation Is in Place

Thu, 15 Oct 2026 09:30:00 +0300

The first ForgeSchema development session establishes the input contract for the engine. A versioned YAML file describes one PostgreSQL schema, its tables, columns, basic primary keys and ordinary indexes. The validator checks names, types and references, then produces canonical JSON with stable ordering.

This checkpoint includes a Go command line program, examples, automated validation tests and a populated PostgreSQL fixture for subsequent work. Schema fingerprints are available in the Go package; they identify canonical representations and are not a security signature.

About ForgeSchema

Mon, 01 Jan 0001 00:00:00 +0000

ForgeSchema is a schema evolution engine being developed in Go for PostgreSQL. It makes a proposed change understandable before execution and provides a way to check the result independently afterwards.

All six prototype checkpoints are complete. The CLI validates desired schemas, inspects PostgreSQL 16/17, generates explained plans, applies supported reviewed artifacts transactionally and verifies structural matches or drift without changing the database. The reproducible customer walkthrough and final handoff are available.

Build

Mon, 01 Jan 0001 00:00:00 +0000

ForgeSchema is an unreleased development prototype. Install Go 1.24 or later, clone the code repository and build the CLI:

go test ./...
go build -o bin/forgeschema ./cmd/forgeschema
./bin/forgeschema validate examples/customers.yaml

The included customer examples demonstrate planning offline. For a real migration, inspect the actual database first and use its snapshot as the source. Review the saved artifact and pause external DDL before apply. DATABASE_URL is supplied securely through the environment.

./bin/forgeschema inspect public > current.json
./bin/forgeschema plan current.json desired.yaml renames.yaml > reviewed-plan.json
./bin/forgeschema apply reviewed-plan.json
./bin/forgeschema verify --plan reviewed-plan.json

Apply changes the database and takes exclusive table locks. Verify is read-only and can also accept a desired schema directly. It prints match or drift JSON; a completed drift comparison exits 4. Read the execution guide and verification guide for role requirements, exit codes, timeout defaults and snapshot limits.

Contact

Mon, 01 Jan 0001 00:00:00 +0000

For questions about ForgeSchema, write to info@forgeschema.com.

Technical issues and reproducible problems can also be raised through the project repository. Please use synthetic examples when describing schema problems; database credentials and private data are not needed.

Engine

Mon, 01 Jan 0001 00:00:00 +0000

ForgeSchema uses one canonical representation for desired YAML, inspected catalogs, migration plans and independent verification. Supported structural changes can be reviewed as explicit operations before they are executed.

Apply validates the saved artifact, checks the live source after acquiring locks, executes supported operations, verifies the target and commits history atomically. The standalone verify command checks a schema file or a saved ready plan’s target in a separate read-only snapshot.

Verification reports deterministic differences for missing or unexpected objects, types, nullability and ordered key/index definitions. It does not infer renames, generate repairs or read application rows. The current version is a development prototype for PostgreSQL 16 and 17, with deliberately limited schema support.

Interactive Demo

Mon, 01 Jan 0001 00:00:00 +0000

Explore a real ForgeSchema migration below. Choose a recorded PostgreSQL version, compare schemas, open the SQL operations and switch between matching and drift reports. This browser demo replays verified CLI results; it does not connect to a database or execute SQL.

Open the full-width demo

The six-session prototype walkthrough passed on PostgreSQL 16.10 and 17.6. Both runs applied six operations, preserved the two original customer rows, rejected stale replay and detected an extra column without repairing it. The downloadable reports belong to those captured runs; generate fresh plans for another database.

Roadmap

Mon, 01 Jan 0001 00:00:00 +0000

The initial six-session prototype is complete: strict schema validation, PostgreSQL inspection, explained migration planning, transactional execution, independent verification and a reproducible customer-database walkthrough.

The full suite and fresh-checkout walkthrough passed on PostgreSQL 16.10 and 17.6. Tests cover preserved rows, stale plans, competing clients, lock-wait drift, cancellation, statement timeouts and rollback after SQL, target-check, metadata-bootstrap or history-recording failures. These results do not establish general crash recovery or production readiness.

The resume checkpoint records the evidence and handoff. Further work awaits owner direction. There is no automatic release, published binary or licensing change.

Schema Format

Mon, 01 Jan 0001 00:00:00 +0000

Desired schemas and inspected snapshots share a versioned representation of one managed PostgreSQL schema. Tables declare supported columns, primary keys and ordinary indexes. Type aliases and nonsemantic ordering normalize; ordered key and index columns remain significant.

Rename intent belongs in a separate explicit mapping file. Reviewed plans contain the canonical source and target descriptions, fingerprints, explained operations and quoted SQL. Their strict JSON loader rejects malformed and inconsistent artifacts.

Verification compares the complete supported managed schema. Extra tables, columns or indexes are drift, rather than being ignored as unrelated. A structure outside the inspector’s supported representation produces an error instead of a partial report. A match concerns structural metadata, not application data or migration history.

Workflow

Mon, 01 Jan 0001 00:00:00 +0000

Inspect captures the supported PostgreSQL catalog structure. Plan compares that snapshot with a desired schema and explicit rename mappings. Unsupported proposals are blocked with no partial operation list. A ready artifact can be saved and reviewed before apply.

Apply executes that saved supported artifact after validation and a source drift check performed after table locks are acquired. Target verification and migration history share the transaction with the application DDL. External DDL must be paused: relation locks cannot prevent every unrelated schema-level CREATE.