Referenca CLI

merql vključuje CLI za zajem posnetkov, izračun razlik in izvajanje združitev neposredno iz terminala. Composer ga namesti kot vendor/bin/merql; v klonu repozitorija merql je bin/merql.

vendor/bin/merql deluje tudi pri namestitvi odvisnosti, saj merql 0.4.1. Starejše izdaje so samodejni nalagalnik Composer iskale samo v lastni mapi paketa vendor/ in odpovedale, ko je bil merql nameščen kot odvisnost.

Hiter začetek

# 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

Za tristransko združitev morata biti na voljo posnetka »naše« in »njihovo«, zajeta iz dveh podatkovnih zbirk, ki sta se razšli od osnove. Za vsak posnetek usmerite MERQL_DB_DSN na ustrezno podatkovno zbirko:

# 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

Če vse tri posnetke zaporedoma zajamete iz iste podatkovne zbirke, združitev ne bo delovala: »njihovo« bo že vsebovalo spremembe »našega«, zato bo vsaka vrstica, ki jo je vstavil »naš«, prijavljena kot konflikt insert_insert.

Spremenljivke okolja

CLI prebere podrobnosti povezave s podatkovno zbirko iz spremenljivk okolja. Povežete se lahko z nizom DSN za PDO ali s posameznimi parametri MySQL.

Povezava prek DSN

Za povezave PDO uporabite MERQL_DB_DSN. To je priporočeni pristop za SQLite in nestandardne konfiguracije. DSN mora kazati na podatkovno zbirko MySQL ali SQLite, saj CLI ne more registrirati gonilnika za druge pogone.

# 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"

Uporabite podatkovno zbirko SQLite, shranjeno v datoteki. Vsak ukaz CLI se izvede v svojem procesu, zato sqlite::memory: vedno odpre novo, prazno podatkovno zbirko, njen posnetek pa ne vsebuje tabel.

Okrajšava MySQL

Če MERQL_DB_DSN ni nastavljena, CLI uporabi nadomestne spremenljivke, specifične za 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"

Ukazi

merql snapshot <name>

Zajame trenutno stanje podatkovne zbirke, določene s spremenljivkami okolja, in ga shrani kot poimenovan posnetek. To je edini ukaz, ki se poveže s podatkovno zbirko.

vendor/bin/merql snapshot baseline

Izhod:

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

Posnetki se privzeto shranijo kot datoteke JSON v .merql/snapshots/ pod delovnim imenikom (glejte Shranjevanje posnetkov). Ime lahko vsebuje samo črke, številke, vezaje in podčrtaje.

Običajen potek dela: zajemite posnetek pred spremembami, nato pa še enega po njih. Ta posnetka sta osnova za izračun razlike ali združitev.

merql diff <base> <current>

Primerja dva poimenovana posnetka in prikaže povzetek razlik.

vendor/bin/merql diff baseline current

Izhod:

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

Oba posnetka morata že obstajati (predhodno morata biti zajeta z ukazom merql snapshot). Za izračun razlike povezava s podatkovno zbirko ni potrebna, saj se uporabijo shranjene datoteke posnetkov.

merql merge <base> <ours> <theirs>

Izvede tristransko združitev treh poimenovanih posnetkov.

vendor/bin/merql merge base ours theirs

Izhod:

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

Vsi trije posnetki morajo že obstajati. Za združitev povezava s podatkovno zbirko ni potrebna, saj se uporabijo shranjene datoteke posnetkov; ukaz CLI ne vsebuje ukaza za uporabo. Za uporabo rezultata združitve uporabite PHP API.

CLI združuje na ravni stolpcev. Ne izvaja združevanja na ravni celic za stolpce TEXT ali JSON, zato sta različni spremembi istega stolpca vedno konflikt (#7). Za združevanje na ravni celic uporabite ThreeWayMerge z CellMergeConfig v PHP.

--dry-run

Dodajte zastavico --dry-run za predogled stavkov SQL, ki bi jih ustvarila združitev, ne da bi jih izvedli. Stavki opisujejo pretvorbo osnovnega stanja v združeni rezultat, zato vključujejo spremembe obeh strani.

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

Izhod:

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';

Razvojni ukazi

Klon repozitorija merql vsebuje v bin/ dodatne skripte za testno zbirko, vodeno z referenčnimi rezultati. Ti niso del paketa Composer, zato so pri namestitvi odvisnosti na voljo samo vendor/bin/merql. Zaženite jih iz korenske mape repozitorija po ukazu composer install.

bin/test-regression sprejema tudi --jobs, vendar trenutno prezre vrednost in scenarije zažene enega za drugim (#5). Neznan --category izpiše No scenarios found in se uspešno zaključi.

Za razporeditev scenarijev glejte Strategija testiranja.

Izhodno stanje

Ukazi merql snapshot, diff in merge se končajo s statusom 1, če manjka argument; enako velja za snapshot, kadar povezava ni konfigurirana. Če posnetek manjka, se ukaz konča z neujeto izjemo SnapshotException in statusom, ki ni nič. Neznan ukaz izpiše Unknown command, trenutno pa se konča s statusom 0 (#3).

Shranjevanje posnetkov

Posnetki so shranjeni v .merql/snapshots/ glede na delovni imenik. Vsak posnetek je ena sama datoteka JSON z imenom <name>.json. Vse ukaze zaženite iz istega imenika, da bodo lahko našli posnetke drug drugega.

CLI nima možnosti ali spremenljivke okolja za drugo lokacijo (#8). Če želite uporabiti drugo, pred zagonom spremenite delovni imenik. V PHP nastavite imenik pred zajemom ali nalaganjem posnetkov:

use Merql\Snapshot\SnapshotStore;

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

Datoteke posnetkov so prenosljive. Lahko jih kopirate med računalniki, vključite v sistem za nadzor različic ali delite za skupinsko odpravljanje napak. Posnetek, zajet z CLI, lahko naložite v PHP z ukazom SnapshotStore::load() in tudi obratno, če oba uporabljata isti imenik.