Moduletrace/datasquirel-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation content

Browse Source
This commit is contained in:
tben
2026-03-15 05:32:05 +01:00
parent 7d10f030f3
commit c0b92596ec
30 changed files with 1840 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
pages/database-reference/data-types/index.mdx
+65
View File
@@ -0,0 +1,65 @@
---
title: Data Types | Datasquirel docs
description: SQL data types supported by Datasquirel
page_title: Data Types
page_description: All SQL data types available for table fields in Datasquirel.
---
## Overview
Every field in a Datasquirel table has a **data type** that defines what kind of values the column can store. Datasquirel is built on MariaDB, so all standard MariaDB column types are supported.
Choosing the right data type matters for:
- **Storage efficiency** — smaller types use less disk space
- **Query performance** — properly typed columns are faster to index and compare
- **Data integrity** — the database enforces type constraints automatically
## Text Types
| Type | Description |
|------|-------------|
| `VARCHAR(n)` | Variable-length string up to `n` characters. Use for short text like names, slugs, email addresses. Maximum `n` is 65,535. |
| `TEXT` | Unlimited-length text. Use for longer content like descriptions or comments. |
| `LONGTEXT` | Very large text (up to 4 GB). Use for HTML, Markdown, or JSON stored as a string. |
| `CHAR(n)` | Fixed-length string of exactly `n` characters. Padded with spaces if shorter. |
| `ENUM(...)` | A value from a predefined list (e.g. `ENUM('draft', 'published', 'archived')`). |
## Numeric Types
| Type | Description |
|------|-------------|
| `INT` | 32-bit signed integer. Range: –2,147,483,648 to 2,147,483,647. |
| `BIGINT` | 64-bit signed integer. Use for IDs that may exceed 2 billion or for large counts. |
| `TINYINT` | 8-bit integer. Range: –128 to 127. Commonly used for boolean-like flags. |
| `SMALLINT` | 16-bit integer. Range: –32,768 to 32,767. |
| `FLOAT` | Single-precision floating-point number. |
| `DOUBLE` | Double-precision floating-point number. |
| `DECIMAL(p, s)` | Exact decimal with `p` total digits and `s` decimal places. Use for money values. |
## Date and Time Types
| Type | Description |
|------|-------------|
| `DATETIME` | A date and time value (e.g. `2024-03-15 14:30:00`). |
| `DATE` | A date without time (e.g. `2024-03-15`). |
| `TIME` | A time without date (e.g. `14:30:00`). |
| `TIMESTAMP` | A Unix timestamp. Automatically updates to the current time on row modification when configured. |
## Boolean
MariaDB does not have a native BOOLEAN type. Datasquirel uses `TINYINT(1)` for boolean fields — `1` for true, `0` for false.
## Structured Data
| Type | Description |
|------|-------------|
| `JSON` | Native JSON column. MariaDB validates and stores the value as structured JSON. |
| `LONGTEXT` | Store JSON, Markdown, or HTML as plain text when native JSON validation is not needed. |
<div className="w-full grid grid-cols-1 gap-4 items-stretch">
<DocsCard
title="VARCHAR"
description="Learn more about VARCHAR and when to use it."
href="/docs/database-reference/data-types/varchar"
/>
</div>
pages/database-reference/data-types/varchar/index.mdx
+50
View File
@@ -0,0 +1,50 @@
---
title: VARCHAR | Datasquirel docs
description: Learn about the VARCHAR data type in Datasquirel
page_title: VARCHAR
page_description: Store variable-length text strings with VARCHAR columns in Datasquirel.
---
## Overview
`VARCHAR(n)` stores variable-length strings up to `n` characters. It is the most commonly used text type for short strings like names, email addresses, slugs, and status values.
## Syntax
```sql
VARCHAR(255)
```
The number in parentheses is the maximum length in characters. Common values are:
- `VARCHAR(100)` — short names, slugs, categories
- `VARCHAR(255)` — email addresses, URLs, titles
- `VARCHAR(1000)` — longer descriptions (though TEXT is often more appropriate)
The maximum allowed length is **65,535** characters, though in practice anything over a few hundred characters is better stored as `TEXT`.
## When to Use VARCHAR
Use `VARCHAR` when:
- The value is a short string with a predictable maximum length
- You plan to index the column (VARCHAR columns are faster to index than TEXT)
- The value is used in `WHERE` clauses, `ORDER BY`, or `JOIN` conditions
Use `TEXT` instead when:
- The value can be arbitrarily long (descriptions, comments, content)
- You do not need to index the full value
## In Datasquirel
When adding a field to a table, select **VARCHAR** as the data type and enter the maximum length. If no length is specified, Datasquirel defaults to `VARCHAR(255)`.
<DocsImg
alt="New Field"
srcLight="/images/screenshots/new-field-light.webp"
srcDark="/images/screenshots/new-field-dark.webp"
/>
## Notes
- VARCHAR is case-insensitive in comparisons by default (controlled by the column collation).
- Leading and trailing spaces are preserved in VARCHAR values.
- An empty string `""` is a valid VARCHAR value and is distinct from NULL.
pages/database-reference/querying-data/delete/index.mdx
+87
View File
@@ -0,0 +1,87 @@
---
title: DELETE | Datasquirel docs
description: Remove rows from a table using DELETE statements in Datasquirel
page_title: DELETE
page_description: Remove rows from your tables using SQL DELETE statements.
---
## Overview
`DELETE FROM` removes rows from a table. Always include a `WHERE` clause to target specific rows — a DELETE without a WHERE clause removes **every row** in the table.
## Basic Syntax
```sql
DELETE FROM table_name WHERE condition;
```
## Examples
### Delete a Single Row by ID
```sql
DELETE FROM users WHERE id = 42;
```
### Delete Multiple Rows by Condition
```sql
DELETE FROM sessions WHERE expires_at < NOW();
```
### Delete All Rows Matching a Value
```sql
DELETE FROM notifications WHERE user_id = 5 AND is_read = 1;
```
### Delete with LIMIT
MariaDB supports `LIMIT` on DELETE to cap how many rows can be removed in one statement:
```sql
DELETE FROM logs WHERE created_at < '2024-01-01' ORDER BY created_at ASC LIMIT 1000;
```
This is useful for batched cleanup of large tables.
## Safety Note
A `DELETE` without a `WHERE` clause removes **every row** from the table. This cannot be undone.
```sql
-- This deletes ALL rows in the table:
DELETE FROM users;
-- This deletes only the intended row:
DELETE FROM users WHERE id = 42;
```
If you need to remove all rows from a large table efficiently, use `TRUNCATE TABLE` instead — it is faster and resets the AUTO_INCREMENT counter.
## Using DELETE via the API
The [CRUD DELETE endpoint](/docs/api-reference/crud/delete) handles row removal by ID or by field value:
```javascript
// Delete by ID
const result = await datasquirel.crud.delete({
dbName: "my_database",
tableName: "sessions",
targetID: 99,
apiKey: process.env.DATASQUIREL_API_KEY,
});
// Delete by field value
const result = await datasquirel.crud.delete({
dbName: "my_database",
tableName: "notifications",
deleteSpec: {
deleteKeyValues: [
{ key: "user_id", value: 5, operator: "=" },
{ key: "is_read", value: 1, operator: "=" },
],
},
apiKey: process.env.DATASQUIREL_API_KEY,
});
```
pages/database-reference/querying-data/index.mdx
+41
View File
@@ -0,0 +1,41 @@
---
title: Querying Data | Datasquirel docs
description: Learn how to query data in Datasquirel using SQL
page_title: Querying Data
page_description: Use SQL to read, insert, update, and delete data in your Datasquirel databases.
---
## Overview
Datasquirel is built on MariaDB, so all standard SQL query syntax works as expected. You can run queries directly from the [admin panel SQL shell](/docs/gui-reference) or through the [REST API](/docs/api-reference/sql).
<div className="w-full grid grid-cols-1 gap-4 items-stretch">
<DocsCard
title="SELECT"
description="Retrieve data from one or more tables."
href="/docs/database-reference/querying-data/select"
/>
<DocsCard
title="INSERT"
description="Add new rows to a table."
href="/docs/database-reference/querying-data/insert"
/>
<DocsCard
title="UPDATE"
description="Modify existing rows in a table."
href="/docs/database-reference/querying-data/update"
/>
<DocsCard
title="DELETE"
description="Remove rows from a table."
href="/docs/database-reference/querying-data/delete"
/>
</div>
## Running Queries
You have two options for executing SQL queries:
**Admin Panel SQL Shell** — navigate to any database in the admin panel and open the SQL shell. Type your query and run it. Results appear in a table below the editor.
**REST API** — POST any SQL string to the `/api/v1/sql` endpoint and receive results as JSON. See [API Reference → SQL](/docs/api-reference/sql).
pages/database-reference/querying-data/insert/index.mdx
+82
View File
@@ -0,0 +1,82 @@
---
title: INSERT | Datasquirel docs
description: Add new rows to a table using INSERT statements in Datasquirel
page_title: INSERT
page_description: Add new rows to your tables using SQL INSERT statements.
---
## Overview
`INSERT INTO` adds one or more new rows to a table. Each row must provide values for all `NOT NULL` columns that do not have a default value.
## Basic Syntax
```sql
INSERT INTO table_name (column1, column2, column3)
VALUES (value1, value2, value3);
```
## Examples
### Insert a Single Row
```sql
INSERT INTO users (name, email, is_active)
VALUES ('Alice', '[email protected]', 1);
```
### Insert Multiple Rows
```sql
INSERT INTO tags (name)
VALUES ('javascript'), ('typescript'), ('sql');
```
### Insert with Default Values
If a column has a DEFAULT value defined, you can omit it:
```sql
INSERT INTO posts (title, content)
VALUES ('My First Post', 'Hello world!');
-- created_at and updated_at will use their DEFAULT values
```
## AUTO_INCREMENT
Every Datasquirel table has an `id` column with `AUTO_INCREMENT`. You never need to provide the `id` value on insert — the database assigns the next available integer automatically.
After an INSERT, the new row's `id` is returned as the `insertId` in the API response.
## Using INSERT via the API
The [CRUD POST endpoint](/docs/api-reference/crud/post) handles inserts through a simple object:
```javascript
const result = await datasquirel.crud.insert({
dbName: "my_database",
tableName: "users",
body: {
name: "Alice",
email: "[email protected]",
is_active: 1,
},
apiKey: process.env.DATASQUIREL_API_KEY,
});
console.log(result.payload); // The new row's id
```
For batch inserts via the API, include a `batchData` array:
```javascript
const result = await datasquirel.crud.insert({
dbName: "my_database",
tableName: "tags",
body: { batchData: [
{ name: "javascript" },
{ name: "typescript" },
]},
apiKey: process.env.DATASQUIREL_API_KEY,
});
```
pages/database-reference/querying-data/select/index.mdx
+90
View File
@@ -0,0 +1,90 @@
---
title: SELECT | Datasquirel docs
description: Read data from a table using SELECT queries in Datasquirel
page_title: SELECT
page_description: Retrieve rows from your tables using SQL SELECT statements.
---
## Overview
`SELECT` retrieves rows from one or more tables. It is the most frequently used SQL statement.
## Basic Syntax
```sql
SELECT column1, column2 FROM table_name WHERE condition ORDER BY column1 ASC LIMIT 10;
```
## Examples
### Get All Rows
```sql
SELECT * FROM users;
```
### Select Specific Columns
```sql
SELECT id, name, email FROM users;
```
### Filter with WHERE
```sql
SELECT * FROM posts WHERE is_published = 1;
```
### Multiple Conditions
```sql
SELECT * FROM posts WHERE is_published = 1 AND category = 'technology';
```
### Sorting
```sql
SELECT * FROM posts ORDER BY created_at DESC;
```
### Pagination
```sql
SELECT * FROM posts ORDER BY created_at DESC LIMIT 10 OFFSET 20;
```
`LIMIT` caps the number of rows returned. `OFFSET` skips the first N rows — useful for pagination (page 3 with 10 items per page = `LIMIT 10 OFFSET 20`).
### JOIN
```sql
SELECT posts.id, posts.title, users.name AS author
FROM posts
JOIN users ON posts.user_id = users.id
WHERE posts.is_published = 1
ORDER BY posts.created_at DESC;
```
### Aggregation
```sql
SELECT category, COUNT(*) AS total
FROM posts
GROUP BY category
ORDER BY total DESC;
```
## Using SELECT via the API
For simple reads, use the [CRUD GET endpoint](/docs/api-reference/crud/get) — it handles filtering, sorting, and pagination through query parameters without writing raw SQL.
For complex queries (JOINs, aggregations, subqueries), use the [SQL API](/docs/api-reference/sql/options):
```javascript
const result = await datasquirel.api.sql({
key: process.env.DATASQUIREL_API_KEY,
params: {
query: "SELECT posts.id, posts.title, users.name AS author FROM posts JOIN users ON posts.user_id = users.id WHERE posts.is_published = 1 ORDER BY posts.created_at DESC LIMIT 20",
},
});
```
pages/database-reference/querying-data/update/index.mdx
+75
View File
@@ -0,0 +1,75 @@
---
title: UPDATE | Datasquirel docs
description: Modify existing rows using UPDATE statements in Datasquirel
page_title: UPDATE
page_description: Modify existing rows in your tables using SQL UPDATE statements.
---
## Overview
`UPDATE` modifies existing rows in a table. Always include a `WHERE` clause to target specific rows — an UPDATE without a WHERE clause updates every row in the table.
## Basic Syntax
```sql
UPDATE table_name SET column1 = value1, column2 = value2 WHERE condition;
```
## Examples
### Update a Single Row by ID
```sql
UPDATE users SET name = 'Alice Smith', email = '[email protected]' WHERE id = 42;
```
### Update Multiple Rows
```sql
UPDATE posts SET is_published = 1 WHERE category = 'announcements';
```
### Update with a Calculated Value
```sql
UPDATE products SET price = price * 1.10 WHERE category = 'electronics';
```
### Update with LIMIT
MariaDB supports `LIMIT` on UPDATE to cap how many rows can be modified in one statement:
```sql
UPDATE notifications SET is_read = 1 WHERE user_id = 5 ORDER BY created_at ASC LIMIT 50;
```
## Safety Note
An `UPDATE` without a `WHERE` clause will update **every row** in the table. Always double-check your `WHERE` clause before running an update, especially in production.
```sql
-- This updates ALL rows in the table:
UPDATE users SET is_active = 0;
-- This updates only the intended row:
UPDATE users SET is_active = 0 WHERE id = 42;
```
## Using UPDATE via the API
The [CRUD PUT endpoint](/docs/api-reference/crud/put) handles updates with a target ID:
```javascript
const result = await datasquirel.crud.update({
dbName: "my_database",
tableName: "users",
targetID: 42,
body: {
name: "Alice Smith",
email: "[email protected]",
},
apiKey: process.env.DATASQUIREL_API_KEY,
});
```
Only the fields you include in `body` are changed — other columns retain their current values.