cmd/dynamo-browse
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions

Updated the documentation
Some checks failed
ci / Build (push) Failing after 3m41s
Details
Release / Build (push) Failing after 3m41s
Details
Release / Site (push) Has been skipped
Details
Release / Release (push) Has been skipped
Details

Browse source
This commit is contained in:
Leon Mika 2025-11-15 11:34:07 +11:00
parent 4cb66f52fe
commit b4cee0e2e5
31 changed files with 267 additions and 296 deletions
Download patch file Download diff file Expand all files Collapse all files

4
_site/content/docs/user-guide/_index.md Normal file
View file

@ -0,0 +1,4 @@
---
bookFlatSection: true
weight: 30
---

50
_site/content/docs/user-guide/customising.md Normal file
View file

@ -0,0 +1,50 @@
---
title: Customising Dynamo-Browse
weight: 50
---
# Customising Dynamo-Browse
Some commands can be used to customise Dynamo-Browse, such as modify key bindings.
The effect of these commands will only be applied for the duration of the session: they are currently not
tracked within the workspace file. To keep customisations across relaunches, these commands
can be added to an RC file.
## RC Files
RC files are text files containing commands that will be executed by Dynamo-Browse upon launch.
By default, RC files are located in `$HOME/.config/dynamo-browse/` and have the suffix `.ucl`. For example:
```
$HOME/.config/dynamo-browse/init.ucl
```
Any number of RC files can be present in this directory, and they are executed in lexicographical order.
## Rebinding Keys
The default key bindings of Dynamo-Browse can be changed using the [rebind](/docs/reference/commands#rebind) command. This takes
a binding name corresponding to the particular action to invoke, and the key
to which it should be mapped to.
Putting these commands in the RC file will effectively change the default bindings of Dynamo-Browse.
```
# Rebind T to prompt for a table
rebind "view.prompt-for-table" "T"
# Rebind escape to prompt for a command
rebind "view.prompt-for-command" "esc"
```
At the moment each binding name can only be mapped to a single key. It's also currently not possible
to setup bindings for commands. These may be supported in the future.
A list of available binding names can be found the the [reference](/docs/reference/key-bindings)
(check the "Show binding names" checkbox). Note that some bindings may not have default key bindings.
## Extensions
The RC files are primarily intended for commands that customise Dynamo-Browse in a particular way, but any
command can be entered here, including those for defining new commands or running predefined queries. These
are generally known as extensions, although act as any other RC file located within that directory. More
information on extensions can be found in the [reference](/docs/reference/script-api).

95
_site/content/docs/user-guide/editing-items.md Normal file
View file

@ -0,0 +1,95 @@
---
title: Editing Items
weight: 40
---
# Editing Items
Dynamo-Browse offers some basic facilities for editing items — such as creating items, deleting items,
and modifying their attribute values.
<figure class="screenshot">
<img src="/images/dynamo-browse/modified-items.png" alt="Item indicators">
</figure>
## Marking Items
Most modifications are applied to items that are marked. A marked item is indicated by a grey
background and a bullet indicator (`•`) on the left side of the table.
To mark or unmark the selected item, press <kbd>m</kbd>.
The command `unmark` can be used to clear all marked items.
## Modifying Attributes
Item attributes can be added or modified by using the command `set-attr` or the alias `sa`.
This command can be used to modify the value and type of an attribute of the currently selected items, or
from any marked items.
The format of the command is as follows:
```
:set-attr [<type>] <attributeName>
```
Where type is one of the following (case insensitive):
- `-S`: string
- `-N`: number
- `-BOOL`: boolean
- `-NULL`: null
If the type is not specified, and the attribute exists, then the attribute type will not change.
The type must be specified if this is a new attribute or multiple items have been marked.
After executing the command, Dynamo-Browse will prompt for the value of the new attribute if one is
required.
Modified attributes will only be tracked in memory: they will not be written
to the actual table until it is "putted" (see [Committing Changes](#committing-changes)).
An item that has been modified will be displayed in red and a modified indicator (`M`) will appear
on the left-most column.
## Deleting Attributes
An attribute can be deleted by using the command `del-attr` or the alias `da`. The format of the command
is as follows:
```
:del-attr <attributeName>
```
When executed, the attribute with the name _attributeName_ will be deleted from the selected item, or
from any marked items.
Deleted attributes will only be tracked in memory: they will not be removed from
the actual table until it is "putted" (see [Committing Changes](#committing-changes)).
An item that has been modified will be displayed in red and a modified indicator (`M`) will appear
on the left-most column.
## Adding Items
A new item can be created by typing in the command `new-item`.
When entered, Dynamo-Browse will prompt for the partition and sort key. Once these are entered,
the item will appear in the top pane in green with an asterisk indicator (`*`) on the left left-most column.
Any additional attributes can be set by using `set-attr`.
A new item will only appear in memory: it will not be written
to the actual table until it is "putted" (see [Committing Changes](#committing-changes)).
## Deleting Items
Items can be deleted by marking them and then typing in the command `delete`.
Unlike most of the other modified commands, running `delete` WILL make changes to the table
immediately.
## Committing Changes
New or modified items (but not deleted items) will be kept in memory until they are committed
or "putted" to the table. To put the changes, use the `put` command or `w` alias.
## Backing Out of Changes
Any modified items can be reverted back to what they are in the actual table by rerunning the
current query. This can be done by pressing <kbd>&#8679;R</kbd>.

60
_site/content/docs/user-guide/filtering-querying.md Normal file
View file

@ -0,0 +1,60 @@
---
title: Querying and Filtering Results
weight: 30
---
# Querying and Filtering Results
## Querying
<figure class="screenshot">
<img src="/images/dynamo-browse/query-items.png" alt="Items with query applied">
</figure>
A query or scan over the table can be performed by entering a _Query Expression_.
Query expressions are a built-in expression language which translates to either a DynamoDB query
or scan, depending on the expression.
Query expressions are entered as expressions, with most being of the form `attribute operator value`.
For example, the expression for selecting records where `color` equals `red` is:
```
color = "red"
```
The `color` attribute can either be a partition key, sort key, or a regular attribute. Dynamo Browse
will do it's best to run the query as a DynamoDB query if possible. Usually query expressions of the
form `pk = <something>` or `pk = <something> and sk <comparison> <something>` where `pk` is a partition key,
`sk` is the sort key, and `<comparison>` is one of the [equality](/docs/reference/query-expressions/#equality),
[numerical comparison](/docs/reference/query-expressions/#numerical-comparison), or
[prefix operator](/docs/reference/query-expressions/#prefix-operator), will be executed as queries.
Other expressions will be executed as scans.
Details about the Query Expression language can be found in the
[Query Expressions references](/docs/reference/query-expressions/).
To run a query, press <kbd>?</kbd>, and enter the query expression.
To clear a query, press <kbd>?</kbd>, and press <kbd>Enter</kbd> without entering any value.
While the query is running, a spinner indicating activity will be shown in the status bar. A running
query can be cancelled while this spinner is visible by pressing <kbd>^C</kbd>. You have the option
to view any partial results that have been retrieved at the time.
## Filtering
<figure class="screenshot">
<img src="/images/dynamo-browse/filter-items.png" alt="Items with filter applied">
</figure>
The displayed items of the current result-set can be filtered down to those that contain a specific substring.
To set the filter, press <kbd>/</kbd>, and enter the substring you wish to filter on.
To clear the filter, press <kbd>/</kbd>, and press <kbd>Enter</kbd> without entering any value.
When a filter is set, any item that does not have a top-level attribute containing the substring will be hidden.
Filtering will only consist the items that are in the current result-set. It will not result in a call to the actual
table itself.
Note that filtering is case sensitive.

157
_site/content/docs/user-guide/getting-around.md Normal file
View file

@ -0,0 +1,157 @@
---
title: Getting Around
weight: 20
---
# Getting Around
After selecting a table, Dynamo-Browse will perform a scan and present the results in the default view mode.
<figure class="screenshot">
<img src="/images/dynamo-browse/main-item-view.png" alt="Main item view">
</figure>
This mode consists of three panes:
- The top pane displays the result-set of the last scan or query. The table name is at the top-left.
- The middle pane displays the attributes of the currently selected item, along with their type.
- The bottom pane displays the current query or filter, plus any messages. Prompts for input will
also appear at the bottom.
The result-set is sorted in ascending order based on the value and type of the partition and sort key.
Up to 1,000 rows will be displayed for the current result-set.
Since DynamoDB does not require all items to have the same attribute (unless they are pre-defined), any
attribute not set for a column is indicated with a grey tilde character `~`.
Use the following keys to change the currently selected row, which is highlighted in purple:
- <kbd>&uarr;</kbd>/<kbd>i</kbd>: Move selection up
- <kbd>&darr;</kbd>/<kbd>k</kbd>: Move selection down
- <kbd>PgUp</kbd>/<kbd>&#8679;I</kbd>: Page up
- <kbd>PgDn</kbd>/<kbd>&#8679;K</kbd>: Page down
- <kbd>Home</kbd>/<kbd>0</kbd>: First row
- <kbd>End</kbd>/<kbd>$</kbd>: Last row
The columns of the table
consist of the top-level attributes of the result-set. The partition key, sort key, plus any explicitly defined
attributes will always be displayed from the left margin onwards. The other attributes are determined
from the results of the last scan or query, and may change depending on the result.
The display columns of the table can be scrolled across by using the following keys:
- <kbd>&larr;</kbd>/<kbd>j</kbd>: Scroll to the left
- <kbd>&rarr;</kbd>/<kbd>l</kbd>: Scroll to the right
The attributes of the currently selected item will appear in the middle pane. Both the type and the value of each
attribute will be displayed. Any nested attributes will be indented, and will below their parent item. A value
displayed in grey does not represent the actual value of the item, but indicates some meta-information about the item,
such as the length.
## The Back-stack
Changes to the view of Dynamo-Browse will be maintained in back-stack, similar to how a
web-browse keeps track of the webpages you've visited. This stack will record the
currently viewed table, filter, or query, allowing you to "go back" to a previous view
by pressing <kbd>Backspace</kbd>. Pressing <kbd>\\</kbd> will allow you to go forward through the stack.
The back-stack is preserved in the workspace file, and can be restored by launching Dynamo-Browse with the `-w`
switch. Launching Dynamo-Browse with a workspace that has a non-empty stack will restore the last viewed
table, filter, or query from the session that was previously using the workspace.
{{<hint info>}}
**Note:** the back-stack does not preserve the actual items in the workspace. Going backwards or forwards
through the back-stack will execute any queries or filters against the actual table itself.
{{</hint>}}
## Adjusting The Layout
The horizontal size of the item table and currently selected item pane can be changed to one of the
following layout configurations:
- Item view taking up 14 rows on the bottom with the table pane taking up the rest of the vertical space (the default)
- Item view and table view taking up half of the available space
- Table view taking up 7 rows on the top with the item view taking up the rest of the vertical space
- Table view hidden
- Item view hidden
Pressing <kbd>w</kbd> will cycle forward though these layouts. For example, while in the
default layout, pressing <kbd>w</kbd> will switch to the second layout, where both the table view take up half the
screen. Pressing <kbd>&#8679;W</kbd> will cycle through the layouts in the reverse order.
## Adjusting The Displayed Columns
The columns of the result-set can be adjusted by opening up the _Fields Popup_. This popup can be opened by pressing <kbd>f</kbd>.
<figure class="screenshot">
<img src="/images/dynamo-browse/fields-popup.png" alt="dynamo-browse">
</figure>
While this popup is opened, the following changes can be applied to the displayed columns of the main table:
- Columns can be hidden
- The order columns appear in the main table can be rearranged
- New columns can be added
The popup will display the list of columns of the main result-set table. Pressing <kbd>&uarr;</kbd>/<kbd>i</kbd>
or <kbd>&darr;</kbd>/<kbd>k</kbd> will move the selection indicator to the column to apply the operation. Pressing
<kbd>&larr;</kbd>/<kbd>j</kbd> or <kbd>&rarr;</kbd>/<kbd>l</kbd> will scroll the main table left or right so that any
operations can be previewed.
To reset the columns to the top-level fields of the current result set, press <kbd>&#8679;R</kbd>.
To close the popup, press <kbd>Escape</kbd>.
### Showing And Hiding Columns
In the Fields Popup, each row has a symbol indicating whether the row is currently visible (`.`) or hidden (`✕`). Pressing
<kbd>Space</kbd> will toggle whether the currently selected column is shown or hidden.
### Re-arranging The Order Of Columns
The currently selected row can be moved up or down the table. This will move the corresponding column in the main table either
left or right.
Press <kbd>&#8679;I</kbd> to the selected row up, which will move the corresponding column left.
Press <kbd>&#8679;K</kbd> to the selected row down, which will move the corresponding column right.
### Adding And Removing Columns
New columns can be added in the table. The value of these columns will be determined by the result of a query expression,
and can be used to expose fields that are not at the top level.
Any nested fields of maps or lists will not be included as a column by default. Consider, for example, a table of books
with authors structured as so:
```
{
"book": {"S": "The Lord Of The Rings"},
"author": {"M": {
"firstName": {"S": "John"},
"middleName": {"S": "Ronald Reuel"},
"lastName": {"S": "Tolkien"},
}}
}
```
If you wanted to show the the author's first and last name in the main table, rather than just see the description `(3 items)`, you
can add a new column with an expression selecting the fields of the author map. The expressions that can be used here
are as follows:
- First name: `author.firstName`
- Last name: `author.lastName`
This can be extended to expressions that perform comparisons or operations. For example, the expression `author.firstName ^= "J"` can be
use in a new column to display `True` for any first name that begins with a J.
To add a new column, press <kbd>a</kbd> while the Fields Popup is visible. You'll be prompted to enter a query expression,
which will be evaluated over each row within the result-set when displaying the table.
Any column, that was either retrieved from the result-set or added by the user, can be deleted by selecting the column
within the Fields Popup and pressing <kbd>d</kbd>.
## Entering Commands
Commands can be entered by pressing <kbd>:</kbd> and entering the command, with any arguments, at the prompt.
The list of available commands can be found within the [reference section](/docs/reference/#commands).

66
_site/content/docs/user-guide/launching.md Normal file
View file

@ -0,0 +1,66 @@
---
title: Launching and Quitting
weight: 10
---
# Launching and Quitting
To launch Dynamo-Browse, run the following command at the terminal:
```
dynamo-browse
```
This will use your current AWS configuration and region, which can be changed by setting
the relevant `AWS_` environment variables.
To connect to a local instance of DynamoDB, such as one
running in a Docker container, use the `--local` flag. This takes as the argument the hostname
and endpoint of the local DynamoDB server. The hostname can be omitted, and will default to `localhost`:
```
dynamo-browse --local :8080
```
## Selecting a Table
Upon launch, Dynamo-Browse will present a list of all the tables within the region:
<figure class="screenshot">
<img src="/images/dynamo-browse/table-selection.png" alt="Table selection">
</figure>
Select the table to view by pressing <kbd>Enter</kbd>. Use the following keys to navigate
the items within the list:
- <kbd>&uarr;</kbd>/<kbd>i</kbd>: Move selection up
- <kbd>&darr;</kbd>/<kbd>k</kbd>: Move selection down
Once the table is selected, the table will be scanned and Dynamo-Browse will be presented in
[View Mode](#view-mode). Another table can be selected from within view mode using the `:table` command.
Dynamo-Browse can also be launched directly in view mode by specifying a table using the `-t` flag:
```
dynamo-browse -t user-accounts
```
## Selecting a Workspace
Dynamo-Browse tracks session state, such as the back-stack, in a workspace file. By default the workspace
file will be a new file created within the temporary directory, but a specific workspace filename can be
specified by using the `-w` flag:
```
dynamo-browse -w my-workspace.ws
```
If the workspace filename references an existing file, Dynamo-Browse will restore the workspace and use it for the duration of
the session. If the workspace filename references a non-existing file, Dynamo-Browse will initialise a new workspace
using the specified filename.
Only one running instance of Dynamo-Browse can use a single workspace file at any one time.
## Quitting
To quit dynamodb-browse, enter the command `q` by pressing <kbd>:</kbd>, then typing <kbd>q</kbd> <kbd>Enter</kbd>.
The keystroke <kbd>Ctrl+C</kbd> can also be used to quit.