Direct Database access

carpo.database is the official @libsql/client client. Configure it with a managed database URL and an access token created in Carpo. It exposes the driver's execute, batch, transaction, and close methods.

const result = await carpo.database.execute({
  sql: 'SELECT id, title FROM todos WHERE user_id = ? ORDER BY id DESC LIMIT 50',
  args: [userId],
})

console.log(result.rows)

Use parameterized SQL for values. Direct SQL is for trusted server code. It is not filtered by the browser Database Data API's per user table permissions or owner scope. If the query returns user data, check that user's authorization before choosing rows or returning the result.

Access token scopeCopy Anchor Link

The access token's configured read only or full access mode and expiry are enforced by Turso. Keep full access tokens in server only configuration. The SDK does not place a Turso credential in browser code.

Use the policy checked API insteadCopy Anchor Link

For server requests that should retain the incoming Project Auth user and use the same table permissions as browser code, use the request scoped client. Its Database methods go through the Data API and do not open a direct database connection.

Use createCarpoServerDatabaseClient() from @carpodev/carpo-sdk/server/database if you need the native libSQL client without Auth, Functions, or Storage.