migrate: Add example

migrate/README.md

@@ -1,35 +1,8 @@
-# GoCQLX Migrations
+# 🚀 GocqlX Migrations
 
-Package `migrate` provides simple and flexible CQL migrations. 
-Migrations can be read from a flat directory containing cql files.
-There is no imposed naming schema, migration name is file name and the migrations are processed in lexicographical order.
-Caller provides a `gocqlx.Session`, the session must use a desired keyspace as migrate would try to create migrations table.
+`migrate` reads migrations from a flat directory containing CQL files.
+There is no imposed naming schema. Migration name is file name.
+The order of migrations is the lexicographical order of file names in the directory. 
+You can inject execution of Go code before processing of a migration file, after processing of a migration file, or between statements in a migration file.
 
-## Features
-
-* Each CQL statement will run once
-* Go code migrations using callbacks
-
-## Example
-
-```go
-package main
-
-import (
-    "context"
-
-    "github.com/scylladb/gocqlx/v2/migrate"
-)
-
-const dir = "./cql" 
-
-func main() {
-    session := CreateSession()
-    defer session.Close()
-
-    ctx := context.Background()
-    if err := migrate.Migrate(ctx, session, dir); err != nil {
-        panic(err)
-    }
-}
-```
+For details see [example](example) migration.

migrate/doc.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a ALv2-style
 // license that can be found in the LICENSE file.
 
-// Package migrate provides simple and flexible CLQ migrations.
-// Migrations can be read from a flat directory containing cql files.
-// There is no imposed naming schema, migration name is file name and the migrations are processed in lexicographical order.
-// Caller provides a gocqlx.Session, the session must use a desired keyspace as migrate would try to create migrations table.
+// Package migrate reads migrations from a flat directory containing CQL files.
+// There is no imposed naming schema. Migration name is file name.
+// The order of migrations is the lexicographical order of file names in the directory.
+// You can inject execution of Go code before processing of a migration file, after processing of a migration file, or between statements in a migration file.
 package migrate

migrate/example/example_test.go

@@ -0,0 +1,60 @@
+// Copyright (C) 2017 ScyllaDB
+// Use of this source code is governed by a ALv2-style
+// license that can be found in the LICENSE file.
+
+// +build all integration
+
+package example
+
+import (
+	"context"
+	"testing"
+
+	"github.com/scylladb/gocqlx/v2"
+	"github.com/scylladb/gocqlx/v2/gocqlxtest"
+	"github.com/scylladb/gocqlx/v2/migrate"
+)
+
+// Running examples locally:
+// make run-scylla
+// make run-examples
+func TestExample(t *testing.T) {
+	const ks = "migrate_example"
+
+	cluster := gocqlxtest.CreateCluster()
+	cluster.Keyspace = ks
+
+	if err := gocqlxtest.CreateKeyspace(cluster, ks); err != nil {
+		t.Fatal("CreateKeyspace:", err)
+	}
+	session, err := gocqlx.WrapSession(cluster.CreateSession())
+	if err != nil {
+		t.Fatal("CreateSession:", err)
+	}
+	defer session.Close()
+
+	// Add callback prints
+	printEvent := func(ctx context.Context, session gocqlx.Session, ev migrate.CallbackEvent, name string) error {
+		t.Log(ev, name)
+		return nil
+	}
+
+	reg := migrate.CallbackRegister{}
+	reg.Add(migrate.BeforeMigration, "m1.cql", printEvent)
+	reg.Add(migrate.AfterMigration, "m1.cql", printEvent)
+	reg.Add(migrate.CallComment, "1", printEvent)
+	reg.Add(migrate.CallComment, "2", printEvent)
+	reg.Add(migrate.CallComment, "3", printEvent)
+
+	migrate.Callback = reg.Callback
+
+	// First run prints data
+	if err := migrate.Migrate(context.Background(), session, "migrations"); err != nil {
+		t.Fatal("Migrate:", err)
+	}
+
+	// Second run skips the processed files
+	if err := migrate.Migrate(context.Background(), session, "migrations"); err != nil {
+		t.Fatal("Migrate:", err)
+	}
+}

migrate/example/migrations/m1.cql

@@ -0,0 +1,15 @@
+-- Comment
+
+CREATE TABLE bar ( id int PRIMARY KEY);
+
+INSERT INTO bar (id) VALUES (1);
+
+-- CALL 1;
+
+INSERT INTO bar (id) VALUES (2);
+
+-- CALL 2;
+
+INSERT INTO bar (id) VALUES (3);
+
+-- CALL 3;