Skip to main content

Building Custom Kwil Binaries

In order to use extensions with Kwil, users need to build custom binaries that include the extensions they want to use. This guide will walk you through the process of building a custom Kwil binary with extensions.

Prerequisites​

Before building a custom binary, ensure you have the following installed:

Step 1: Setting up the environment

Start by setting up the repo for building the custom binary. This will be a standard Go repo setup.

Create a new directory for the binary and navigate to it:

mkdir custom-kwil
cd custom-kwil

Initialize a new Go module:

go mod init custom-kwil

Install the Kwil SDK:

go get github.com/kwilteam/kwil-db

Run go mod tidy to ensure all dependencies are installed.

go mod tidy

Step 2: Set up main.go​

Create a new file called main.go in the root of the project directory:

touch main.go

Add the following code to main.go:

main.go
package main

import (
    "fmt"
    "os"

    "github.com/kwilteam/kwil-db/cmd/custom"
)

func main() {
    err := custom.NewCustomCmd(custom.CommonCmdConfig{
        RootCmd:     "my-custom-cmd",
        ProjectName: "My Project Name",
    }).Execute()
    if err != nil {
        fmt.Println(err)
        os.Exit(1)
    }
    os.Exit(0)
}

Step 3: Add a custom extension​

In the same directory as main.go, create a new file called custom_extension.go:

touch custom_extension.go

Add the following code to custom_extension.go. This example uses a custom authenticator extension, however any type of extension can be added in this step using their respective Register function in the init function of the extension file.

tip

Examples on how to implement each type of extensions can be found in their respective sections.

danger

This example is for demonstration purposes only and should not be used in a production environment. For a production-ready Ed25519 authenticator, please refer to the Ed25519 authenticator guide.

custom_extension.go
package main

import (
    "crypto/ed25519"
    "fmt"
    "encoding/hex"

    "github.com/kwilteam/kwil-db/extensions/auth"
)

// init registers the Ed25519Authenticator with the Kwil node
func init() {
    err := auth.RegisterAuthenticator("ed25519_example", Ed25519Authenticator{})
    if err != nil {
        panic(err)
    }
}

type Ed25519Authenticator struct{}

// Verify verifies the signature of a message
func (Ed25519Authenticator) Verify(sender, msg, signature []byte) error {
    if !ed25519.Verify(sender, msg, signature) {
        return fmt.Errorf("signature verification failed")
    }

    return nil
}

// Identifier returns the hex encoding of the public key
func (Ed25519Authenticator) Identifier(sender []byte) (string, error) {
    return hex.EncodeToString(sender), nil
}

Step 4: Build the custom binary​

Build the custom binary. This will compile all the files in the project directory, as well as any that are imported:

go build . -o my-custom-cmd

This will create a binary called my-custom-cmd in the root of the project directory. The binary has 3 subcommands:

  • node: Start a Kwil node, equivalent to a standalone kwild binary.
  • client: A client to interact with the Kwil node, equivalent to a standalone kwil-cli binary.
  • admin: A client for node operators to interact with the Kwil node's admin RPC, equivalent to a standalone kwil-admin binary.

Step 5: Run Postgres​

Before running the custom node, you will have to start Postgres. The Kwil team has provided a default image with the necessary configurations. For more information on how to configure your own Postgres database, please refer to the Postgres setup guide.

docker run -d -p 5432:5432 --name kwil-postgres -e "POSTGRES_HOST_AUTH_METHOD=trust" \
    kwildb/postgres:latest

Step 6: Run the custom my-custom-cmd node binary​

After running Postgres, you can run the custom my-custom-cmd node command. The --autogen flag will automatically generate a new node key, a network genesis file, and a default node configuration:

./my-custom-cmd node --autogen

Conclusion​

In this guide, you built a custom Kwil binary with extensions. You can now use the custom binary to run a Kwil node with your custom extension(s). For more information on how to implement custom extensions, please refer to the respective extension documentation.

Next Steps​

Additional extension types and tutorials found below: