Getting Started

Install PowDB, create a table, insert data, query it, and run in server mode. Takes about 10 minutes.

1Install

The easiest way to install PowDB is from crates.io:

cargo install powdb-cli
cargo install powdb-server

Or build from source (requires Rust 1.80+; install from rustup.rs if needed):

git clone https://github.com/zvndev/powdb.git
cd powdb
cargo build --release

Check that installation worked:

powdb-cli --version

2Start the REPL

Launch the interactive PowQL shell:

powdb-cli
# or from source:
cargo run --release -p powdb-cli

You should see:

Data is stored in ./powdb_data/ by default. Change it with --data-dir:

powdb-cli --data-dir ./my_project_data

3Create a Table

PowDB uses the type keyword to define tables. Fields prefixed with required cannot be null.

powql> type User { required name: str, required email: str, age: int }

No CREATE TABLE, no column types in parentheses. Fields have a name and a type, separated by a colon.

Supported types: str, int, float, bool, datetime, uuid, bytes.

4Insert Data

Insert rows with the insert keyword. Fields are assigned with :=.

powql> insert User { name := "Alice", email := "alice@example.com", age := 30 }

Add a few more people:

powql> insert User { name := "Bob", email := "bob@example.com", age := 25 }
powql> insert User { name := "Charlie", email := "charlie@example.com", age := 35 }
powql> insert User { name := "Diana", email := "diana@example.com", age := 28 }
powql> insert User { name := "Eve", email := "eve@example.com", age := 22 }
powql> insert User { name := "Frank", email := "frank@example.com", age := 40 }

Fields without required can be omitted -- they default to null:

powql> insert User { name := "Grace", email := "grace@example.com" }

5Query Basics

Select all rows

Just type the table name:

powql> User

Filter rows

Use filter with a condition. Fields are referenced with a dot prefix:

powql> User filter .age > 25

Project specific fields

Use { } braces to select which fields to return:

powql> User filter .age > 25 { .name, .age }

6Sorting and Limiting

PowQL operations chain left to right in a pipeline. Add order and limit:

powql> User order .age desc limit 3 { .name, .age }

7Aggregations

PowQL wraps aggregate functions around the query pipeline.

powql> count(User)
7

powql> count(User filter .age > 25)
4

powql> avg(User { .age })
30

powql> sum(User filter .age > 25 { .age })
133

Other aggregate functions: min(), max().

8Updates

Use update after an optional filter to modify rows:

powql> User filter .name = "Alice" update { age := 31 }

Verify it worked:

powql> User filter .name = "Alice" { .name, .age }

You can use expressions that reference the current row value:

powql> User filter .name = "Bob" update { age := .age + 1 }

9Create an Index

Indexes speed up lookups on frequently queried columns:

powql> alter User add index .email

Indexed columns are used automatically for point lookups and range scans -- no query hints needed.

10Delete

Use delete after a filter to remove matching rows:

powql> User filter .age < 25 delete

To delete all rows in a table: User delete

11Server Mode

For multi-client access, run PowDB as a server.

Start the server

powdb-server --port 5433 --data-dir ./powdb_data

Connect from a client

powdb-cli --remote localhost:5433

From here, the same PowQL statements work as embedded mode.

TypeScript client

import { Client } from "@zvndev/powdb-client";

const client = await Client.connect({ host: "localhost", port: 5433 });
const result = await client.query("User filter .age > 25 { .name, .age }");
if (result.kind === "rows") console.table(result.rows);

Password authentication

# Start the server with a password
POWDB_PASSWORD=mysecret powdb-server

# Connect with the password
powdb-cli --remote localhost:5433 --password mysecret

What's Next

This tutorial covered tables, inserts, queries, aggregates, updates, indexes, deletes, and server mode. PowDB supports much more, including joins, group by, subqueries, materialized views, window functions, and set operations.

See the full language reference: PowQL Reference