Referentie voor CLI

merql wordt geleverd met een CLI om rechtstreeks vanaf de terminal snapshots te maken, verschillen te berekenen en samenvoegingen uit te voeren. Composer installeert deze als vendor/bin/merql; in een checkout van de merql-repository is deze bin/merql.

vendor/bin/merql werkt na installatie als dependency, omdat merql 0.4.1. Eerdere releases zochten de Composer-autoloader alleen in de eigen map vendor/ van het pakket en mislukten wanneer merql als dependency was geïnstalleerd.

Snel aan de slag

# 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

Voor een driewegssamenvoeging moeten ours en theirs zijn vastgelegd vanuit twee databases die uiteen zijn gegaan vanaf de basis. Richt MERQL_DB_DSN voor elke snapshot op de juiste database:

# 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

Achtereenvolgens alle drie de snapshots maken van dezelfde database werkt niet als samenvoeging: theirs zou de wijzigingen van ours al bevatten, waardoor elke rij die ours heeft ingevoegd als een insert_insert-conflict zou worden gemeld.

Omgevingsvariabelen

CLI leest verbindingsgegevens voor de database uit omgevingsvariabelen. U kunt verbinding maken met een PDO DSN-string of met afzonderlijke MySQL-parameters.

Verbinding op basis van een DSN

Gebruik MERQL_DB_DSN voor verbindingen op basis van PDO. Dit is de aanbevolen aanpak voor SQLite en voor niet-standaardconfiguraties. De DSN moet verwijzen naar een MySQL- of SQLite-database: de CLI kan geen driver voor andere database-engines registreren.

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

Gebruik een SQLite-database die is opgeslagen in een bestand. Elke opdracht van CLI wordt in een eigen proces uitgevoerd, dus sqlite::memory: opent altijd een nieuwe, lege database en een snapshot daarvan bevat geen tabellen.

Verkorte notatie voor MySQL

Als MERQL_DB_DSN niet is ingesteld, valt CLI terug op variabelen die specifiek zijn voor 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"

Opdrachten

merql snapshot <name>

Leg de huidige status vast van de database die door de omgevingsvariabelen wordt aangegeven en sla deze op als een snapshot met een naam. Dit is de enige opdracht die verbinding maakt met een database.

vendor/bin/merql snapshot baseline

Uitvoer:

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

Snapshots worden opgeslagen als JSON-bestanden in .merql/snapshots/ onder de werkmap (zie Snapshotopslag). De naam mag alleen alfanumerieke tekens, streepjes en underscores bevatten.

Typische werkwijze: maak een snapshot voordat u wijzigingen aanbrengt en daarna nog een. De twee snapshots vormen de basis voor een vergelijking of samenvoeging.

merql diff <base> <current>

Vergelijk twee snapshots met een naam en geef een samenvatting van de verschillen weer.

vendor/bin/merql diff baseline current

Uitvoer:

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

Beide snapshots moeten al bestaan (eerder vastgelegd met merql snapshot). Voor de vergelijking is geen databaseverbinding nodig, omdat deze met opgeslagen snapshotbestanden werkt.

merql merge <base> <ours> <theirs>

Voer een driewegssamenvoeging uit van drie snapshots met een naam.

vendor/bin/merql merge base ours theirs

Uitvoer:

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

Alle drie de snapshots moeten al bestaan. Voor de samenvoeging is geen databaseverbinding nodig, omdat deze met opgeslagen snapshotbestanden werkt. De samenvoeging schrijft nooit naar een database: de CLI heeft geen apply-opdracht. Gebruik PHP API om een samenvoegingsresultaat toe te passen.

De CLI voegt samen op kolomniveau. Hij voert geen samenvoeging op celniveau uit voor TEXT- of JSON-kolommen, dus twee verschillende bewerkingen aan dezelfde kolom zijn hier altijd een conflict (#7). Gebruik ThreeWayMerge met een CellMergeConfig in PHP voor samenvoeging op celniveau.

--dry-run

Voeg de vlag --dry-run toe om een voorbeeld te bekijken van de SQL-instructies die de samenvoeging zou genereren, zonder iets uit te voeren. De instructies beschrijven hoe de basisstatus wordt omgezet in het samengevoegde resultaat en bevatten daarom de wijzigingen van beide kanten.

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

Uitvoer:

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

Ontwikkelopdrachten

Een checkout van de merql-repository bevat meer scripts in bin/ voor de oracle-gestuurde testsuite. Deze maken geen deel uit van het Composer-pakket, dus na het installeren van afhankelijkheden is alleen vendor/bin/merql beschikbaar. Voer ze uit vanuit de hoofdmap van de repository nadat je composer install hebt uitgevoerd.

bin/test-regression accepteert ook --jobs, maar negeert de waarde momenteel en voert scenario's een voor een uit (#5). Bij een onbekende --category wordt No scenarios found weergegeven en eindigt het programma succesvol.

Zie Teststrategie voor de indeling van de scenario's.

Afsluitstatus

merql snapshot, diff en merge eindigen met status 1 als een argument ontbreekt, en snapshot ook als er geen verbinding is ingesteld. Bij een ontbrekende snapshot eindigt de opdracht met een niet-afgevangen SnapshotException en een niet-nulstatus. Bij een onbekende opdracht wordt Unknown command weergegeven, maar het programma eindigt momenteel met status 0 (#3).

Snapshotopslag

Snapshots worden opgeslagen in .merql/snapshots/ ten opzichte van de werkmap. Elke snapshot is één JSON-bestand met de naam <name>.json. Voer elke opdracht uit vanuit dezelfde map, zodat de opdrachten elkaars snapshots kunnen vinden.

De CLI heeft geen optie of omgevingsvariabele voor een andere locatie (#8). Om een andere locatie te gebruiken, ga je naar een andere werkmap voordat je de opdracht uitvoert. Stel in PHP de map in voordat je snapshots vastlegt of laadt:

use Merql\Snapshot\SnapshotStore;

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

Snapshotbestanden zijn overdraagbaar. Je kunt ze tussen machines kopiëren, aan versiebeheer toevoegen of delen om samen problemen op te sporen. Een snapshot die door de CLI is vastgelegd, kan in PHP worden geladen met SnapshotStore::load(), en omgekeerd, zolang beide dezelfde map gebruiken.