Skip to content

docs: add "Why pistachio?" section to README #235

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
winebarrel merged 1 commit into from
May 20, 2026
Merged

docs: add "Why pistachio?" section to README #235

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,25 @@ Declarative schema management tool for PostgreSQL. Define your desired schema in

See also: [Getting Started Guide](getting-started.md)

## Why pistachio?

Traditional migration tools make you hand-write and order an ever-growing
chain of `ALTER` scripts. With pistachio you keep a single source of truth —
your desired schema as plain SQL — and let the tool compute the DDL to get
there:

- **Declarative.** Edit your `CREATE TABLE` / `CREATE VIEW` definitions; no
migration files to author or sequence.
- **Just SQL.** Schema files are ordinary PostgreSQL DDL (parsed via
pg_query), and `pista dump` round-trips an existing database back into a
Comment thread
winebarrel marked this conversation as resolved.
schema file.
- **Safe by default.** Destructive changes (dropping tables, columns,
constraints, …) are suppressed unless you opt in with `--allow-drop`, and
surface as `-- skipped:` comments so nothing is dropped silently.
- **Production-aware.** `CONCURRENTLY` index builds, `--with-tx`, and
`--pre-sql` / `lock_timeout` controls let you apply changes online without
long-held locks.

> [!NOTE]
> **v1.7.0 breaking change:** the CLI binary was renamed from `pist` to `pista`, environment variables from `PIST_*` to `PISTA_*`, and SQL comment directives from `-- pist:` to `-- pista:`. Existing SQL files and shell / CI configurations must be updated before upgrading. See the [1.7.0 changelog entry](CHANGELOG.md#170---2026-05-12) for the full list of renamed names.

Expand Down