Add migration runner and compatibility docs

Author: darwvin-dev

CHANGELOG.md

@@ -16,6 +16,8 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Bulk delete API at `POST /admin/api/{resource}/bulk-delete` with de-duplicated ids and audit logging.
 - `pkg/adapters/sqlstore` for `database/sql` integrations, including MySQL and SQLite-style drivers.
 - `pkg/adapters/gormstore`, `pkg/adapters/mongostore`, and `pkg/adapters/redisstore`.
+- `pkg/migrate` SQL migration runner with ordered files and checksum tracking.
+- Compatibility policy and examples for existing chi, Gin/Echo, and GORM apps.
 - `docs/cli-init.md` for the supported init flags and generated project layout.
 - `docs/drop-in-adapters.md` for mounting GoMyAdmin on existing Go backends.
 - `docs/migrations.md` for versioned schema changes and release note expectations.

README.md

@@ -221,6 +221,7 @@ pkg/
   cache/                        tiny cache adapter contract + in-memory implementation
   filters/                      search / sort / filter query parsing
   logger/                       structured JSON logger (slog)
+  migrate/                      SQL migration runner with checksum tracking
   openapi/                      OpenAPI 3.1 spec generation
   pagination/                   page + per_page parsing
   postgres/                     pgx connection pool + safe SQL query builder
@@ -630,6 +631,7 @@ The demo backend includes users, customers, invoices, invoice items, payments, t
 - [Authentication and sessions](docs/auth.md)
 - [Stable CLI init flow](docs/cli-init.md)
 - [Drop-in adapters for existing Go backends](docs/drop-in-adapters.md)
+- [Compatibility policy](docs/compatibility.md)
 - [Versioned migrations](docs/migrations.md)
 - [PostgreSQL CRM schema example](examples/postgres-crm/README.md)
 
@@ -687,6 +689,7 @@ npm run build
 - [x] Generic `pkg/cache` interface for Redis/Memcached/application-cache adapters
 - [x] `database/sql` adapter for MySQL and SQLite-style drivers
 - [x] GORM, MongoDB, and Redis session adapters
+- [x] Production-oriented SQL migration runner with checksum tracking
 - [ ] Relation field rendering in the frontend
 - [ ] Playwright e2e tests for the CRM demo
 

docs/compatibility.md

@@ -0,0 +1,34 @@
+# Compatibility Policy
+
+GoMyAdmin follows semantic versioning.
+
+## Before v1.0.0
+
+The project is still stabilizing. Minor releases may change public APIs when the change improves the long-term adapter model, security posture, or generated app structure.
+
+Even before v1, GoMyAdmin tries to keep these stable:
+
+- `pkg/admin` resource builder concepts
+- `pkg/server.Config`
+- `server.AdminStore`
+- `auth.SessionStore`
+- `storage.Storage`
+- generated API route shapes under `/admin/api`
+
+## v1.0.0 and Later
+
+After v1.0.0:
+
+- breaking public API changes require a major version
+- adapters should remain source-compatible across minor releases
+- generated apps may receive new files, but existing generated code should keep compiling
+- database migrations are append-only
+
+## Supported Runtime Targets
+
+- Go: 1.23+
+- HTTP: any stack that can mount `http.Handler`
+- Built-in database adapter: PostgreSQL via pgx
+- Optional adapters: database/sql, MySQL-style SQL, SQLite-style SQL, GORM, MongoDB
+- Sessions: PostgreSQL, in-memory, cache-backed, Redis-backed
+- Storage: local filesystem, in-memory, S3-compatible

examples/existing-chi/README.md

@@ -0,0 +1,43 @@
+# Existing chi App
+
+```go
+package main
+
+import (
+	"context"
+	"log"
+	"net/http"
+	"os"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/darwvin-dev/gomyadmin/pkg/admin"
+	"github.com/darwvin-dev/gomyadmin/pkg/server"
+)
+
+type User struct{}
+
+func main() {
+	app := admin.New("Acme Admin")
+	app.Resource(User{}).
+		TableName("users").
+		Field("ID").String().Primary().Readonly().
+		Field("Email").Email().Searchable().Sortable().
+		Field("Status").Enum("active", "blocked").Filterable()
+
+	adminServer, err := server.New(context.Background(), server.Config{
+		DatabaseURL: os.Getenv("DATABASE_URL"),
+		App:         app,
+		Authenticate: func(ctx context.Context, email, password string) (admin.Actor, bool, error) {
+			return admin.Actor{ID: "admin", Email: email, Roles: []string{"super_admin"}, Permissions: []string{"*"}}, true, nil
+		},
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer adminServer.Close()
+
+	r := chi.NewRouter()
+	r.Mount("/admin", http.StripPrefix("/admin", adminServer.Handler()))
+	log.Fatal(http.ListenAndServe(":8080", r))
+}
+```

examples/existing-gin-echo/README.md

@@ -0,0 +1,26 @@
+# Existing Gin or Echo App
+
+GoMyAdmin exposes a standard `http.Handler`, so frameworks can mount it through their HTTP adapter.
+
+## Gin
+
+```go
+adminHandler := adminServer.Handler()
+
+router.Any("/admin/*path", func(c *gin.Context) {
+	adminHandler.ServeHTTP(c.Writer, c.Request)
+})
+```
+
+## Echo
+
+```go
+adminHandler := adminServer.Handler()
+
+e.Any("/admin/*", func(c echo.Context) error {
+	adminHandler.ServeHTTP(c.Response(), c.Request())
+	return nil
+})
+```
+
+Use the same `server.Config` options shown in the chi example: pass either `DatabaseURL`, `Pool`, or a custom `Store`.

examples/gorm-store/README.md

@@ -0,0 +1,28 @@
+# GORM Store
+
+```go
+gormDB, err := gorm.Open(mysql.Open(os.Getenv("DATABASE_URL")), &gorm.Config{})
+if err != nil {
+	return err
+}
+
+app := admin.New("Acme Admin")
+app.Resource(User{}).
+	TableName("users").
+	Field("ID").String().Primary().Readonly().
+	Field("Email").Email().Searchable().Sortable()
+
+store, err := gormstore.MySQL(gormDB, app)
+if err != nil {
+	return err
+}
+
+adminServer, err := server.New(ctx, server.Config{
+	App:          app,
+	Store:        store,
+	SessionStore: redisstore.New(redisClient),
+	Authenticate: authenticateAdmin,
+})
+```
+
+The GORM adapter reuses GORM's underlying `*sql.DB`, so connection pooling and driver configuration stay owned by your app.

pkg/adapters/gormstore/doc.go

@@ -0,0 +1,2 @@
+// Package gormstore adapts GORM-managed database connections to GoMyAdmin.
+package gormstore

pkg/adapters/mongostore/doc.go

@@ -0,0 +1,2 @@
+// Package mongostore adapts MongoDB collections to GoMyAdmin resources.
+package mongostore

pkg/adapters/redisstore/doc.go

@@ -0,0 +1,2 @@
+// Package redisstore provides Redis-backed auth.SessionStore construction.
+package redisstore

pkg/adapters/sqlstore/doc.go

@@ -0,0 +1,5 @@
+// Package sqlstore adapts database/sql connections to server.AdminStore.
+//
+// Use MySQL or SQLite helpers when your app already imports and configures the
+// relevant database/sql driver.
+package sqlstore