star tool
The star
tool is a cross-platform command-line tool, distributed as a stand-alone console application, used to manage Starcounter databases and applications. By using the star
tool, you can – for example – create, modify, delete and query Starcounter databases, as well as import and export data from compatible 3:rd party data sources.
The easiest way to explore the features of the star
tool is to use it, in particular with the --help
option, which prints help information about available commands and options. In this article, we will provide a reference for the available commands and describe some common use cases.
Distribution
The Windows and Linux versions of the tool are downloaded together with the main Starcounter binaries. For Linux operating systems, make sure to also install the prerequisites listed at the installation page and grant execution permissions (chmod -R u+x /path/to/star/tool/folder
).
Usage
The star
tool is a console application with a command-line interface, and we interact with it using commands, options and arguments.
The global command pattern is:
Specific commands may have different sub-patterns, which are defined in their respective sections below. The option --help
is defined for each command, and can be used to print details on available options and sub-commands.
In examples below, Windows-style directory paths are used. On Linux operating systems, the star
tool expects Linux-style paths.
Commands
The available commands can be split into four categories:
Database management commands, used for creating and starting databases.
Import and export commands, used for importing and exporting data to or from SQLite database files.
Information commands, e.g. printing all tables or listing all indexes of a given table.
SQL REPL, used for executing DML and DDL statements manipulating the database schema and data.
Database management
clean
The clean
command permanently removes dropped tables and columns from the database referenced by the absolute or relative path given in the argument.
new
The new
command creates a new database at the absolute or relative path provided in the <path>
argument. If the directory referenced by the path does not exist, it will be created. To create a new database at the path C:\databases\mydb
, we run:
start
The start
command starts the database referenced by the absolute or relative path given in the <db>
argument. To start an existing database located at C:\databases\mydb
, we run:
Import and export
reload
The reload
command takes data from an SQLite database file referenced by the absolute or relative path in the <file>
argument and imports that data into the database referenced by the absolute or relative path given in the <db>
argument. To load data from an SQLite database file named myDatabase.sqlite3
located in C:\databases
into an existing database located at C:\databases\mydb
, we run:
Note: only files created with the unload
command can be reloaded.
unload
The unload
command selects the SQLite database file at the path given in the <file>
argument, or creates one if it doesn't exists, and then takes data from a database referenced by the absolute or relative path given in the <db>
argument and imports that data into the created SQLite database. To load data from an existing database located at C:\databases\mydb
into a new SQLite database file named myDatabase.sqlite3
at C:\databases
, we run:
Information
list
The list
command is used together with one of the following sub-commands to list ranges of entities in a database:
list table
The list table
sub-command lists all tables in the database referenced by the absolute or relative path given in the <db>
argument. The following options are available to configure the output of the command:
Formatting options:
t
– Include the name of the table to list.b
– Include the name of the base table (if inherited) of the table to list.
To list all tables of an existing database located at C:\databases\mydb
, including only user tables and displaying both the name of the table and the name of its base table (if any), we run:
list index
The list index
sub-command lists all indexes in a table, the name of which is specified by the <table>
argument, in the database referenced by the absolute or relative path given in the <db>
argument. The following options are available to configure the output of the commmand:
Formatting options:
i
– Include the name of the index to list.t
– Include the name of the table of the index.u
– Include whether or not the index is unique.
To list all indexes of the table MyApp.Superhero
, of an existing database located at C:\databases\mydb
, including both user indexes and system indexes and both the name of the index and whether it's unique, we run:
info
The info
command is used together with one of the following sub-commands to print info about some specific entity in a database:
info table
The info table
sub-command prints detailed information about a table, the name of which is specified in the <table>
argument, in the database referenced by the absolute or relative path given in the <db>
argument. The following options are available to configure the output of the command:
Formatting options:
c
– Include the name of the columns of the table to list.t
– Include the datatype of the columns of the table to list.n
– For each column, include whether it accepts null values in table cells.i
– For each column, include whether it is inherited.b
– Include the name of the table of the column.
To list all user columns of the MyApp.Superhero
table of an existing database located at C:\databases\mydb
, including inherited columns and listing only the names and the datatypes of columns, we run:
info index
The info index
sub-command prints detailed information about an index, the name of which is specified in the <index>
argument, in the database referenced by the absolute or relative path given in the <db>
argument. The following options are available to configure the output of the command:
Formatting options:
c
– Include the name of the column that the index is registered on.b
– Include the name of the table that holds the column that the index is registered on.
To list all indexes of the MyApp.Superhero
table of an existing database located at C:\databases\mydb
, including only the name of the column of the index, we run:
SQL REPL
sql
The star
tool includes a built-in SQL REPL (read-eval-print loop) component that can be used to execute DDL and DML statements on the database referenced by the absolute or relative path given in the <db>
argument.
To enter the SQL REPL for an existing database located at C:\databases\mydb
, we run:
For more information on how to write SQL queries to a Starcounter database, and supported DDL statements, see the SQL section of the documentation.
Last updated