docs.turso.tech/sdk/ts/

Starting URLs:
https://docs.turso.tech/sdk/ts/
## Page: https://docs.turso.tech/sdk/ts/

In this JavaScript quickstart we will learn how to:

*   Retrieve database credentials
*   Install the JavaScript libSQL client
*   Connect to a remote Turso database
*   Execute a query using SQL

1

Retrieve database credentials

You will need an existing database to continue. If you don’t have one, create one.

Get the database URL:

    turso db show --url <database-name>
    

Get the database authentication token:

    turso db tokens create <database-name>
    

Assign credentials to the environment variables inside `.env`.

    TURSO_DATABASE_URL=
    TURSO_AUTH_TOKEN=
    

You will want to store these as environment variables.

2

Install @libsql/client

Begin by installing the `@libsql/client` dependency in your project:

    npm install @libsql/client
    

3

Initialize a new client

Next add your database URL and auth token:

    import { createClient } from "@libsql/client";
    
    export const turso = createClient({
      url: process.env.TURSO_DATABASE_URL,
      authToken: process.env.TURSO_AUTH_TOKEN,
    });
    

4

Execute a query using SQL

You can execute a SQL query against your existing database by calling `execute()`:

    await turso.execute("SELECT * FROM users");
    

If you need to use placeholders for values, you can do that:

    await turso.execute({
      sql: "SELECT * FROM users WHERE id = ?",
      args: [1],
    });

---

## Page: https://docs.turso.tech/sdk/ts/quickstart

In this JavaScript quickstart we will learn how to:

*   Retrieve database credentials
*   Install the JavaScript libSQL client
*   Connect to a remote Turso database
*   Execute a query using SQL

1

Retrieve database credentials

You will need an existing database to continue. If you don’t have one, create one.

Get the database URL:

    turso db show --url <database-name>
    

Get the database authentication token:

    turso db tokens create <database-name>
    

Assign credentials to the environment variables inside `.env`.

    TURSO_DATABASE_URL=
    TURSO_AUTH_TOKEN=
    

You will want to store these as environment variables.

2

Install @libsql/client

Begin by installing the `@libsql/client` dependency in your project:

    npm install @libsql/client
    

3

Initialize a new client

Next add your database URL and auth token:

    import { createClient } from "@libsql/client";
    
    export const turso = createClient({
      url: process.env.TURSO_DATABASE_URL,
      authToken: process.env.TURSO_AUTH_TOKEN,
    });
    

4

Execute a query using SQL

You can execute a SQL query against your existing database by calling `execute()`:

    await turso.execute("SELECT * FROM users");
    

If you need to use placeholders for values, you can do that:

    await turso.execute({
      sql: "SELECT * FROM users WHERE id = ?",
      args: [1],
    });

---

## Page: https://docs.turso.tech/sdk/ts/reference

The following runtime environments are known to be compatible:

*   Node.js version 12 or later
*   Deno
*   CloudFlare Workers
*   Netlify & Vercel Edge Functions

## Installing

Begin by installing the `@libsql/client` dependency in your project:

## Initializing

Import `createClient` to initialize a client that you can use to query your database:

  

## In-Memory Databases

libSQL supports connecting to in-memory databases for cases where you don’t require persistence:

## Local Development

You can work locally using an SQLite file and passing the path to `createClient`:

## Embedded Replicas

You can work with embedded replicas by passing your Turso Database URL to `syncUrl`:

### Manual Sync

The `sync()` function allows you to sync manually the local database with the remote counterpart:

### Periodic Sync

You can automatically sync at intervals by configuring the `syncInterval` (seconds) property when instantiating a new libSQL client:

## Encryption

To enable encryption on a SQLite file, pass the `encryptionKey`:

TypeScript

Encrypted databases appear as raw data and cannot be read as standard SQLite databases. You must use the libSQL client for any operations — learn more.

## Concurrency

By default, the client performs up to `20` concurrent requests. You can set this option to a higher number to increase the concurrency limit. You can also set this option to `undefined` to disable concurrency completely:

## Response

Each method listed below returns a `Promise<ResultSet>`:

| Property | Type | Description |
| --- | --- | --- |
| `rows` | `Array<Row>` | An array of Row objects containing the row values, empty for write operations |
| `columns` | `Array<string>` | An array of strings with the names of the columns in the order they appear in each Row, empty for write operations |
| `rowsAffected` | `number` | The number of rows affected by a write statement, `0` otherwise |
| `lastInsertRowid` | `bigint | undefined` | The ID of a newly inserted row, or `undefined` if there is none for the statement |

## Simple query

You can pass a string or object to `execute()` to invoke a SQL statement:

## Placeholders

libSQL supports the use of positional and named placeholders within SQL statements:

  

## Transaction Modes

| Mode | SQLite command | Description |
| --- | --- | --- |
| `write` | `BEGIN IMMEDIATE` | The transaction may execute statements that read and write data. Write transactions executed on a replica are forwarded to the primary instance, and can’t operate in parallel. |
| `read` | `BEGIN TRANSACTION READONLY` | The transaction may only execute statements that read data (select). Read transactions can occur on replicas, and can operate in parallel with other read transactions. |
| `deferred` | `BEGIN DEFERRED` | The transaction starts in read mode, then changes to write as soon as a write statement is executed. This mode change may fail if there is a write transaction currently executing on the primary. |

## Batch Transactions

A batch consists of multiple SQL statements executed sequentially within an implicit transaction. The backend handles the transaction: success commits all changes, while any failure results in a full rollback with no modifications.

## Interactive Transactions

Interactive transactions in SQLite ensure the consistency of a series of read and write operations within a transaction’s scope. These transactions give you control over when to commit or roll back changes, isolating them from other client activity.

| Method | Description |
| --- | --- |
| `execute()` | Similar to `execute()` except within the context of the transaction |
| `commit()` | Commits all write statements in the transaction |
| `rollback()` | Rolls back the entire transaction |
| `close()` | Immediately stops the transaction |

  

## ATTACH

You can attach multiple databases to the current connection using the `ATTACH` attachment:

---

## Page: https://docs.turso.tech/sdk/ts/examples

*   *   GitHub Copilot
        
        Write better code with AI
        
    *   GitHub Advanced Security
        
        Find and fix vulnerabilities
        
    *   Actions
        
        Automate any workflow
        
    *   Codespaces
        
        Instant dev environments
        
    *   Issues
        
        Plan and track work
        
    *   Code Review
        
        Manage code changes
        
    *   Discussions
        
        Collaborate outside of code
        
    *   Code Search
        
        Find more, search less
        
    

*   Explore
    
    *   Learning Pathways
    *   Events & Webinars
    *   Ebooks & Whitepapers
    *   Customer Stories
    *   Partners
    *   Executive Insights
    
*   *   GitHub Sponsors
        
        Fund open source developers
        
    
    *   The ReadME Project
        
        GitHub community articles
        
    
*   *   Enterprise platform
        
        AI-powered developer platform
        
    
*   Pricing

## Provide feedback

## Saved searches

## Use saved searches to filter your results more quickly

Sign up