database-migration

atilladeniz's avatarfrom atilladeniz

Manage database migrations and Better Auth schema. Use when adding tables, modifying schema, running migrations, or resetting the database.

⭐1stars🔀0forks📁View on GitHub🕐Updated Dec 9, 2025
[SQL and Databases]

When & Why to Use This Skill

This Claude skill automates PostgreSQL database management, GORM entity registration, and Better Auth schema migrations. It streamlines the development lifecycle by handling schema modifications, database resets, and synchronization between backend models and the database, ensuring a consistent and error-free environment for developers.

Use Cases

  • Schema Evolution: Automatically registering new GORM entities in the backend registry and managing auto-migrations to keep the database in sync with Go code.
  • Authentication Setup: Managing Better Auth table migrations (user, session, account) and generating SQL migration files for Next.js and Bun-based projects.
  • Environment Management: Executing database lifecycle commands such as starting, stopping, and resetting PostgreSQL instances using Docker and Makefile integration.
  • Database Troubleshooting: Performing direct database inspections, listing tables, and running SQL queries to verify data integrity and resolve connection issues.
namedatabase-migration
descriptionManage database migrations and Better Auth schema. Use when adding tables, modifying schema, running migrations, or resetting the database.
allowed-toolsRead, Bash, Grep

Database Migration

Manage PostgreSQL database, Better Auth schema, and GORM AutoMigrate.

GORM AutoMigrate (Backend)

Nach goca feature muss die neue Entity in backend/internal/domain/registry.go registriert werden:

// internal/domain/registry.go
func AllEntities() []interface{} {
    return []interface{}{
        &UserStats{},
        &NewEntity{},  // Neue Entity hier hinzufuegen
    }
}

Das ist die EINZIGE Stelle - main.go bleibt unveraendert! GORM erstellt die Tabelle automatisch beim Backend-Start.

Database Commands

Start Database

make db-up

Stop Database

make db-down

Reset Database (delete all data)

make db-reset

Better Auth Tables

Better Auth uses these tables (auto-created via migration):

  • user - User accounts
  • session - Active sessions
  • account - OAuth/credential accounts
  • verification - Email verification tokens

Run Better Auth Migration

make db-migrate

Or manually:

cd frontend && bunx dotenv-cli -e .env.local -- bunx @better-auth/cli@latest migrate --config src/shared/lib/auth-server/auth.ts --yes

Generate Migration SQL (without applying)

cd frontend && bunx dotenv-cli -e .env.local -- bunx @better-auth/cli@latest generate --config src/shared/lib/auth-server/auth.ts

Direct Database Access

Connect to PostgreSQL

docker exec nextgopg-db-1 psql -U postgres -d nextgopg

List Tables

docker exec nextgopg-db-1 psql -U postgres -d nextgopg -c "\dt"

Describe Table

docker exec nextgopg-db-1 psql -U postgres -d nextgopg -c "\d user"

Run SQL Query

docker exec nextgopg-db-1 psql -U postgres -d nextgopg -c "SELECT * FROM \"user\""

Database Connection

Connection String

postgres://postgres:postgres@localhost:5432/nextgopg

Environment Variable

Set in frontend/.env.local:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/nextgopg

Troubleshooting

Table doesn't exist

Run Better Auth migration:

cd frontend && DATABASE_URL="postgres://postgres:postgres@localhost:5432/nextgopg" bunx @better-auth/cli migrate -y

Connection refused

Start the database:

make db-up

Reset everything

make db-reset
make db-migrate