Tutorial

This walkthrough uses the commerce example: an online shop with customers, products and orders. Every command below can be run as written.

Setup

Download the files the walkthrough uses and work inside that directory:

curl -fsSL https://bluep.ca/tutorial.tar.gz | tar -xz
cd bluep-tutorial

It holds the commerce model, its next version commerce-v2, the same schema as PostgreSQL and SQLite DDL, a small Avro schema, and three versions of one model for the merge step.

help and --version

bluep --version
bluep 0.2.0
bluep 0.2.0
bluep help review
bluep review — create and check repository-local model reviews
bluep review — create and check repository-local model reviews

bluep help lists every top-level command, including review.

init, fmt and check

bluep init scratch --name scratch
created scratch/model.bluep
bluep fmt scratch
bluep check commerce
model is valid

import and export

DDL, DBML, and JSON are supported interchange inputs. Import PostgreSQL DDL, then export and import JSON.

bluep import ddl commerce.postgresql.sql --dialect postgresql --out imported
wrote imported/model.bluep
bluep export json commerce > commerce.json
bluep export json-schema commerce --root customer > customer.schema.json
lossy [model-configuration] $: naming and lint configuration is not represented
bluep import avro simple.avsc --out avro --name simple
imported 1 entities into avro

Use --nest identifying when identifying children should become nested records or arrays. The application interchange guide lists every mapping and round-trip guarantee.

For import db, install and configure the matching live database client first; this tutorial does not use credentials.

generate

generate ddl writes SQL, generate docs writes HTML, and generate diagram writes a deterministic SVG or vector PDF.

bluep generate ddl commerce --target pg > commerce.sql
sed -n '/CREATE TABLE public.customer/,/);/p' commerce.sql
CREATE TABLE public.customer (
  id bigint NOT NULL GENERATED ALWAYS AS IDENTITY,
  email varchar(320) NOT NULL,
  full_name varchar(200) NOT NULL,
  created_at timestamp with time zone NOT NULL DEFAULT now(),
  CONSTRAINT pk_customer PRIMARY KEY (id),
  CONSTRAINT uq_customer_email UNIQUE (email),
  CONSTRAINT ck_customer_email CHECK (email ~ '^[^@]+@[^@]+$')
);
bluep generate docs commerce --out html
wrote 18 files to html
bluep generate diagram commerce --area Sales --format svg --out sales.svg
wrote sales.svg

lint and report

Use bluep impact commerce entity:customer to inspect dependent objects.

bluep lint commerce
model.bluep:258:12: warning [domain-check] column 'email' lacks the check constraint of domain 'email': email ~ '^[^@]+@[^@]+$'
bluep report --list
classification.html   html  matrix of classification levels with the entities and attributes at each level
bluep report commerce --template entities.csv
name,description,attributes,stereotype,areas
address,A postal address of a customer.,7,,Sales;

diff and migrate

The direction is current→desired: commerce is current and commerce-v2 is desired.

bluep diff commerce-v2 --target pg --against-dir commerce --accept-renames
~ column public.customer.email: type varchar(320) -> varchar(500)
bluep migrate commerce-v2 --target pg --against-dir commerce --accept-renames > migration.sql
skipped 1 destructive change(s); use --allow-destructive to include them

pull

bluep pull commerce --target pg --from-dir commerce-v2 --plan pull.json
plan: 8 changes (2 destructive), 1 rename candidates
bluep pull commerce --target pg --apply pull.json
applied 6, skipped 2; changed files: model.bluep
bluep check commerce
model is valid

history and review

History and review work on git revisions, so the tutorial directory becomes a repository with two commits. Review actions include create, show, comment, resolve, approve, request-changes, close, and check.

git init -q
git add . && git commit -qm "commerce v1"
cp commerce-v2/model.bluep commerce/model.bluep
git commit -qam "commerce v2"
bluep history commerce --from HEAD~1 --to HEAD
logical: 5
bluep review create commerce --from HEAD~1 --to HEAD
created review review-<id>: 12 changes (<from>..<to>)
bluep review list commerce

merge and merge-file

Configure the Git merge driver with bluep merge-file %O %A %B; it merges one .bluep file at a time.

bluep merge merge/base merge/ours merge/theirs --out merged
CONFLICT entities.order.description: base "An order." | ours "Orders placed by customers." | theirs "A customer order."
bluep merge-file base.bluep ours.bluep theirs.bluep
CONFLICT entities.order.description: base "An order." | ours "Orders placed by customers." | theirs "A customer order."

The conflict command exits 1 and its CONFLICT prefix is expected.

serve

Install curl before trying this optional localhost-only HTTP-server step.

bluep serve commerce --host 127.0.0.1 --port 7878
curl http://127.0.0.1:7878/api/summary
{"entities":8}

Stop the server with an interrupt after the request.

drift and deploy

The model is now commerce-v2 and the DDL is still the original, so drift reports the difference. Drift supports text, JSON, and HTML formats. Deploy status is available with --status.

bluep drift commerce --target pg --ddl commerce.postgresql.sql --dialect postgresql --fail-on none
drift target pg (postgresql)
deployed revision: not requested
database drift: 8
undeployed model changes: 0

Install sqlite3 before this optional deploy database setup step.

sqlite3 commerce.db < commerce.sqlite.sql
bluep deploy commerce --target lite --database commerce.db --dry-run --applied-by you@example.com --rollback-out rollback.sql

Compare in the browser

In the browser editor, open Compare and choose a local model directory or DDL file. Review current-to-desired changes, accepting those for the migration and rejecting those that should be restored in the open model when applied.

For application contracts, run bluep export json-schema <dir> or see the application interchange guide.

Where to go next

Read the user guide, the format reference, and the examples.