CLI Reference

merql leveres med en CLI til at oprette øjebliksbilleder, beregne diff og udføre fletninger direkte fra terminalen. Composer installerer den som vendor/bin/merql; i et checkout af merql-arkivet er den bin/merql.

vendor/bin/merql fungerer ved installation som afhængighed, fordi merql 0.4.1. Tidligere versioner søgte kun efter Composer-autoloaderen i pakkens egen vendor/-mappe og fejlede, når merql var installeret som afhængighed.

Hurtig start

# Capture a baseline from your database.
export MERQL_DB_DSN="sqlite:/path/to/db.sqlite"
vendor/bin/merql snapshot base

# Make some changes, then capture again.
vendor/bin/merql snapshot current

# See what changed.
vendor/bin/merql diff base current

En trevejsfletning kræver, at ours og theirs hentes fra to databaser, der er divergeret fra base. Ret MERQL_DB_DSN mod den rette database for hvert øjebliksbillede:

# Base: live before the sandbox was copied from it.
MERQL_DB_DSN="sqlite:/data/live.sqlite" vendor/bin/merql snapshot base

# ... copy live.sqlite to sandbox.sqlite, then both databases change ...

MERQL_DB_DSN="sqlite:/data/sandbox.sqlite" vendor/bin/merql snapshot ours
MERQL_DB_DSN="sqlite:/data/live.sqlite" vendor/bin/merql snapshot theirs

# Three-way merge with dry-run preview.
vendor/bin/merql merge base ours theirs --dry-run

Det fungerer ikke som en fletning at tage alle tre øjebliksbilleder fra den samme database efter hinanden: theirs ville allerede indeholde ændringerne fra ours, så hver række, som ours indsatte, ville blive rapporteret som en insert_insert-konflikt.

Miljøvariabler

CLI henter oplysninger om databaseforbindelsen fra miljøvariabler. Du kan oprette forbindelse enten med en PDO-DSN-streng eller individuelle MySQL-parametre.

DSN-baseret forbindelse

Brug MERQL_DB_DSN til PDO-baserede forbindelser. Dette er den anbefalede tilgang for SQLite og for konfigurationer, der ikke er standard. DSN'en skal pege på en MySQL- eller SQLite-database: CLI kan ikke registrere en driver til andre databasemotorer.

# SQLite file.
export MERQL_DB_DSN="sqlite:/var/data/myapp.sqlite"

# MySQL via DSN.
export MERQL_DB_DSN="mysql:host=127.0.0.1;dbname=mydb;charset=utf8mb4"
export MERQL_DB_USER="root"
export MERQL_DB_PASS="secret"

Brug en filbaseret SQLite-database. Hver CLI-kommando kører i sin egen proces, så sqlite::memory: åbner altid en ny, tom database, og et øjebliksbillede af den indeholder ingen tabeller.

MySQL-genvej

Når MERQL_DB_DSN ikke er angivet, falder CLI tilbage på variabler, der er specifikke for MySQL.

export MERQL_DB_NAME="wordpress"
export MERQL_DB_HOST="127.0.0.1"
export MERQL_DB_PORT="3306"
export MERQL_DB_USER="root"
export MERQL_DB_PASS="password"

Kommandoer

merql snapshot <name>

Hent den aktuelle tilstand for databasen, der angives af miljøvariablerne, og gem den som et navngivet øjebliksbillede. Dette er den eneste kommando, der opretter forbindelse til en database.

vendor/bin/merql snapshot baseline

Output:

Snapshot 'baseline' saved
Tables: posts, comments, users, settings

Øjebliksbilleder gemmes som JSON-filer i .merql/snapshots/ under arbejdsbiblioteket (se Lagring af øjebliksbilleder). Navnet må kun indeholde alfanumeriske tegn, bindestreger og understregningstegn.

Typisk arbejdsgang: Opret et øjebliksbillede før ændringerne og derefter et nyt efter. De to øjebliksbilleder danner grundlag for en diff eller fletning.

merql diff <base> <current>

Sammenlign to navngivne øjebliksbilleder, og vis en oversigt over forskellene.

vendor/bin/merql diff baseline current

Output:

Changeset: baseline -> current
  Inserts: 3
  Updates: 7
  Deletes: 1

Begge øjebliksbilleder skal allerede findes (tidligere oprettet med merql snapshot). Diff kræver ikke en databaseforbindelse, da den arbejder på gemte øjebliksbilledfiler.

merql merge <base> <ours> <theirs>

Udfør en trevejsfletning af tre navngivne øjebliksbilleder.

vendor/bin/merql merge base ours theirs

Output:

Merge: base + ours + theirs
  Operations: 12
  Conflicts:  0
  Clean:      yes

Alle tre øjebliksbilleder skal allerede findes. Fletningen kræver ikke en databaseforbindelse, da den arbejder på gemte øjebliksbilledfiler, og den skriver aldrig til en database: CLI har ingen anvendelseskommando. Brug PHP API til at anvende et fletningsresultat.

CLI fletter på kolonneniveau. Den udfører ikke fletning på celleniveau for TEXT- eller JSON-kolonner, så to forskellige ændringer af samme kolonne altid er en konflikt her (#7). Brug ThreeWayMerge med en CellMergeConfig i PHP til fletning på celleniveau.

--dry-run

Tilføj flaget --dry-run for at få vist de SQL-sætninger, som fletningen ville generere, uden at udføre noget. Sætningerne beskriver, hvordan grundtilstanden ændres til det flettede resultat, så de omfatter ændringerne fra begge sider.

vendor/bin/merql merge base ours theirs --dry-run

Output:

Merge: base + ours + theirs
  Operations: 3
  Conflicts:  0
  Clean:      yes

Dry run SQL:
  INSERT INTO `posts` (`id`, `title`, `status`) VALUES ('10', 'New Post', 'draft');
  UPDATE `posts` SET `title` = 'Updated Title' WHERE `id` = '5';
  DELETE FROM `comments` WHERE `id` = '3';

Udviklingskommandoer

Et checkout af merql-arkivet indeholder flere scripts i bin/ til dets oracle-drevne testsuite. De er ikke en del af Composer-pakken, så en installation som afhængighed kun har vendor/bin/merql. Kør dem fra arkivets rodmappe efter composer install.

bin/test-regression accepterer også --jobs, men ignorerer i øjeblikket værdien og kører scenarierne efter hinanden (#5). En ukendt --category udskriver No scenarios found og afsluttes uden fejl.

Se Teststrategi for scenariernes struktur.

Afslutningsstatus

merql snapshot, diff og merge afsluttes med status 1, hvis et argument mangler, og snapshot gør det også, hvis der ikke er konfigureret nogen forbindelse. Hvis et øjebliksbillede mangler, afsluttes kommandoen med en ufanget SnapshotException og en status, der ikke er nul. En ukendt kommando udskriver Unknown command, men afsluttes i øjeblikket med status 0 (#3).

Lagring af øjebliksbilleder

Øjebliksbilleder gemmes i .merql/snapshots/ i forhold til arbejdsbiblioteket. Hvert øjebliksbillede er en enkelt JSON-fil med navnet <name>.json. Kør alle kommandoer fra samme mappe, så de kan finde hinandens øjebliksbilleder.

CLI har ingen indstilling eller miljøvariabel til en anden placering (#8). Hvis du vil bruge en anden placering, skal du skifte til et andet arbejdsbibliotek, før du kører den. I PHP skal du angive biblioteket, før du opretter eller indlæser øjebliksbilleder:

use Merql\Snapshot\SnapshotStore;

SnapshotStore::setDirectory('/var/data/merql-snapshots');

Øjebliksbilledfiler er flytbare. Du kan kopiere dem mellem maskiner, indsende dem til versionsstyring eller dele dem til fælles fejlfinding. Et øjebliksbillede oprettet af CLI kan indlæses i PHP med SnapshotStore::load() og omvendt, så længe begge bruger samme mappe.