Databases
Learn how to deploy, drop, view, and execute queries on a database
The
database subcommand contains all of the commands necessary for interacting with databases. Currently, the subcommand supports the following functionalities:- Deploy: Deploying a database schema
- Drop: Dropping a database schema
- List: Listing database schemas for a wallet
- Read Schema: Displays the schema of a deployed database
- Execute: Execute a query against a database
The
deploy subcommand is used to deploy a database schema. The CLI can read in the JSON representation of a schema, and deploy it to the Kwil network. Read more about JSON Database schemas in the databases section.The
deploy command takes no arguments, however has one required flag. Users must specify the relative filepath to their JSON with the --path or -p flag.kwil-cli database deploy --path=./my_db.json
If you're looking to deploy a database ASAP, we recommend using our database builder tool. It is more native than building your own JSON from scratch, and includes validation tools to help prevent errors.
The
drop subcommand is used to drop a deployed database. You can only drop databases that have been deployed with your configured wallet. The drop command takes one argument, which is the name of the database you wish to drop.kwil-cli database drop mydb
The
list subcommand is used to list the databases deployed by a particular wallet. This command takes no arguments, and by default will list the databases for the wallet you have configured. You can list databases deployed from any wallet using the optional --owner (or -o) flag.kwil-cli database list --owner=0x37Fc1953e4A26007E6Df52f06B5897a998F51f5D
The
read-schema subcommand is used to display schema information for a deployed database. This command takes no arguments, however it can accept several different flags. A database can either be selected with an owner and name, or with a database ID. If both are passed as flags, it will give preference to the database ID.To select a database by its owner and name, you can use the
--owner (or -o) flag, and the --name (or -n) flag. If no --owner flag is provided, it will default to databases owned by the wallet you are using, if a wallet has been configured.kwil-cli database read-schema --name=mydb
or
kwil-cli database read-schema --owner=0x37Fc1953e4A26007E6Df52f06B5897a998F51f5D --name=db1
Alternatively, you can pass the
--dbid flag (or -i) to identify the database to read from.kwil-cli database read-schema --dbid=xc57b99f921ac99896d861b4462d7874212e0a63e53b2c53d91b0f6d2
The
execute subcommand is used to execute against the database. Currently, Kwil does not support ad-hoc queries, and only supports prepared statements defined in your schema.To specify the name of the database you are targeting, you must use either pass a database
--owner and --name, or a --dbid. This works exactly the same as the read-schema command, where it will auto-fill your address if you only pass a --name flag.To specify the name of the query you wish to execute, you also have to pass a required
--query flag. This name must be the same as the one defined in your database. To read more about query definitions, see the SQL Queries section.Finally, in order to pass parameters to the query, you must specify the inputs as arguments. You must first specify the name of the parameter you are filling, and then the value. Queries shouldd follow the layout below
kwil-cli database execute [param_1_name] [param_1_value] [param_2_name] [param_2_value] --query=[query_name] --dbid=[db_id]
For example, if you were executing an INSERT query named "create_user" that took two parameters: name (string), and age (int32), you would pass my arguments as follows:
kwil-cli database execute name satoshi age 32 --query=create_user --name=mydb --owner=0x37Fc1953e4A26007E6Df52f06B5897a998F51f5D
Last modified 1mo ago