This guide will walk you through the process of migrating your existing SQLite database to Turso Cloud. You can choose between using the Turso CLI, or the Platform API.

​
Preparing to Migrate

Before importing your SQLite database to Turso, you need to ensure it’s compatible with Turso’s requirements. Specifically, your SQLite database should be using WAL (Write-Ahead Logging) mode.

1

Open your SQLite database

Use the SQLite command-line tool or any SQLite client to open your database:

sqlite3 path/to/your/database.db
2

Set WAL journal mode

Run the following command to switch your database to WAL mode:

PRAGMA journal_mode='wal';

This should return wal to confirm the change was successful.

3

Checkpoint and truncate the WAL file

Execute a checkpoint to ensure all changes are written to the main database file and truncate the WAL file:

PRAGMA wal_checkpoint(truncate);
4

Verify the journal mode

Confirm that your database is now in WAL mode:

PRAGMA journal_mode;

This should return wal.

5

Close the database

Exit the SQLite shell:

.exit

Your database is now ready for migration to Turso.

​
Using the CLI

You can create a new database from a local SQLite file using the Turso CLI:

1

Install the Turso CLI

Make sure you have the Turso CLI installed, and you’re authenticated.

2

Import your SQLite Database

Import your existing SQLite database file using the db import command:

turso db import ~/path/to/my-database.db

Your database will be named after the file (without the .db extension), and will import all your tables, data, and schema.

3

Connect to your database

You can now connect to your database using the shell:

turso db shell <database-name>

​
Using the Platform API

You can also use the Platform API to migrate your existing SQLite database:

1

Signup or Login using the Turso CLI

Make sure to install the Turso CLI if you haven’t already.

turso auth signup
2

Create a new Platform API Token

Now create a new API Token using the Turso CLI:

turso auth api-tokens mint quickstart

Make sure to save the token somewhere safe. You’ll need it to create a database and database token.

3

Retrieve your account or organization slug

The Platform API can be used with your personal account or with an organization. You’ll need the obtain the slug of your account or organization using using the Turso CLI:

turso org list
4

Create a Database for Import

First, create a database that’s ready to receive an import:

curl -X POST "https://api.turso.tech/v1/organizations/{organizationSlug}/databases" \
  -L \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "new-database",
      "group": "default",
      "seed": { "type": "database_upload" }
  }'

The seed parameter with "type": "database_upload" indicates that you plan to upload a database file. If you don’t proceed to upload a database, this database will count towards your quota, but will not be usable.

5

Create a Database Token

Generate an authentication token for your database:

curl -X POST "https://api.turso.tech/v1/organizations/{organizationSlug}/databases/{databaseName}/auth/tokens" \
  -L \
  -H "Authorization: Bearer TOKEN"

This token will be used to authenticate your upload request, and future requests to the database.

6

Upload Your SQLite Database

Finally, upload your SQLite database file:

curl -X POST "https://{databaseName}-{organizationSlug}.turso.io/v1/upload" \
  -H "Authorization: Bearer DATABASE_TOKEN" \
  --data-binary @/path/to/your/database.db

The Authorization header uses the database token you generated in the previous step, not your Platform API token.

You’re now ready to connect to your new Turso database using any of the Turso client libraries.

TypeScript / JS

Rust

Go

Python

Android

Swift

PHP

Ruby

Ruby on Rails

C

libSQL Remote Protocol

Was this page helpful?

Suggest editsRaise issue