En/migration (#272)

Author: aryanmehrotra

Diff for: docs/advanced-guide/handling-data-migrations/page.md

@@ -0,0 +1,109 @@
+# Handling Data Migrations
+
+Gofr supports data migrations for MySQL and Redis which allows to alter the state of a database, be it adding a new column to existing table or modifying the data type of an existing column or adding constraints to an existing table, setting and removing keys etc.
+
+**How Migrations help?**
+
+Suppose you manually edit fragments of your database, and now it's your responsibility to inform other developers to execute them. Additionally, you need to keep track of which changes should be applied to production machines in the next deployment.
+
+GoFr maintains the table called **gofr_migration** which helps in such case. This table tracks which migrations have already been executed and ensures that only migrations that have never been run are executed. This way, you only need to ensure that your migrations are properly in place. ([Learn more](https://cloud.google.com/architecture/database-migration-concepts-principles-part-1))
+
+## Usage
+
+We will create an employee table using migrations.
+
+### Creating Migration Files
+
+It is recommended to maintain a migrations directory in your project root to enhance readability and maintainability.
+
+**Migration file names**
+
+It is recommended that each migration file should be numbered using the unix timestamp when the migration was created, This helps prevent numbering conflicts when working in a team environment.
+
+Create the following file in migrations directory.
+
+**Filename : 1708322067_create_employee_table.go**
+```go
+package migrations
+
+import "gofr.dev/pkg/gofr/migration"
+
+
+const createTable = `CREATE TABLE IF NOT EXISTS employee
+(
+    id             int         not null
+        primary key,
+    name           varchar(50) not null,
+    gender         varchar(6)  not null,
+    contact_number varchar(10) not null
+);`
+
+func createTableEmployee() migration.Migrate {
+	return migration.Migrate{
+		UP: func(d migration.Datasource) error {
+			_, err := d.DB.Exec(createTable)
+			if err != nil {
+				return err
+			}
+			return nil
+		},
+	}
+}
+```
+
+`migration.Datasource` have the datasources whose migrations are supported which are Redis and MySQL. 
+All the migrations run in transactions by default.
+
+For MySQL it is highly recommended to use `IF EXISTS` and `IF NOT EXIST` in DDL commands as MySQL implicitly commits these Commands.
+
+**Create a function which returns all the migrations in a map**
+
+**Filename : all.go**
+```go
+package migrations
+
+import "gofr.dev/pkg/gofr/migration"
+
+func All() map[int64]migration.Migrate {
+	return map[int64]migration.Migrate{
+		1708322067: createTableEmployee(),
+	}
+}
+```
+
+Migrations will run in ascending order of keys in this map.
+
+### Initialisation from main.go 
+```go
+package main
+
+import (
+	"errors"
+	"fmt"
+
+	"gofr.dev/examples/using-migrations/migrations"
+	"gofr.dev/pkg/gofr"
+)
+
+func main() {
+	// Create a new application
+	a := gofr.New()
+
+	// Add migrations to run
+	a.Migrate(migrations.All())
+
+	// Run the application
+	a.Run()
+}
+
+```
+
+When we run the app we will see the following logs for migrations which ran successfully.
+
+```bash
+INFO [16:55:46] Migration 1708322067 ran successfully
+```
+
+
+
+

Diff for: docs/navigation.js

@@ -15,7 +15,7 @@ export const navigation = [
             { title: 'Inter-service HTTP Calls', href: '/docs/advanced-guide/interservice-http-call' },
             { title: 'Publishing Custom Metrics', href: '/docs/advanced-guide/publishing-custom-metrics' },
             { title: 'Remote Log Level Change', href: '/docs/advanced-guide/remote-log-level-change' },
-            // { title: 'Handling Data Migrations', href: '/docs/advanced-guide/data-migrations' },
+            { title: 'Handling Data Migrations', href: '/docs/advanced-guide/handling-data-migrations' },
             // { title: 'Dealing with Remote Files', href: '/docs/advanced-guide/remote-files' },
             // { title: 'Dynamic Configurations', href: '/docs/advanced-guide/dynamic-configs' },
             // { title: 'Supporting OAuth', href: '/docs/advanced-guide/oauth' },

Diff for: examples/using-migrations/configs/.env

@@ -0,0 +1,14 @@
+APP_NAME=using-migrations
+HTTP_PORT=9000
+
+REDIS_HOST=localhost
+REDIS_PORT=2002
+
+DB_HOST=localhost
+DB_USER=root
+DB_PASSWORD=password
+DB_NAME=gofr
+DB_PORT=2001
+
+TRACER_HOST=localhost
+TRACER_PORT=2005

Diff for: examples/using-migrations/main.go

@@ -0,0 +1,77 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+
+	"gofr.dev/examples/using-migrations/migrations"
+	"gofr.dev/pkg/gofr"
+)
+
+const (
+	queryGetEmployee    = "SELECT id,name,gender,contact_number,dob from employee where name = ?"
+	queryInsertEmployee = "INSERT INTO employee (id, name, gender, contact_number,dob) values (?, ?, ?, ?, ?)"
+)
+
+func main() {
+	// Create a new application
+	a := gofr.New()
+
+	// Add migrations to run
+	a.Migrate(migrations.All())
+
+	// Add all the routes
+	a.GET("/employee", GetHandler)
+	a.POST("/employee", PostHandler)
+
+	// Run the application
+	a.Run()
+}
+
+type Employee struct {
+	ID     int    `json:"id"`
+	Name   string `json:"name"`
+	Gender string `json:"gender"`
+	Phone  int    `json:"contact_number"`
+	DOB    string `json:"dob"`
+}
+
+// GetHandler handles GET requests for retrieving employee information
+func GetHandler(c *gofr.Context) (interface{}, error) {
+	name := c.Param("name")
+	if name == "" {
+		return nil, errors.New("name can't be empty")
+	}
+
+	row := c.DB.QueryRowContext(c, queryGetEmployee, name)
+	if row.Err() != nil {
+		return nil, errors.New(fmt.Sprintf("DB Error : %v", row.Err()))
+	}
+
+	var emp Employee
+
+	err := row.Scan(&emp.ID, &emp.Name, &emp.Gender, &emp.Phone, &emp.DOB)
+	if err != nil {
+		return nil, errors.New(fmt.Sprintf("DB Error : %v", err))
+	}
+
+	return emp, nil
+}
+
+// PostHandler handles POST requests for creating new employees
+func PostHandler(c *gofr.Context) (interface{}, error) {
+	var emp Employee
+	if err := c.Bind(&emp); err != nil {
+		c.Logger.Errorf("error in binding: %v", err)
+		return nil, errors.New("invalid body")
+	}
+
+	// Execute the INSERT query
+	_, err := c.DB.ExecContext(c, queryInsertEmployee, emp.ID, emp.Name, emp.Gender, emp.Phone, emp.DOB)
+
+	if err != nil {
+		return Employee{}, errors.New(fmt.Sprintf("DB Error : %v", err))
+	}
+
+	return fmt.Sprintf("succesfully posted entity : %v", emp.Name), nil
+}

Diff for: examples/using-migrations/migrations/1708322067_create_employee_table.go

@@ -0,0 +1,39 @@
+package migrations
+
+import (
+	"gofr.dev/pkg/gofr/migration"
+)
+
+const createTable = `CREATE TABLE IF NOT EXISTS employee
+(
+    id             int         not null
+        primary key,
+    name           varchar(50) not null,
+    gender         varchar(6)  not null,
+    contact_number varchar(10) not null
+);`
+
+const employee_date = `INSERT INTO employee (id, name, gender, contact_number) VALUES (1, 'Umang', "M", "0987654321");`
+
+func createTableEmployee() migration.Migrate {
+	return migration.Migrate{
+		UP: func(d migration.Datasource) error {
+			_, err := d.DB.Exec(createTable)
+			if err != nil {
+				return err
+			}
+
+			_, err = d.DB.Exec(employee_date)
+			if err != nil {
+				return err
+			}
+
+			_, err = d.DB.Exec("alter table employee add dob varchar(11) null;")
+			if err != nil {
+				return err
+			}
+
+			return nil
+		},
+	}
+}

Diff for: examples/using-migrations/migrations/1708322089_redis_add_employee_name.go

@@ -0,0 +1,20 @@
+package migrations
+
+import (
+	"context"
+	"gofr.dev/pkg/gofr/migration"
+)
+
+func addEmployeeInRedis() migration.Migrate {
+	return migration.Migrate{
+		UP: func(d migration.Datasource) error {
+			err := d.Redis.Set(context.Background(), "Umang", "0987654321", 0).Err()
+			if err != nil {
+				return err
+			}
+
+			return nil
+
+		},
+	}
+}

Diff for: examples/using-migrations/migrations/all.go

@@ -0,0 +1,12 @@
+package migrations
+
+import (
+	"gofr.dev/pkg/gofr/migration"
+)
+
+func All() map[int64]migration.Migrate {
+	return map[int64]migration.Migrate{
+		1708322067: createTableEmployee(),
+		1708322089: addEmployeeInRedis(),
+	}
+}

Diff for: go.mod

@@ -6,6 +6,7 @@ require (
 	github.com/DATA-DOG/go-sqlmock v1.5.2
 	github.com/alicebob/miniredis/v2 v2.31.1
 	github.com/go-sql-driver/mysql v1.7.1
+	github.com/gogo/protobuf v1.3.2
 	github.com/gorilla/mux v1.8.1
 	github.com/grpc-ecosystem/go-grpc-middleware v1.4.0
 	github.com/joho/godotenv v1.5.1

Diff for: go.sum

@@ -45,6 +45,7 @@ github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre
 github.com/go-sql-driver/mysql v1.7.1 h1:lUIinVbN1DY0xBg0eMOzmmtGoHwWBbvnWubQUrtU8EI=
 github.com/go-sql-driver/mysql v1.7.1/go.mod h1:OXbVy3sEdcQ2Doequ6Z5BW6fXNQTmx+9S1MCJN5yJMI=
 github.com/go-stack/stack v1.8.0/go.mod h1:v0f6uXyyMGvRgIKkXu+yp6POWl0qKG85gN/melR3HDY=
+github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
 github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
 github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b/go.mod h1:SBH7ygxi8pfUlaOkMMuAQtPIUF8ecWP5IEl/CR7VP2Q=
 github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da/go.mod h1:cIg4eruTrX1D+g88fzRXU5OdNfaM+9IcxsU14FzY7Hc=

Diff for: pkg/gofr/gofr.go

@@ -21,6 +21,7 @@ import (
 	"gofr.dev/pkg/gofr/container"
 	"gofr.dev/pkg/gofr/logging"
 	"gofr.dev/pkg/gofr/metrics"
+	"gofr.dev/pkg/gofr/migration"
 	"gofr.dev/pkg/gofr/service"
 )
 
@@ -208,6 +209,10 @@ func (a *App) SubCommand(pattern string, handler Handler) {
 	a.cmd.addRoute(pattern, handler)
 }
 
+func (a *App) Migrate(migrationsMap map[int64]migration.Migrate) {
+	migration.Run(migrationsMap, a.container)
+}
+
 func (a *App) initTracer() {
 	tracerHost := a.Config.Get("TRACER_HOST")
 	tracerPort := a.Config.GetOrDefault("TRACER_PORT", "9411")

Diff for: pkg/gofr/migration/datasource.go

@@ -0,0 +1,8 @@
+package migration
+
+type Datasource struct {
+	Logger
+
+	DB    sqlDB
+	Redis redis
+}

Diff for: pkg/gofr/migration/logger.go

@@ -0,0 +1,8 @@
+package migration
+
+type Logger interface {
+	Info(args ...interface{})
+	Infof(format string, args ...interface{})
+	Error(args ...interface{})
+	Errorf(format string, args ...interface{})
+}