libSQL Shell

libSQL shell is a standalone program written in Go for querying SQLite database files and libSQL databases running sqld.

Table of Contents

• libSQL Shell
  • Table of Contents
  • Running the shell
  • Query SQLite database files
  • Query sqld
  • Query a Turso database
  • Built-in help
  • Development
  • Install git hooks
  • Install golangci-lint
  • Configure tests

Running the shell

After cloning this repo, you can start the shell using go run or create an executable using go build.

There is only one argument: the database to query. When the shell is connected to the database, it allows interactive SQL queries.

Query SQLite database files

To start a shell that queries a SQLite database file, provide a path to the file:

go run ./cmd/libsql-shell/main.go my_libsql.db

Query sqld

To start a shell that queries a libSQL database running sqld, provide the database connection URL. For example, for sqld running locally:

go run ./cmd/libsql-shell/main.go ws://127.0.0.1:8080

Query a Turso database

To query sql managed by Turso, you need a database URL and token. Assuming you have already logged in to the CLI and created a database:

1. Get your database URL: turso db show <db_name>. The URL will be on the format libsql://<db_name>-<username>.turso.io
2. Create a database token: turso db tokens create <db_name>

Add the token to the URL in the authToken query string parameter and provide that to the shell:

go run ./cmd/libsql-shell/main.go libsql://<db_name>-<username>.turso.io/?auth=<db_token>`

Built-in help

The shell has built-in commands similar to the SQLite CLI. Get a list of commands with .help.

Development

Install git hooks

Git Hooks are shell scripts that run automatically before or after Git executes an important command, such as Commit or Push. To install it, run the command:

./scripts/git/install-git-hooks.sh

Install golangci-lint

The above git hooks require golangci-lint in your PATH. Install golangci-lint.

Configure tests

The tests are configured through .test_config.yaml file. Copy .test_config.yaml.example to create your .test_config.yaml and see below the description for each field:

• sqld_db_uri: URL for sqld database used during the tests. It should be a dedicated database once it's cleared after each test. In particular, for turso databases, follow the steps from Running the Project/Turso to generate a Turso db path. For this database, it's useful to generate a non-expiration token with turso db tokens create --expiration none <turso_test_db_name> If you're working with a local server pass the local address inside this env variable. In case it's a local file, provide the file path.
• skip_sqld_tests: Used to skip SQLD related tests

Running tests against a locally-running sqld instance

An easy way to get an SQLD server locally is by running the remote docker image:

docker run -p 8080:8080 -d ghcr.io/libsql/sqld:latest

This command runs the latest version available, exposing the server on (http://localhost:8080). You can checkout other versions here. Now, in libsql-shell-go, edit your test_config.yaml file by adding the URL of the locally running sqld server under sqld_db_uri. Remember to set the variable skip_sqld_tests to false, otherwise, sqld-related tests will be skipped. Once you have this configuration and the sqld instance running simply run the tests normally:

go test -v ./...

You can confirm that the sqld instance was hit by checking the server logs.