Databases
A database is a folder in your repository that contains a schema and a collection of records. Each record is a markdown document with structured properties defined by the schema.
What databases aren't
Lightworks databases are not a general-purpose data store like SQL. There are no ACID transactions, no query planner, and no indexes beyond the search index built by the GitHub Action. Records are markdown files on disk — reads go through the GitHub API and writes produce git commits.
They work best for structured, human-authored content that benefits from version history, review workflows, and audit trails — requirements, risks, test cases, change records, and similar QMS artifacts.
File structure
requirements/
├── _schema.json # defines properties and views
├── req-001/
│ └── index.md # a record
├── req-002/
│ └── index.md # a record
The _schema.json file defines the property types, default views, and view configuration for the database. Records are sub-folders, each with their own index.md containing frontmatter properties and a markdown body.
Property types
| Type | Description |
|---|---|
text | Plain string value |
number | Numeric value — supports number, currency, and percent formats |
select | Single choice from a defined list of options |
multi-select | Multiple choices with color coding |
status | Select with built-in categories: to-do, in-progress, complete |
date | ISO 8601 date, with optional time component |
checkbox | Boolean true/false |
url | Web or relative URL |
person | Single GitHub collaborator |
people | Multiple GitHub collaborators |
relation | Link to a record in another database |
esign | Electronic signature with login, name, and timestamp |
linear | Reference to a Linear issue — requires the Linear connection |
jira | Reference to a Jira issue — requires the Jira connection |
Views
Each database supports multiple named views. Switch between them using the view switcher in the toolbar. Views are stored in the schema and persist across sessions.
| View | Description |
|---|---|
| Table | Columnar grid with sortable columns and inline filtering |
| List | Compact list with inline property display |
| Board | Kanban columns grouped by a status or select field |
| Gallery | Card grid — cover image from the first URL property |
| Feed | Chronological feed |
Creating a record
Open a database and click New to create a record. A new folder is created with an index.md pre-populated with default property values from the schema.
Sorting and filtering
In Table view, click a column header to sort ascending or descending. Use the filter input to search by any column value. Column order and visibility can be configured per view.
Board grouping
Board view groups records by a status or select property. Lightworks auto-detects the best grouping field from the schema. Drag cards between columns to update that property — the change is committed to the record's frontmatter.
Querying and accessing data
For deeper exploration, use the Console to run LQL queries across your databases — filter, join, and trace relationships, or compare snapshots over time with temporal queries.
To read and write records programmatically from GitHub Actions or external tooling, see the Developers reference for the REST API.