{"id":19293660,"url":"https://github.com/tursodatabase/libsql-shell-go","last_synced_at":"2025-12-24T08:48:50.736Z","repository":{"id":157563245,"uuid":"599635333","full_name":"tursodatabase/libsql-shell-go","owner":"tursodatabase","description":null,"archived":false,"fork":false,"pushed_at":"2024-09-03T19:07:26.000Z","size":255,"stargazers_count":7,"open_issues_count":31,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-20T08:56:20.783Z","etag":null,"topics":["golang","libsql","shell","sqlite"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tursodatabase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-09T15:03:56.000Z","updated_at":"2025-03-10T22:02:50.000Z","dependencies_parsed_at":"2024-07-16T22:07:27.404Z","dependency_job_id":"f3422a46-729c-459a-b73a-675a52f3de50","html_url":"https://github.com/tursodatabase/libsql-shell-go","commit_stats":null,"previous_names":["tursodatabase/libsql-shell-go","chiselstrike/libsql-shell","libsql/libsql-shell-go"],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tursodatabase%2Flibsql-shell-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tursodatabase%2Flibsql-shell-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tursodatabase%2Flibsql-shell-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tursodatabase%2Flibsql-shell-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tursodatabase","download_url":"https://codeload.github.com/tursodatabase/libsql-shell-go/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250195054,"owners_count":21390230,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","libsql","shell","sqlite"],"created_at":"2024-11-09T22:35:41.945Z","updated_at":"2025-12-24T08:48:50.724Z","avatar_url":"https://github.com/tursodatabase.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# libSQL Shell\n\nlibSQL shell is a standalone program written in Go for querying SQLite database files and libSQL databases running [sqld](https://github.com/libsql/sqld).\n\n## Table of Contents\n\n- [libSQL Shell](#libsql-shell)\n  - [Table of Contents](#table-of-contents)\n  - [Running the shell](#running-the-shell)\n    - [Query SQLite database files](#query-sqlite-database-files)\n    - [Query sqld](#query-sqld)\n    - [Query a Turso database](#query-a-turso-database)\n    - [Built-in help](#built-in-help)\n  - [Development](#development)\n    - [Install git hooks](#install-git-hooks)\n    - [Install golangci-lint](#install-golangci-lint)\n    - [Configure tests](#configure-tests)\n\n## Running the shell\n\nAfter cloning this repo, you can start the shell using `go run` or create an executable using `go build`.\n\nThere is only one argument: the database to query. When the shell is connected to the database, it allows interactive SQL queries.\n\n### Query SQLite database files\n\nTo start a shell that queries a [SQLite database file](https://www.sqlite.org/fileformat.html), provide a path to the file:\n\n```sh\ngo run ./cmd/libsql-shell/main.go my_libsql.db\n```\n\n### Query sqld\n\nTo start a shell that queries a libSQL database running sqld, provide the database connection URL. For example, for sqld running locally:\n\n```sh\ngo run ./cmd/libsql-shell/main.go ws://127.0.0.1:8080\n```\n\n### Query a Turso database\n\nTo query sql managed by [Turso](https://turso.tech), you need a database URL and token. Assuming you have already logged in to the CLI and created a database:\n\n1. Get your database URL: `turso db show \u003cdb_name\u003e`. The URL will be on the format `libsql://\u003cdb_name\u003e-\u003cusername\u003e.turso.io`\n1. Create a database token: `turso db tokens create \u003cdb_name\u003e`\n\nProvide the database URL and token using the `--auth` flag:\n\n```sh\ngo run ./cmd/libsql-shell/main.go libsql://\u003cdb_name\u003e-\u003cusername\u003e.turso.io --auth \u003cdb_token\u003e\n```\n\n### Built-in help\n\nThe shell has built-in commands similar to the [SQLite CLI](https://www.sqlite.org/cli.html). Get a list of commands with `.help`.\n\n## Development\n\n### Install git hooks\n\nGit 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:\n\n```bash\n./scripts/git/install-git-hooks.sh\n```\n\n### Install golangci-lint\n\nThe above git hooks require `golangci-lint` in your PATH. [Install golangci-lint](https://golangci-lint.run/usage/install/).\n\n### Configure tests\n\nThe 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:\n\n  - `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](#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 \u003cturso_test_db_name\u003e`\n    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.\n  - `skip_sqld_tests`: Used to skip SQLD related tests\n\n### Running tests against a locally-running sqld instance\n\nAn easy way to get an SQLD server locally is by running the remote docker image:\n\n``` shell\ndocker run -p 8080:8080 -d ghcr.io/libsql/sqld:latest\n```\n\nThis command runs the latest version available, exposing the server on (http://localhost:8080). You can checkout other versions\n[here](https://github.com/libsql/sqld/pkgs/container/sqld).\nNow, 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:\n\n``` shell\ngo test -v ./...\n```\n\nYou can confirm that the sqld instance was hit by checking the server logs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftursodatabase%2Flibsql-shell-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftursodatabase%2Flibsql-shell-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftursodatabase%2Flibsql-shell-go/lists"}