Ridge DB Quickstart

This guide starts the repository ridged service, connects through pgwire, and creates a small relational table. Use the embedded API instead when the database should live inside one seed process.

Build and check the service

From the seed repository:

./seed/seed check grove/apps/ridge/ridged
./seed/seed build grove/apps/ridge/ridged -o /tmp/ridged --release
/tmp/ridged --check

Start a loopback service with an explicit data prefix:

/tmp/ridged --data=/absolute/path/to/ridge/main

The default pgwire endpoint is 127.0.0.1:7898, database ridge, user ridge. Keep it on loopback. Use the packaged service definitions for a persistent macOS or Linux installation.

Connect

psql -X -h 127.0.0.1 -p 7898 -U ridge -d ridge

If the operator enabled password authentication, provide the configured credential through the client or a private password file. Never put a password in a command committed to source control.

Create and inspect data

CREATE TABLE task_items (
    task_id BIGINT PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY,
    title TEXT NOT NULL,
    done BOOLEAN NOT NULL DEFAULT false
);

INSERT INTO task_items (title) VALUES ('read Ridge documentation');
SELECT task_id, title, done FROM task_items;

SHOW DATABASES;
SHOW SCHEMAS;
SHOW TABLES;
DESCRIBE task_items;
SHOW INDEXES FROM task_items;
SHOW CONSTRAINTS FROM task_items;

Keywords are case-insensitive. Unquoted identifiers are lowercase. The MySQL-like introspection commands are Ridge aliases; their result columns contain Ridge-native typed metadata.

Embed in a seed application

The same hello-world fits inside one seed process with the embedded API. The base directory must exist before ridge_open; create it once:

mkdir -p data/app

use "ridge"
use "io"

fn main() -> result<i64, ridge_error> {
    let mut db = ridge_open("data/app", 4096 as usize)?
    db.create_table("items", 1024 as usize)?

    let payload = bytes.from("hello").or_abort()
    db.insert("items", 1, payload.view())?

    let found = db.get("items", 1)?
    match found {
        some(row) => { let _w = stdout_write_format(f"row={row.id}") }
        none => { let _w = stdout_write("not found".bytes()) }
    }
    result.ok(0)
}

Build and run it from the seed repository:

./seed/seed check path/to/application
./seed/seed run path/to/application   # prints row=1

The relational and SQL packages provide generation-2 typed multi-column rows; choose one coherent data path instead of mixing legacy row and relational visibility assumptions.

Open Ridge Admin

The packaged Ridge Admin installation includes ridged and a built-in Local Ridge profile for 127.0.0.1:7898.

ridge-admin

Open the one-time fragment URL printed by the process. The browser exchanges the fragment for a local authenticated session and removes it from history.

Next steps