Read me first

If you have just been handed SchemaShift and you are not sure what it is or where to start, this page is for you. It assumes no knowledge of the tool and avoids technical shorthand. Everything here describes what the software actually does today.

---

1. Who this is for

SchemaShift is for the people responsible for changing the structure of a database without breaking anything. In most organisations that is a small group:

• The engineers who build the application and need to add a new field, table, or index.
• The people who look after the databases themselves and are accountable when something goes wrong in production.
• Whoever has to sign off that a risky change is safe before it happens.
• The people on call at 3am when a release goes badly.

You do not need to be a database specialist to use it. You do need to be someone who is allowed to change a database, or to approve someone else doing so.

---

2. What it does

Every application stores its information in a database, and the shape of that storage — which tables exist, which fields they hold — has to change as the product changes. That change is called a migration, and it is one of the few software operations that can destroy information permanently.

SchemaShift makes those changes safe. In plain terms it:

• Shows you exactly what will happen before anything is changed.
• Warns you loudly when a change would destroy data, and blocks it unless someone deliberately allows it.
• Notices when a live database has quietly stopped matching what your team intended.
• Lets you undo a change, and tells you in advance when undoing will not be possible.
• Keeps a tamper-evident record of who changed what, when, and who approved it.

There are two ways to use it: a command-line tool for engineers and automated pipelines, and a web interface for teams who need review and approval before changes reach important systems.

---

3. The domain: what a schema migration is

Think of a database as a very large, very strict filing system. The schema is the design of that filing system: what kinds of folders exist, what each one holds, and how they relate.

Changing the design of a filing system that is in constant use is delicate:

• Adding something new is usually safe. A new, empty folder harms nothing.
• Removing something is not. Deleting a field deletes everything recorded in it, for every record, permanently.
• Changing something can be either. Widening a field is harmless; narrowing it can silently truncate what does not fit.
• Order matters. Changes must be applied in the same sequence everywhere, or two copies of the same system drift apart.

Two ideas run through the whole product:

Versioned changes. Each change is a numbered step. The tool records which steps have been applied to which database, so it always knows where each system stands.

Declared state. Instead of writing each step by hand, you describe the shape you want, and SchemaShift works out the steps needed to get there. That comparison is also what lets it detect drift.

Drift is the word for a live database that no longer matches its intended design — usually because someone made an emergency change by hand and it was never written down. Drift is a leading cause of failed releases, because the next automated change assumes a starting point that is no longer true.

---

4. Where it fits

SchemaShift sits between your team and your databases. It does not replace them, and it does not store your data.

Databases it manages. PostgreSQL, MySQL, and SQLite.

Systems it works alongside. Your code repository, where change files live next to the application code. Your automated build pipeline, where SchemaShift acts as a gate that fails a build containing an unsafe change. Your secret store, which holds the database passwords.

An important boundary: SchemaShift never stores your database passwords. It stores a reference — a note saying "the password for this database is the one called PRODUCTION_DB" — and looks the real value up at the moment it connects. If someone obtained a complete copy of everything SchemaShift stores, it would contain no credentials.

Who runs it. Each organisation runs its own private copy. Your installation is yours alone; there is no shared service holding several companies' information.

---

5. First run

The very first thing to do is point it at a database that does not matter — a local or test copy — and ask it what it would change. Nothing is applied.

The preview version comes with sample data already loaded, so you can look around a populated system immediately without connecting anything real. See installation to get it running, then getting started for the first walkthrough.

Read the plan it produces. That single screen is the heart of the product: a numbered list of operations, in the order they will run, with anything destructive clearly marked. When you trust what that screen tells you, you are ready to use it for real.

Do not begin by connecting production.

---

6. Setting up

Roughly in this order:

1. Install it — as a command-line tool for individuals and pipelines, or as a server with a web interface for teams. See installation.
2. Prepare a real environment. When you are ready for a genuine stage or production system, first-run setup explains how to initialise it, including the safeguards that stop you wiping the wrong system.
3. Connect your databases. Register each one as a target — development, staging, production, and so on. Supply the name of the stored secret holding its password, never the password itself.
4. Decide which environments need approval. Production almost certainly should. Development almost certainly should not.
5. Assign roles (see below) so people can do their jobs and no more.
6. Add it to your build pipeline, so unsafe changes are caught automatically rather than by whoever happens to be looking. See integration.

---

7. Day to day

For most people the routine is short:

Making a change. Describe what you want, review the plan SchemaShift produces, and apply it to your own development database. If it looks wrong, nothing has happened yet.

Getting it approved. For a protected environment, submit the change instead of applying it. Someone with the reviewer role checks and approves it. If the change is edited after approval, the approval is automatically cancelled — so nobody can approve one thing and apply another.

Applying it. Someone with the admin role applies the approved change. The system records who did it and when.

When something goes wrong. Roll back the most recent change, or back to a named earlier point. If a change cannot be safely undone, SchemaShift will have told you so before it was applied, and will offer a safer path instead.

Checking for surprises. Run a drift check, or let the server do it on a schedule and tell you when a database has diverged.

---

8. Ongoing care

• Review drift reports regularly. Repeated drift usually means a process problem, not a tooling one.
• Review the audit trail periodically, and confirm the integrity check still reports it as intact.
• Back up your databases on your normal schedule. SchemaShift makes changes safer; it is not a backup, and it cannot recover data that a destructive change removed.
• Keep declared schemas in your repository, so the intended design is always reviewable alongside the code.
• Revisit who has which role as people join and leave.

---

Roles: who can do what

Roles are assigned per environment, so the same person can be trusted with development and restricted in production.

Role	What they can do
Viewer	Look at everything; change nothing.
Author	Create and submit changes for review.
Reviewer	Approve or reject submitted changes.
Admin	Apply changes, and manage targets, environments, and roles.

Submitting, approving, and applying are deliberately separate. One person acting alone should not be able to push an unreviewed change into production.

---

A short glossary

Term	Meaning
Schema	The structure of a database: its tables and fields.
Migration	One recorded change to that structure.
Target	A specific database SchemaShift manages.
Environment	A stage such as development, staging, or production.
Plan	The list of operations needed to reach the design you asked for.
Drift	A live database no longer matching its intended design.
Destructive change	One that removes or narrows something, and can lose data.
Rollback	Undoing an applied change.
Audit trail	The tamper-evident record of what was done, by whom, and when.
Secret reference	The name of a stored password, rather than the password.

---

The other documents here

Document	Read it when
Overview	You want a short summary of the product.
Getting started	You are ready for your first hands-on walkthrough.
Installation	You need to get it running.
First-run setup	You are preparing a real stage or production system.
Quickstart	You want the shortest path to a working change.
Reference	You need the details of a specific command or setting.
Integration	You are wiring it into a build pipeline.
Comparison	You are evaluating it against other tools.
Architecture	You want to know how it is built.
Security and compliance	You are reviewing it on behalf of a security team.
Capability matrix	You need to know precisely what does and does not exist yet.
Testing	You want to know how it is verified.

---

Sample data, and starting clean

The preview version ships with realistic sample data — three invented products, each with its own databases, months of change history, approvals and rejections, a failed change, and drift findings — so that every screen has something meaningful on it. None of it is real, and it is there purely so you can evaluate the tool without connecting anything.

When you move to a real system, use the initialisation described in first-run setup. It clears everything and loads only the minimum needed to start, with several deliberate confirmations first.

---

Common questions

Will it change my database without asking? No. Applying a change is always a separate, explicit action, and you can always see the plan first.

What if a change cannot be undone? It tells you before you apply it, and suggests a safer route. This is deliberate: a rollback that silently fails is worse than one that was never promised.

Does it need an internet connection? No. Everything essential works fully offline, which matters for isolated or regulated environments. The optional AI assistance is the only part that reaches outside, and when it is unavailable the rest carries on unaffected.

Does the AI apply changes on its own? No. Anything AI-assisted is a suggestion presented for review, always editable, never applied automatically.

Can it move my data between different database systems? No. It manages structure, not the migration of records from one system to another.

Something looks wrong. Is my data at risk? If you have not applied anything, no. Previews and drift checks only read.

---

Where to get help

This product is part of the worlds-biggest-software-project initiative. The community at wbsp.ai is the place to ask questions, make suggestions, or find people who can adapt it to your organisation's needs.

It is worth knowing that this application is core functionality: deliberately plain, with no branding or visual styling applied. It is built to be customised. If you have domain knowledge, you can shape it yourself; if not, the community can help.