Skip to content

Getting started

This page takes you from the first dump of a database to the first applied change. You need a PostgreSQL server and pistachio. See Installation.

Connect

Every command that reads a database takes a connection string. The default is postgres://postgres@localhost/postgres.

pista dump
pista dump -c 'postgres://user:pass@host:5432/mydb'

export PISTA_CONN_STR='postgres://user@host:5432/mydb'
export PISTA_PASSWORD='s3cret'
pista dump

Options can also come from a YAML file. See Configuration.

Dump the schema

dump writes the current schema as SQL. That file is the starting point. When you pass it back to plan, plan produces no changes.

pista dump > schema.sql

Every command targets the public schema unless -n selects another. See Working with multiple schemas.

--split writes one file per object into a directory instead. See pista dump.

Edit

Change the file so that it declares the schema you want. This example adds a new column:

CREATE TABLE public.users (
    id integer NOT NULL,
    name text NOT NULL,
    email text,
    CONSTRAINT users_pkey PRIMARY KEY (id)
);

Plan

plan prints the DDL that makes the database match the file. It runs nothing:

pista plan schema.sql

-- Connected to postgres://postgres@localhost:5432/postgres
-- Plan for schema public (1 table, 0 views, 0 enums, 0 domains, 0 composite types, 0 sequences)
ALTER TABLE public.users ADD COLUMN email text;

plan does not include a drop unless --allow-drop includes its type. Instead, it writes the drop as a -- skipped: comment. See Controlling drops.

Apply

apply computes the same plan and runs it:

pista apply schema.sql

-- Connected to postgres://postgres@localhost:5432/postgres
-- Apply to schema public (1 table, 0 views, 0 enums, 0 domains, 0 composite types, 0 sequences)
ALTER TABLE public.users ADD COLUMN email text;
-- Apply finished in 12ms

A second plan now prints -- No changes. From here on, edit the file, run plan, and run apply. Keep the file in version control next to the application.

Next