kwil-db

module
v0.7.6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 16, 2024 License: Apache-2.0

README

Kwil

The database for Web3.

banner

Github-License Release Build-Status Go-Version GoDoc Go-Report-Card Discord

Kwil is the node software for Kwil Networks. Built with PostgreSQL and CometBFT, Kwil enables byzantine fault tolerant networks to be built on top of relational databases.

Overview

To learn more about high-level Kwil concepts, refer to the Kwil documentation.

To test deploying and using a Kuneiform schema (Kwil's smart contract language) on the Kwil testnet, refer to the Kwil testnet tutorial.

For more information on kwil-db, check out the Kwil node documentation.

Quickstart

Build Instructions
Prerequisites

To build Kwil, you will need to install:

  1. Go 1.21 or 1.22

  2. (optional) Protocol Buffers, with the protoc executable binary on your PATH.

  3. (optional) Taskfile

  4. (optional) Protocol buffers go plugins and other command line tools. The tool task will install the required versions of the tools into your GOPATH, so be sure to include GOPATH/bin on your PATH.

    task tools
    

Only Go is required to build directly from the cmd/kwild folder or via go install, although developers may require the other tools.

To run Kwil, PostgreSQL is also required. See the documentation for more information.

Build

The build task will compile kwild, kwil-cli, and kwil-admin binaries. They will be generated in .build/:

task build

You may also build the individual applications manually:

cd cmd/kwild
go build

Or without even cloning the source repository:

go install github.com/kwilteam/kwil-db/cmd/kwild@v0.7.0

Just replace v0.7.0 with the desired version or latest.

Running kwild

Running kwild requires a PostgreSQL host running. Since the default configuration of most PostgreSQL packages requires changes for kwild, the easiest is to run our pre-configured Docker image:

docker run -p 5432:5432 -v kwil-pg-demo:/var/lib/postgresql/data \
    --shm-size 256m -e "POSTGRES_HOST_AUTH_METHOD=trust" \
    --name kwil-pg-demo kwildb/postgres:latest

The first time this is run, it will pull the kwildb/postgres image from Docker Hub and create a new persistent Docker volume named kwil-pg-demo. NOTE: This command requires no authentication with postgres, and should not be used in production.

task pg may be used to run the above command.

You can then start a single node network using the kwild binary built in the previous section:

# Use the full path to kwild if it is not on your PATH.
kwild --autogen

With the --autogen flag, the node automatically creates a new random network and validator key, and the node will begin producing blocks.

For more information on running nodes, and how to run a multi-node network, refer to the Kwil documentation.

Resetting node data

By default, kwild stores all data in ~/.kwild. To reset the data on a deployment, remove the data directory while the node is stopped:

rm -r ~/.kwild

Then delete the PostgreSQL database. If using the Docker image or service, delete the container and it's volume:

docker container rm -f kwil-pg-demo
docker volume rm -f kwil-pg-demo

task pg:clean may be used to run the above commands.

If using a system install of postgres, recreate the database with psql:

psql -U postgres -h 127.0.0.1 -d postgres \
    -c "DROP DATABASE IF EXISTS kwild" \
    -c "CREATE DATABASE kwild OWNER kwild"
Unified kwild + postgres Quickstart Docker Service

For development purposes, the deployments/compose/kwil folder contains a Docker Compose service definition that starts both kwild and postgres, configured so that they will work together out-of-the-box with no additional configuration changes. Start it by running the following from the deployments/compose/kwil folder in the repository:

cd deployments/compose/kwil
docker compose up --build -d

With the -d option, the service(s) will be started as background processes. To stop them or view logs, use the docker container commands or the Docker Desktop dashboard.

On start, this service definition will create a testnode folder in the same location as the docker-compose.yml file, and a persistent Docker volume called kwil_pgkwil for the postgres database cluster files.

This also runs with the --autogen flag, creating a new randomly generated chain, and is not intended for production use. However, the service definition may be used as a basis for a customized deployment.

Extensions

Kwil offers an extension system that allows you to extend the functionality of your network (e.g. building network oracles, customizing authentication, running deterministic compute, etc.). To learn more about the types of extensions and how to build them, refer to the extensions directory README.

Contributing

We welcome contributions to kwil-db. To contribute, please read our contributing guidelines.

License

The kwil-db repository (i.e. everything outside of the core directory) is licensed under the Apache License, Version 2.0. See LICENSE for more details.

The kwil Go SDK (i.e. everything inside of the core directory) is licensed under the MIT License. See core/LICENSE.md for more details.

Directories

Path Synopsis
cmd
common/display
Package display provides interfaces and functions to format the command line output and print.
Package display provides interfaces and functions to format the command line output and print.
kwil-admin/nodecfg
Package nodecfg provides functions to assist in the generation of new kwild node configurations.
Package nodecfg provides functions to assist in the generation of new kwild node configurations.
kwild/config
Package config provides types and functions for node configuration loading and generation.
Package config provides types and functions for node configuration loading and generation.
kwild/server
Package server defines the main Kwil server, which includes the blockchain node and the gRPC services that interface with the Kwil dataset engine.
Package server defines the main Kwil server, which includes the blockchain node and the gRPC services that interface with the Kwil dataset engine.
sql
Package sql defines common type required by SQL database implementations and consumers.
Package sql defines common type required by SQL database implementations and consumers.
core module
auth
Package auth contains any known Authenticator extensions that may be selected at build-time for use in kwild.
Package auth contains any known Authenticator extensions that may be selected at build-time for use in kwild.
listeners
package listeners provides the interface and registration for custom event-driven listeners.
package listeners provides the interface and registration for custom event-driven listeners.
listeners/eth_deposits
package ethdeposits implements an listener that listens to Ethereum events and triggers the creation of deposit events in Kwil.
package ethdeposits implements an listener that listens to Ethereum events and triggers the creation of deposit events in Kwil.
precompiles
package actions allows custom actions to be registered with the engine.
package actions allows custom actions to be registered with the engine.
resolutions
package resolutions contains the interface and registration for resolution types.
package resolutions contains the interface and registration for resolution types.
resolutions/credit
package credit implements a credit resolution, allowing accounts to be credited with a given amount.
package credit implements a credit resolution, allowing accounts to be credited with a given amount.
internal
abci/meta
Package meta defines a chain metadata store for the ABCI application.
Package meta defines a chain metadata store for the ABCI application.
engine/sqlanalyzer/attributes
Package attributes analyzes a returned relations attributes, maintaining order.
Package attributes analyzes a returned relations attributes, maintaining order.
engine/sqlanalyzer/clean
Package clean cleans SQL queries.
Package clean cleans SQL queries.
events
package events is used to track events that need to be included in a Kwil block.
package events is used to track events that need to be included in a Kwil block.
events/broadcast
package broadcast contains logic for broadcasting events to the Kwil network
package broadcast contains logic for broadcasting events to the Kwil network
ident
Package ident provides the functions required by kwild for message and transaction signature verification, and address derivation.
Package ident provides the functions required by kwild for message and transaction signature verification, and address derivation.
kv
services/grpc/function/v0
package function/v0 implements a grpc server for the Kwil function service.
package function/v0 implements a grpc server for the Kwil function service.
sql/pg
Package pg defines the primary PostgreSQL-powered DB and Pool types used to support Kwil DB.
Package pg defines the primary PostgreSQL-powered DB and Pool types used to support Kwil DB.
sql/versioning
package versioning provides standard schema versioning for Kwil databases.
package versioning provides standard schema versioning for Kwil databases.
txapp
package tx_router routes transactions to the appropriate module(s)
package tx_router routes transactions to the appropriate module(s)
utils/sync_map
Package syncmap provides a map that is safe for concurrent use.
Package syncmap provides a map that is safe for concurrent use.
parse module
test module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL