Add DBTransaction interface documentation for ORM support

Updated JWT documentation to reflect the new DBTransaction interface
that allows ORM transactions to be used directly with the JWT package.

Changes:
- Added explanation of DBTransaction interface
- Documented that *sql.Tx automatically implements the interface
- Added examples showing GORM transaction usage (tx.Statement.ConnPool)
- Added examples showing Bun transaction usage (bunDB.BeginTx)
- Updated validation and revocation sections with ORM examples
- Clarified that users can choose between ORM or standard transactions

Benefits:
- GORM users can use gormDB.Begin() and pass tx.Statement.ConnPool
- Bun users can use bunDB.BeginTx() and pass tx directly
- Standard library users continue using db.Begin() as before
- No need to extract/manage separate transactions for different libraries

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-11 18:10:52 +11:00
parent f7025211be
commit f9522e95b9

65
JWT.md

@@ -159,7 +159,9 @@ token, expiry, err := gen.NewRefresh(42, true)
## Token Validation ## Token Validation
Tokens must be validated within a transaction context: Tokens must be validated within a transaction context. The package accepts any transaction type that implements the `DBTransaction` interface (which `*sql.Tx` does automatically):
### Using Standard Library
```go ```go
// Begin transaction // Begin transaction
@@ -185,6 +187,22 @@ if err != nil {
tx.Commit() tx.Commit()
``` ```
### Using ORM Transactions
You can use ORM transactions directly since they implement the `DBTransaction` interface:
```go
// GORM transaction
tx := gormDB.Begin()
token, err := gen.ValidateAccess(tx.Statement.ConnPool, tokenString)
tx.Commit()
// Bun transaction
tx, _ := bunDB.BeginTx(context.Background(), nil)
token, err := gen.ValidateAccess(tx, tokenString)
tx.Commit()
```
### Token Properties ### Token Properties
After validation, you can access token claims: After validation, you can access token claims:
@@ -204,9 +222,12 @@ ttl := token.TTL // "session" or "exp"
## Token Revocation ## Token Revocation
The revocation methods accept any transaction implementing the `DBTransaction` interface.
### Revoking a Token ### Revoking a Token
```go ```go
// Using standard library
tx, _ := db.Begin() tx, _ := db.Begin()
defer tx.Rollback() defer tx.Rollback()
@@ -222,6 +243,12 @@ if err != nil {
return err return err
} }
tx.Commit()
// Or using GORM
tx := gormDB.Begin()
token, _ := gen.ValidateAccess(tx.Statement.ConnPool, tokenString)
token.Revoke(tx.Statement.ConnPool)
tx.Commit() tx.Commit()
``` ```
@@ -358,6 +385,8 @@ CREATE INDEX IF NOT EXISTS idx_jwtblacklist_sub ON jwtblacklist(sub);
### GORM ### GORM
GORM transactions can be used directly with the JWT package:
```go ```go
import ( import (
"gorm.io/gorm" "gorm.io/gorm"
@@ -383,19 +412,25 @@ gen, _ := jwt.CreateGenerator(jwt.GeneratorConfig{
TableConfig: jwt.DefaultTableConfig(), TableConfig: jwt.DefaultTableConfig(),
}) })
// Use with transactions // Option 1: Use GORM transactions directly
tx, _ := sqlDB.Begin() tx := gormDB.Begin()
defer tx.Rollback() token, _ := gen.ValidateAccess(tx.Statement.ConnPool, tokenString)
token, _ := gen.ValidateAccess(tx, tokenString)
tx.Commit() tx.Commit()
// Option 2: Use standard sql.DB transactions
sqlTx, _ := sqlDB.Begin()
defer sqlTx.Rollback()
token, _ := gen.ValidateAccess(sqlTx, tokenString)
sqlTx.Commit()
``` ```
### Bun ### Bun
Bun transactions can be used directly with the JWT package:
```go ```go
import ( import (
"context"
"database/sql" "database/sql"
"github.com/uptrace/bun" "github.com/uptrace/bun"
"github.com/uptrace/bun/dialect/pgdialect" "github.com/uptrace/bun/dialect/pgdialect"
@@ -423,13 +458,17 @@ gen, _ := jwt.CreateGenerator(jwt.GeneratorConfig{
TableConfig: jwt.DefaultTableConfig(), TableConfig: jwt.DefaultTableConfig(),
}) })
// Use with transactions // Option 1: Use Bun transactions directly (recommended)
tx, _ := sqlDB.Begin() ctx := context.Background()
defer tx.Rollback() tx, _ := bunDB.BeginTx(ctx, nil)
token, _ := gen.ValidateAccess(tx, tokenString) // Bun's tx implements DBTransaction
token, _ := gen.ValidateAccess(tx, tokenString)
tx.Commit() tx.Commit()
// Option 2: Use standard sql.DB transactions
sqlTx, _ := sqlDB.Begin()
defer sqlTx.Rollback()
token, _ := gen.ValidateAccess(sqlTx, tokenString)
sqlTx.Commit()
``` ```
## Complete Example ## Complete Example