Quick start - WitDatabase

This walks the whole application once. Nothing here needs an existing database.

1. Run it

Download the build for your platform and run it. Windows has an installer and a zip, macOS a zip, Linux a .deb and a zip, each in two sizes depending on whether the .NET runtime travels with it. There is nothing to install alongside it and nothing to register; the engine is inside the application.

Releases are signed: Authenticode on Windows, Developer ID with notarization on macOS, and a GPG-signed SHA256SUMS on Linux.

The welcome screen: recent databases, Create and Open.

From source:

bash

dotnet run --project Tools/OutWit.Database.Studio/OutWit.Database.Studio.csproj

2. Create a database

Ctrl+N.

Create dialog: name and location, the three storage choices, encryption off.

Three storage choices, and the first is the one you want: a single file for the B+Tree store, a folder for LSM, or in memory for something you are only trying out. See storage engines before choosing anything but the first.

Leave encryption off for now.

3. Give the connection a colour

Connection properties: display name, label, colour picker.

Every tab belonging to this connection will be tinted with the colour you pick. With a real database and a scratch copy open at once, the tab strip is what tells you which one your DELETE is about to run against.

Pick something loud for anything you would be unhappy to damage.

4. Make a table

Ctrl+T opens a query tab. Note the key: Ctrl+N creates a database, and the query tab is Ctrl+T.

sql

CREATE TABLE Customers (
    Id      BIGINT PRIMARY KEY AUTOINCREMENT,
    Name    VARCHAR(100) NOT NULL,
    Email   VARCHAR(255) NOT NULL UNIQUE,
    Joined  DATETIME NOT NULL
);

INSERT INTO Customers (Name, Email, Joined) VALUES
    ('Ada Lovelace',   'ada@example.com',   NOW()),
    ('Alan Turing',    'alan@example.com',  NOW()),
    ('Grace Hopper',   'grace@example.com', NOW());

Ctrl+Shift+F5 runs the whole script.

The query tab after running the script. The Messages panel shows a line per statement with what it did and how long it took.

The Messages panel has a line for each statement rather than one line for the script, so a script that fails partway tells you how far it got.

5. Look at the rows

Press Ctrl+R to refresh the tree, then find Customers and double-click it.

The Customers table open in a table editor tab, three rows, the row count in the footer.

Double-click opens the data, not the structure. The structure is on F4, since looking at data is what people open a database tool to do.

6. Edit a row

Click a cell, type, press Enter.

A cell edited, the row marked as changed in the gutter, the hint bar showing Ctrl+S to apply and Esc to discard.

Nothing has been written yet. Changes accumulate and Ctrl+S applies the whole set as one transaction, so either all of it lands or none of it does. Esc discards, Delete marks a row for removal.

7. Ask something

Back in the query tab:

sql

SELECT Name, Email FROM Customers WHERE Name LIKE 'A%' ORDER BY Joined;

Put the cursor in the statement and press F5, which runs the statement under the cursor and nothing else. That is the key to use while writing: a tab can hold a dozen half-finished statements and you can still try the one you are on.

The Result panel with two rows, the row count and elapsed time in the footer bar.

8. See how it will run

Explain on the toolbar, or EXPLAIN in front of the statement.

The Plan panel for the query, with the note that the plan is built without running the query and that this engine reports no row counts or costs.

The plan is built without running the query. This engine reports no row counts and no costs, so what the plan tells you is which access path was chosen, which is the question behind most queries that are slower than expected.

9. Export the result

Right-click the grid, Export Results.

The export dialog: format CSV, JSON or SQL, and three scopes with their row counts.

Three scopes, each carrying its count: what you selected, what is on the page, or everything. It starts on what you actually have, because starting on "everything" is how an export of one row becomes an export of four million.

Opening a database somebody sent you

Ctrl+O. Studio reads the file before it opens it and says what it found, from the header, which is plaintext even when the data is not: the storage engine, the size, and whether the database was made with MVCC. That happens without a password and without opening anything, so it is the fastest way to find out what a file actually is.

The open dialog with a path typed and the line under it reporting what was found in the file.

Every refusal carries its own reason: a file that is not a database, a wrong password, a file another process is holding.

A database encrypted before 13.1.0 is refused by the engine, and Studio is the tool that converts one. It recognises that refusal, explains it, and offers a box reading "Open the old encryption format". Tick it and press Connect to get the data; a notification then says the conversion is one password change away, which is on the Database tab. Once the password has been changed the file is in the current format and the box is not needed again.

10. Find your way around

Ctrl+K opens the command palette.

The command palette open, showing commands and objects together, each object labelled with its database.

It finds commands and objects together, across every open database. Once it is in your fingers it is faster than the tree for most of what you would use the tree for.

Where to go next

Explorer, the tree in full
Query editor, completion, error underlining, history
Data and editing, paging and conflicts
Settings and shortcuts, the whole keyboard map