Handling SurrealDB Token Expiration & Reconnection (Hono Example)

[agentic-com]

If you define a duration for your root authentication, the token you receive after connecting with db.connect(…) will expire after that time. If not actualised, all your requests will be Unauthorised.

I was experiencing a root token actualisation issue because the actual adapter doesn’t consider it. Consequently, I created my own token renewal logic and I’m sharing it here in case it helps someone else in the future or inspires @oskar-gmerek for future feature releases. It’s not perfect but it provides a basic understanding of how such a system works.

import type { Context } from 'hono'
import { betterAuth } from 'better-auth'
import { surrealdbAdapter } from 'surreal-better-auth'
import Surreal from 'surrealdb'
import { getBetterAuthOptions } from './options'

// Singleton instances
let authInstance: ReturnType<typeof betterAuth> | null = null
let dbInstance: Surreal | null = null
let isConnecting = false
let connectionPromise: Promise<Surreal> | null = null

/**
 * SurrealDB connection configuration
 */
interface SurrealDBConfig {
  url: string
  namespace: string
  database: string
  username: string
  password: string
}

/**
 * Extract SurrealDB configuration from context
 */
function getSurrealDBConfig(c: Context): SurrealDBConfig {
  const env = c.env
  return {
    url: env.SURREALDB_URL,
    namespace: env.SURREALDB_NS,
    database: env.SURREALDB_DB,
    username: env.SURREALDB_USERNAME,
    password: env.SURREALDB_PASSWORD,
  }
}

/**
 * Connect to SurrealDB with the given configuration
 */
async function connectToSurrealDB(config: SurrealDBConfig, logger: any): Promise<Surreal> {
  logger.info('------->[BetterAuth : SurrealDB] : Establishing connection...')

  const db = new Surreal()
  await db.connect(config.url, {
    namespace: config.namespace,
    database: config.database,
    auth: {
      username: config.username,
      password: config.password,
    },
  })

  logger.info('------->[BetterAuth : SurrealDB] : Connection established successfully')
  return db
}

/**
 * Ensure database connection is alive, reconnect if needed
 * Based on the working pattern from surreal-better-auth adapter
 */
async function ensureConnection(c: Context): Promise<Surreal> {
  const config = getSurrealDBConfig(c)
  const logger = c.var.logger

  // Test existing connection
  if (dbInstance) {
    try {
      logger.info('------->[BetterAuth : SurrealDB] : Testing existing connection...')
      await dbInstance.query('SELECT * FROM user LIMIT 1')
      logger.info('------->[BetterAuth : SurrealDB] : Existing connection is alive')
      return dbInstance
    }
    catch (error: any) {
      logger.warn('------->[BetterAuth : SurrealDB] : Connection is dead, resetting and reconnecting', {
        error: error.message,
      })
      // Connection is dead, reset and reconnect
      dbInstance = null
      authInstance = null // Reset auth instance as well
    }
  }

  // If already connecting, wait for that connection
  if (isConnecting && connectionPromise) {
    logger.info('------->[BetterAuth : SurrealDB] : Connection in progress, waiting...')
    return connectionPromise
  }

  // Create new connection
  isConnecting = true
  connectionPromise = new Promise<Surreal>((resolve, reject) => {
    connectToSurrealDB(config, logger)
      .then((newDb) => {
        dbInstance = newDb
        isConnecting = false
        connectionPromise = null
        resolve(newDb)
      })
      .catch((error) => {
        logger.error('------->[BetterAuth : SurrealDB] : Connection failed', error)
        isConnecting = false
        connectionPromise = null
        reject(error)
      })
  })

  return connectionPromise
}

/**
 * Create BetterAuth instance with SurrealDB adapter
 */
function createBetterAuthInstance(c: Context, db: Surreal): ReturnType<typeof betterAuth> {
  const env = c.env

  c.var.logger.info('------->[BetterAuth] : Creating new BetterAuth instance...')

  return betterAuth({
    ...getBetterAuthOptions({
      SURREALDB_NS: env.SURREALDB_NS,
      SURREALDB_DB: env.SURREALDB_DB,
      SURREALDB_AUTH_AC: env.SURREALDB_AUTH_AC,
      CHROME_EXTENSION_ID: env.CHROME_EXTENSION_ID,
    }),

    database: surrealdbAdapter(db, {
      debugLogs: true,
      idGenerator: 'surreal.ULID',
      allowPassingId: true,
    }),

    baseURL: env.BETTER_AUTH_URL,
    secret: env.BETTER_AUTH_SECRET,
  })
}

/**
 * Get or create BetterAuth instance with automatic reconnection support
 */
export async function auth(c: Context): Promise<ReturnType<typeof betterAuth>> {
  // Ensure we have a valid database connection
  const db = await ensureConnection(c)

  // Create new auth instance if it doesn't exist or db has changed
  if (!authInstance || dbInstance !== db) {
    authInstance = createBetterAuthInstance(c, db)
  }

  return authInstance
}

[oskar-gmerek]

Hi @agentic-com !

Thanks for raising this and sharing your implementation.

I want to clarify that surreal-better-auth is intentionally designed to be decoupled from the database connection lifecycle. Managing the connection state (initialization, keep-alive, reconnection) is out of the scope of this adapter. This design choice ensures the adapter remains lightweight and fully agnostic, giving developers complete freedom to configure their environment according to their specific needs without the adapter imposing any logic on the Surreal instance.

That being said, the code you shared is a valuable reference for anyone looking for inspiration on how to handle reconnection logic at the application level, specifically within the Hono framework. It provides a solid foundation for developers to build upon. Thank you for sharing it.

To keep this visible for the community as a "recipe" rather than a bug report, I will convert this Issue into a Discussion. This way, it serves as a helpful resource for others facing similar implementation challenges.

Quick question: Do you feel the current documentation/README makes this distinction clear enough? I’d be happy to add a brief note clarifying that connection management is strictly the consumer's responsibility if you think the current wording is ambiguous.