db

A simple tool to manage your data
npm

[!DANGER] The project is in alpha phase, please don't use in production

Installation

npm install -g @sidekick-coder/db

Usage

Create db.config.yml

name: tasks
provider:
  name: file
  config:
    format: markdown
    path: ./tasks-folder # path to the folder with markdown files

db list --where "status=done" # list 

db find --where "id=01" # find single item

db create --data "title=New task&status=todo&body=This is a new task" # create new item

db update --data "status=done" --where "id=01" # update item

db destroy --where "id=01" # delete item

Providers

• File
• Folder
• Notion
• Vault

Database

A database in the context of this lib refers to any data that can be converted to an array of objects.

Examples can be:

• list of plain text files with key value pairs
• list of markdown file with frontmatter
• list of json files
• list of folders
• list of rows from a SQL Table (Postgres, MySQL, etc)
• etc...

Config file

The config file is a yaml file that defines the one or more databases definitions.

The cli will always look for a the db.config.yml file in the current directory, unless you pass a different path as a flag.

db -f "path/to/config.yml"

Single Database config sample

name: tasks
provider:
    name: file
    config:
        path: data
        format: markdown
        id_strategy: increment
view:
    default: default
    sources:
        dirs: views
        files: [./views/default.yml]
        items:
            - name: archived
              where:
                  archived: false

Multiple Databases config sample

databases:
    default: tasks
    sources:
        files: ["content/tasks/db.config.yml"]
        patterns: ["content/*/db.config.yml"]
        items:
            - name: tags
              provider:
                  name: file
                  config:
                      path: ./content/tags/data

            - name: code-snippets
              provider:
                  name: file
                  config:
                      path: content/code-snippets/data

Select the databse with the --database flag

db list --database tags

# or short version 

db list --db tags

List

List items in the database

Options

| Option | Type | Required | Description | | --- | --- | --- | --- | | where | object | false | Where statments to filter data see filters | | limit | number | false | Limit the number of items if provider supports | | page | number | false | Page number if provider supports number pagination | | cursor | string | false | Cursor to start from if provider supports cursor pagination | | include | array | false | Include properties | | exclude | array | false | Exclude properties | | sort-by | string | false | Sort by property | | sort-desc | boolean | false | Sort descending |

Examples

db list

db list --where "status=done"

Find

Find a single item in the database

Options

| Option | Type | Required | Description | | --- | --- | --- | --- | | where | object | false | Where statments to filter data see filters | | include | array | false | Include properties | | exclude | array | false | Exclude properties |

Examples

db find

db find --where "status=done"

Create

Create a new item in the database

Options

| Option | Type | Required | Description | | --- | --- | --- | --- | | data | object | true | Data to be updated |

Examples

db create --data "title=New task&status=todo&body=This is a new task"

db create --data "new-task.yml"

db create --data '{"title": "New task", "status": "todo", "body": "This is a new task"}'

Update

Update an item in the database

Options

| Option | Type | Required | Description | | --- | --- | --- | --- | | data | object | true | Data to be updated | | where | object | false | Where statments to filter data see filters |

[!WARNING] if where is not provided, all items will be updated

Examples

db update --data "status=done" --where "id=01"

db update --data "update-task.yml" --where "id=01"

db update --data '{"status": "done"}' --where "id=01"

Destroy

Delete an item in the database

Options

| Option | Type | Required | Description | | --- | --- | --- | --- | | where | object | false | Where statments to filter data see filters |

[!WARNING] if where is not provided, all items will be deleted

Examples

db destroy --where "id=01"

db destroy --where "delete-task.yml"

db destroy --where '{"id": "01"}'

Variables

Some cli flags accept a special format that can help use complex data structures, similar to ansible variables.

key value

simple key value pairs.

db list --where "path=data" 

load from file

You can load the value from a file by adding the extension to the value

Accepted formats are yml, yaml, json

db list --where "query.yml" 

json

You can pass a json string directly

db list --where '{"path": "data"}'

Views

Views are predefined options to filter, sort and format data

# only query filter in query
include: [id, title, status]

# exclude properties
exclude: [body]

# sort by
sort-by: id
sort-desc: true

# where statments
where: 
    status: done

render: console # render to use
render_options:
    columns:
        - label: ID
          value: id
          width: 3 # 3% terminal width

        - label: Status
          value: status
          width: 10 # 10% terminal width

        - label: Project
          value: project
          width: 10 # 10% terminal width

        - label: Title
          value: title
          # auto width, fill the rest of the terminal width

# load by name
db list --view "done-tasks"

# load by file
db list --view "done-tasks.yml"

Programatic usage

You can use the library in your own javascripts projects too!

Install

npm install @sidekick-coder/db

createDatabase

import { createDatabase } from '@sidekick-coder/db/database'

const definition = {
    name: 'tasks',
    provider: {
        name: 'file',
        config: {
            path: 'data', // absolute path 
            format: 'markdown', 
            id_strategy: 'increment' 
        }
    },
}

const options = {
    root: 'C:\\Users' // optional, root path to resolve relative paths
}

const db = createDatabase(definition, options)

const items = await db.list()

console.log(items)

// also access provider custom methods 
const files = await db.provider.findMetadata()

console.log(files)

createDatabaseFromConfig

import { resolve } from '@sidekick-coder/db/config'
import { createDatabaseFromConfig } from '@sidekick-coder/db/database'

const config = resolve('path/to/db.config.yml') // must be absolute

const db = createDatabaseFromConfig(config, 'database-name')

const items = await db.list() 

console.log(items)

createDatabaseFromPath

import { createDatabaseFromPath } from '@sidekick-coder/db/database'

const db = createDatabaseFromPath('path/to/data/db.config.yml', 'database-name')

const items = await db.list()

console.log(items)