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