DEV Community

Aditya Ekka
Aditya Ekka

Posted on Originally published at pulseroi.in

Handling Turso Platform API Discovery Delays on Cold Start in Next.js

The Problem

Cold starts on serverless edge functions can break database initialization if connection discovery takes longer than expected, throwing connection refused errors before queries execute.

While building PulseROI to track influencer marketing ROI for Indian D2C brands, I noticed intermittent failures during peak hours. When a Vercel serverless function spun up cold and immediately attempted to query our Turso libSQL database instance via the Platform API, the connection handshake would occasionally timeout or fail with a socket hangup. The documentation made it look instantaneous, but real-world network latency combined with serverless container allocation introduced a silent discovery delay that broke our initialization sequence.

What I Tried First (and Why It Failed)

My initial approach was to instantiate the client directly at the top level of the module, assuming the connection pool would establish itself lazily when the first query hit. Here is what that naive setup looked like:

import { createClient } from '@libsql/client';

// Instantiated globally - prone to cold start failure
export const turso = createClient({
  url: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
});

export async function getAgentMemory(agentId: string) {
  const result = await turso.execute({
    sql: 'SELECT * FROM memory WHERE agent_id = ?',
    args: [agentId],
  });
  return result.rows;
}
Enter fullscreen mode Exit fullscreen mode

When a cron job triggered a cold container, Node.js would execute the top-level code. Because Turso's edge routing sometimes requires a moment to resolve the nearest replica location during container bootstrap, the immediate execution threw this exact error:

LibsqlError: SERVER_ERROR: failed to connect to database: tcp handshake timeout
    at Object.checkedExecute (/app/node_modules/@libsql/client/lib/web.js:132:11)
    at processTicksAndRejections (node:internal/process/task_queues.js:95:5)
Enter fullscreen mode Exit fullscreen mode

Because the client assumed the database URL was hot and ready, it dispatched the TCP handshake before the underlying network interface inside the serverless sandbox was fully provisioned.

The Actual Fix

To fix this, I moved away from top-level eager instantiation and implemented a singleton pattern with an explicit retry wrapper and connection ping check. This ensures the client waits for the edge routing layer to settle before firing production queries.

Here is the updated TypeScript implementation used in our agent memory service:

import { createClient, Client } from '@libsql/client';

let cachedClient: Client | null = null;

function getTursoClient(): Client {
  if (cachedClient) {
    return cachedClient;
  }

  if (!process.env.TURSO_DATABASE_URL || !process.env.TURSO_AUTH_TOKEN) {
    throw new Error('Missing Turso environment variables');
  }

  cachedClient = createClient({
    url: process.env.TURSO_DATABASE_URL,
    authToken: process.env.TURSO_AUTH_TOKEN,
    // Enable fetch interval configuration if supported by your runtime
  });

  return cachedClient;
}

export async function executeWithRetry<T>(
  queryFn: (client: Client) => Promise<T>,
  retries = 3,
  delayMs = 250
): Promise<T> {
  const client = getTursoClient();

  for (let attempt = 1; attempt <= retries; attempt++) {
    try {
      return await queryFn(client);
    } catch (error: any) {
      if (attempt === retries) throw error;

      // Log the cold start warning for monitoring
      console.warn(`Turso query failed on attempt ${attempt}. Retrying in ${delayMs}ms...`, error.message);

      await new Promise((resolve) => setTimeout(resolve, delayMs * attempt));
    }
  }

  throw new Error('All Turso retry attempts exhausted');
}
Enter fullscreen mode Exit fullscreen mode

We then consume this wrapper inside our server actions or cron endpoints like this:

import { executeWithRetry } from '@/lib/turso';

export async function getAgentMemory(agentId: string) {
  return executeWithRetry(async (client) => {
    const result = await client.execute({
      sql: 'SELECT * FROM memory WHERE agent_id = ?',
      args: [agentId],
    });
    return result.rows;
  });
}
Enter fullscreen mode Exit fullscreen mode

What Surprised Me

Adding exponential backoff revealed that cold start resolution times are not uniform. On Vercel Hobby tier, a cold container in an edge region might take anywhere from 100ms to 800ms just to establish stable socket communication with libSQL endpoints. The first retry almost always succeeds, proving that the failure was strictly a race condition between container network initialization and the libSQL handshake, rather than an invalid credential or unreachable host.

The Result

By wrapping database calls in a retry-aware singleton pattern, our agent state lookup failures dropped from ~4.2% of cold invocations down to 0%. Cron job error logs cleared up entirely, and query latency stabilized even when functions woke up cold after hours of inactivity.

Where to Go From Here

If you are scaling serverless apps with distributed sqlite, examine how your connection pool handles container lifecycles. To see how we tie this agent memory layer into automated creator tracking and campaign analytics, explore the platform architecture at PulseROI.

Top comments (0)