dal/README.md

131 lines
5.7 KiB
Markdown
Raw Normal View History

2024-08-21 20:28:41 +00:00
# DAL
2024-08-21 20:28:41 +00:00
**Data Access Layer**
2024-08-22 09:17:28 +00:00
2024-08-21 20:28:41 +00:00
DAL is a proxy layer for SQL databases with a MongoDB inspired query interface.
2024-08-22 09:17:28 +00:00
It can be used as a Go or NodeJS package (requires compiler).
It is modular and allows to create your own proxy and apply custom middlewares.
2024-08-21 20:39:02 +00:00
_Notes:_
2024-08-21 20:40:53 +00:00
- This project is still in **early alpha**. You need to build it yourself and use at your own risk.
2024-08-21 20:39:02 +00:00
- At the time only SQLite is implemented, however, other drivers might work.
_Use cases:_
2024-08-21 20:28:41 +00:00
- For IOT networks when MySQL/PG are too heavy.
- If you need a layer between your application and the database (i.e. for caching).
2024-08-22 07:30:37 +00:00
- If you want a MongoDB-like query interface for your SQL db.
- When you need a SQLite proxy (useful to share datasets with services)
2024-08-21 20:28:41 +00:00
## Usage
### Server
The most efficient way to use DAL is to run the server as a standalone service.
Build:
```bash
go build -o server
```
Run:
```bash
export SQLITE_DIRECTORY=/opt/data
./server
2024/08/21 22:01:54 Starting server on port 8118
2024/08/21 22:01:54 Using directory: /opt/data
```
### Client
Install:
```bash
pnpm add git+git@github.com:nesterow/dal.git
```
### Query Interface
2024-08-21 20:39:02 +00:00
| Method | Description | SQL |
| -------------------------------------------- | -------------------------------------- | ----------------------------------------------- |
| `In(table: string)` | Select table | `SELECT * FROM table` |
| `Find(filter: object)` | Filter rows | `SELECT * FROM table WHERE filter` |
| `Fields(fields: string[])` | Select fields | `SELECT fields, FROM table` |
| `Sort(sort)` | Sort rows | `SELECT * FROM table ORDER BY sort` |
| `Limit(limit: number)` | Limit rows | `SELECT * FROM table LIMIT limit` |
| `Offset(offset: number)` | Offset rows | `SELECT * FROM table OFFSET offset` |
| `Join({ $for: "t_2", $do: { "t.a": "b" } })` | Join tables | `SELECT * FROM table t JOIN t_2 ON t.a = b` |
| `Insert({name: "J"}, {name: "B"})` | Insert row | `INSERT INTO table (name,) VALUES ('J', 'B')` |
| `Set({name: "Julian"})` | Update row (Find(filter).Set({})) | `UPDATE table SET name = 'Julian' WHERE filter` |
| `Delete()` | Delete row (Find(filter).Delete()) | `DELETE FROM table WHERE filter` |
| `As(DTO)` | Map rows to a DTO | `SELECT * FROM table` |
| `Rows()` | Get rows iterator | `SELECT * FROM table` |
| `Exec()` | Execute query (update, insert, delete) | `SQL RESULT` |
| `Query()` | Query database | DTO array |
| `Tx()` | Run in trasaction | |
2024-08-21 20:28:41 +00:00
### Filters
2024-08-21 20:39:02 +00:00
| Filter | Description | SQL |
| ----------------------------- | ---------------------- | ------------------------------ |
| `{id: 1, num: 2}` | Equals, default filter | `WHERE id = 1 AND num = 2` |
| `{id: { $eq: 1 }}` | Equals, explicit | `WHERE id = 1` |
| `{id: { $gt: 1 }}` | Greater than | `WHERE id > 1` |
| `{id: { $gte: 1 }}` | Greater than or equal | `WHERE id >= 1` |
| `{id: { $lt: 1 }}` | Less than | `WHERE id < 1` |
| `{id: { $lte: 1 }}` | Less than or equal | `WHERE id <= 1` |
| `{id: { $ne: 1 }}` | Not equal | `WHERE id != 1` |
| `{id: { $in: [1, 2] }}` | In | `WHERE id IN (1, 2)` |
| `{id: { $nin: [1, 2] }}` | Not in | `WHERE id NOT IN (1, 2)` |
| `{id: { $like: "a" }}` | Like | `WHERE id LIKE '%a%'` |
| `{id: { $nlike: "a" }}` | Not like | `WHERE id NOT LIKE '%a%'` |
| `{id: { $between: [1, 2] }}` | Between | `WHERE id BETWEEN 1 AND 2` |
| `{id: { $nbetween: [1, 2] }}` | Not between | `WHERE id NOT BETWEEN 1 AND 2` |
| `{id: { $glob: "\*son" }}` | Glob | `WHERE id GLOB '*son'` |
2024-08-21 20:28:41 +00:00
### Example
```typescript
2024-08-21 20:28:41 +00:00
import { DAL } from "@nesterow/dal";
class UserDTO {
id: number = 0;
name: string = "";
data: string = "";
age: number | undefined;
}
const db = new DAL({
database: "test.sqlite",
url: "http://localhost:8111",
});
2024-08-21 20:48:50 +00:00
// SELECT * FROM test t WHERE name GLOB '*son' AND age >= 18
2024-08-21 20:28:41 +00:00
const rows = db
.In("test t")
.Find({
2024-08-21 20:28:41 +00:00
name: { $glob: "*son" },
age: { $gte: 18 },
2024-08-21 20:48:50 +00:00
})
2024-08-21 20:28:41 +00:00
.As(UserDTO) // Map every row to DTO
2024-08-21 20:48:50 +00:00
.Rows();
2024-08-21 20:28:41 +00:00
for await (const row of rows) {
console.log(row); // Jason, Jackson
}
```
2024-08-22 07:30:37 +00:00
## Internals
The client uses a light builder and messagepack over http. It is relatively easy to implement a client in any language see [the docs](./doc/)
## License
While in alpha stage the project is free for research purposes.
Later it will be released under MIT-like license with AI/dataset exclusion terms.