tursodatabase / libsql-shell-go

7 stars 7 forks source link
golang libsql shell sqlite

libSQL Shell

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

Table of Contents

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:

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.