Migration Guide: v0.9.x → v0.10.0

⚠️ BREAKING CHANGES — Fresh Install Only

v0.10.0 introduces breaking changes that are incompatible with existing v0.9.x databases. There is no automatic migration path for existing data. You must:

1. Back up your existing database.
2. Perform a fresh install of v0.10.0.
3. Manually migrate data if required.

---

Breaking Changes

BC-1: UUID Primary Keys (ID Format)

Change: The default primary key is now UUID v7 (string), not integer.

What changed:

• New schemas default to id: UUID (auto-generated UUIDv7 string).
• All REST API responses return "id": "550e8400-e29b-41d4-a716-446655440000" (string).
• Go SDK/Framework receives id as a string, not int or uint64.

Customize if needed:

• Override with auto-increment-uint64 for integer IDs.
• Use custom-string-pk for custom string primary keys.
• See System Schema for details.

REST Example:

Before (v0.9.x):

{
  "id": 1,
  "name": "John"
}

After (v0.10.0):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "John"
}

BC-2: Error Response Model (HTTP 422)

Change: Validation errors now use HTTP 422 with structured error codes.

Before (v0.9.x):

{
  "code": "400",
  "message": "Invalid field type",
  "data": null
}

After (v0.10.0):

{
  "code": "422",
  "message": "schema validation failed",
  "data": {
    "schema": "post",
    "field_errors": [
      {
        "code": "field.type.invalid",
        "field": "status",
        "message": "field type 'invalid_type' is not recognized"
      }
    ]
  }
}

Errors now include dotted error codes (e.g., field.type.invalid, schema.label_field.not_found) for programmatic handling.

See Error Codes Reference for the complete list.

BC-3: Authentication Endpoint Changes

Change: Login and auth endpoints moved from /api/user/* to /api/auth/*.

Endpoints changed:

Old (v0.9.x)	New (v0.10.0)
POST /api/user/login	POST /api/auth/local/login
GET /api/user/me	GET /api/auth/me
—	POST /api/auth/logout
—	POST /api/auth/token/refresh
—	POST /api/auth/otp/request (passwordless)
—	POST /api/auth/otp/verify

Login Response - Refresh Token Support:

Refresh tokens are opt-in via AUTH_ENABLE_REFRESH_TOKEN env var. Default: disabled.

{
  "token": "<access_token>",
  "expires": "2024-06-24T20:21:10Z",
  "refresh_token": "<refresh_token>",
  "refresh_token_expires": "2024-07-01T20:21:10Z"
}

• Access token lifetime: 7 days (default) or 15 minutes (when refresh enabled).
• Refresh token lifetime: 7 days (default).
• refresh_token and refresh_token_expires fields omitted if refresh is disabled.

BC-4: Refresh Token Environment (New)

New environment variables:

AUTH_ENABLE_REFRESH_TOKEN=true
AUTH_REFRESH_TOKEN_LIFETIME=604800  # 7 days in seconds

Default behavior (both unset): Refresh tokens disabled.

BC-5: OTP Passwordless Authentication (New)

Feature: Email-based one-time-password (OTP) authentication for passwordless login.

Environment:

AUTH_OTP_ENABLED=true
AUTH_OTP_LENGTH=6
AUTH_OTP_EXPIRATION=300  # seconds
AUTH_OTP_MAX_ATTEMPTS=3

Flow:

1. User requests OTP: POST /api/auth/otp/request { "email": "user@example.com" }
2. Server sends email with OTP code.
3. User verifies: POST /api/auth/otp/verify { "email": "user@example.com", "code": "123456" }
4. Response includes token and optional refresh_token (same format as login).

Email Templates: Activation and recovery emails are now customizable via fs.EmailTemplates configuration. See Configuration for details.

---

Migration Checklist

• [ ] Back up existing v0.9.x database.
• [ ] Update client code to expect UUID strings instead of integers for id fields.
• [ ] Update login endpoint calls to /api/auth/local/login.
• [ ] Update token refresh logic to use /api/auth/token/refresh if using refresh tokens.
• [ ] Add error handling for HTTP 422 with dotted error codes.
• [ ] Test OTP flow if using passwordless auth.
• [ ] Review Error Codes Reference for application-specific error handling.

---

What's New

• UUID v7 Primary Keys: Distributed ID generation, better sortability.
• Refresh Tokens: Optional token refresh for long-lived sessions.
• OTP Passwordless Auth: Email-based authentication without passwords.
• Structured Error Codes: Machine-readable error identification.
• Email Template Customization: Branded activation and recovery emails.

---

Further Reading

• Error Codes Reference
• System Schema (Primary Keys)
• Authentication
• Configuration