Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/itsumura-h/nim-allographer
A query_builder/ORM library inspired by Laravel/PHP and Orator/Python for Nim
https://github.com/itsumura-h/nim-allographer
database mariadb mysql nim nim-lang orm postgresql query-builder rdb sqlite3 surrealdb
Last synced: about 1 month ago
JSON representation
A query_builder/ORM library inspired by Laravel/PHP and Orator/Python for Nim
- Host: GitHub
- URL: https://github.com/itsumura-h/nim-allographer
- Owner: itsumura-h
- License: mit
- Created: 2019-09-28T17:02:16.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-04-26T17:16:18.000Z (5 months ago)
- Last Synced: 2024-05-18T15:32:27.006Z (4 months ago)
- Topics: database, mariadb, mysql, nim, nim-lang, orm, postgresql, query-builder, rdb, sqlite3, surrealdb
- Language: Nim
- Homepage:
- Size: 3.51 MB
- Stars: 142
- Watchers: 6
- Forks: 11
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-surreal - allographer - A query builder and schema builder for Nim that also supports SurrealDB. (Libraries)
- awesome-nim - allographer - A query_builder/ORM library inspired by Laravel/PHP and Orator/Python for Nim. (Data / Database)
README
allographer
===
[](https://github.com/yglukhov/nimble-tag)
An asynchronous query builder library inspired by [Laravel/PHP](https://readouble.com/laravel/6.0/en/queries.html) and [Orator/Python](https://orator-orm.com) for Nim.
Supported Databases are [Sqlite3](https://www.sqlite.org/index.html), [PostgreSQL](https://www.postgresql.org/), [MySQL](https://www.mysql.com/), [MariaDB](https://mariadb.org/) and [SurrealDB](https://surrealdb.com/).
Supported Nim for both `1.6.14` and `2.0.0`
## Easy to access Rdb
### Query Builder
```nim
import asyncdispatch, json
import allographer/connection
import allographer/query_builder
let maxConnections = 95
let timeout = 30
let rdb = dbOpen(PostgreSql, "database", "user", "password" "localhost", 5432, maxConnections, timeout)
# also available
# let rdb = dbOpen(Sqlite3, "/path/to/db/sqlite3.db", maxConnections=maxConnections, timeout=timeout)
# let rdb = dbOpen(MySQL, "database", "user", "password" "localhost", 3306, maxConnections, timeout)
# let rdb = dbOpen(MariaDB, "database", "user", "password" "localhost", 3306, maxConnections, timeout)
# let surreal = dbOpen(SurrealDb, "test_ns" "test_db", "user", "password" "http://localhost", 8000, maxConnections, timeout)
proc main(){.async.} =
let result = await rdb
.table("users")
.select("id", "email", "name")
.limit(5)
.offset(10)
.get()
echo result
waitFor main()
>> SELECT id, email, name FROM users LIMIT 5 OFFSET 10
>> @[
{"id":11,"email":"[email protected]","name":"user11"},
{"id":12,"email":"[email protected]","name":"user12"},
{"id":13,"email":"[email protected]","name":"user13"},
{"id":14,"email":"[email protected]","name":"user14"},
{"id":15,"email":"[email protected]","name":"user15"}
]
```
### Schema Builder
```nim
import allographer/schema_builder
rdb.create([
table("auth", [
Column.increments("id"),
Column.string("name").nullable(),
Column.timestamp("created_at").default()
]),
table("users", [
Column.increments("id"),
Column.string("name"),
Column.foreign("auth_id").reference("id").on("auth").onDelete(SET_NULL)
])
])
>> CREATE TABLE auth (
id INT NOT NULL PRIMARY KEY,
name VARCHAR,
created_at DATETIME DEFAULT (NOW())
)
>> CREATE TABLE users (
id INT NOT NULL PRIMARY KEY,
name VARCHAR NOT NULL,
auth_id INT,
FOREIGN KEY(auth_id) REFERENCES auth(id) ON DELETE SET NULL
)
rdb.alter(
table("users", [
Column.string("email").unique().default("").add(),
Column.deleteColumn("name")
])
)
>> ALTER TABLE "users" ADD COLUMN `email` UNIQUE DEFAULT "" CHECK (length(`email`) <= 255)
>> ALTER TABLE "users" DROP `name`
```
## Index
* [allographer](#allographer)
* [Easy to access Rdb](#easy-to-access-rdb)
* [Query Builder](#query-builder)
* [Schema Builder](#schema-builder)
* [Index](#index)
* [Install](#install)
* [Configuation](#configuation)
* [Createing connection](#createing-connection)
* [Logging](#logging)
* [Documents](#documents)
* [Nim API Documents](#nim-api-documents)
* [Schema Builder](#schema-builder-1)
* [Query Builder for RDB](#query-builder-for-rdb)
* [Query Builder for SurrealDB](#query-builder-for-surrealdb)
* [Development](#development)
* [Branch naming rule](#branch-naming-rule)
---
## Install
```sh
nimble install allographer
```
If you get `SIGSEGV: Illegal storage access. (Attempt to read from nil?)` when trying to use the database you likely have a problem with the library path. On OS X the default is to check for the `brew --prefix` of the chosen driver, if that doesn't work it will look in `/usr/lib` or an environment variable `DYLD_xxx_PATH` where `xxx` if your driver: `SQLITE`, `MARIADB`, `MYSQL` or `POSTGRES`.
## Configuation
Allographer loads emvironment variables of `DB_SQLITE`, `DB_POSTGRES`, `DB_MYSQL` `DB_MARIADB` and `DB_SURREAL` to define which process should be **compiled**.
These environment variables have to be set at compile time, so they have to be written in `config.nims` not in `.env`.
config.nims
```nim
import os
putEnv("DB_SQLITE", $true)
putEnv("DB_POSTGRES", $true)
```
In this example, even if your runtime environment lacks `mysqlclient-dev`, execution will success. However if your runtime environment lacks `sqlite3`, execution will fail.
## Createing connection
Database connection should be definded as singleton variable.
database.nim
```nim
import allographer/connection
let rdb* = dbOpen(PostgreSql, "database", "user", "password" "localhost", 5432, maxConnections, timeout)
# you can create connection for multiple database at same time.
let sqliteRdb* = dbOpen(Sqlite3, "/path/to/db/sqlite3.db", maxConnections=maxConnections, timeout=timeout)
let mysqlRdb* = dbOpen(MySQL, "database", "user", "password" "localhost", 3306, maxConnections, timeout)
let mariaRdb* = dbOpen(MariaDB, "database", "user", "password" "localhost", 3306, maxConnections, timeout)
let surrealDb* = dbOpen(SurrealDb, "test_ns" "test_db", "user", "password" "http://localhost", 8000, maxConnections, timeout)
```
Then, call connection when you run query.
run_sql.nim
```nim
import asyncdispatch
import allographer/query_builder
from database import rdb
proc main(){.async.}=
echo await rdb.table("users").get()
waitFor main()
```
## Logging
Please set args in `dbOpen()`
```nim
proc dbOpen*(driver:Driver, database:string="", user:string="", password:string="",
host: string="", port=0, maxConnections=1, timeout=30,
shouldDisplayLog=false, shouldOutputLogFile=false, logDir=""):Rdb
```
- shouldDisplayLog: Whether display logging in terminal console or not.
- shouldOutputLogFile: Whether output logging in log file or not.
- logDir: Define logging dir path.
## Documents
[Schema Builder for RDB](./documents/rdb/schema_builder.md)
[Query Builder for RDB](./documents/rdb/query_builder.md)
[Schema Builder for SurrealDB](./documents/surrealdb/schema_builder.md)
[Query Builder for SurrealDB](./documents/surrealdb/query_builder.md)
## Nim API Documents
### v2
[connection](https://itsumura-h.github.io/nim-allographer/v2/connection.html)
[Schema Builder](https://itsumura-h.github.io/nim-allographer/v2/schema_builder.html)
[Query Builder](https://itsumura-h.github.io/nim-allographer/v2/query_builder.html)
### v1
[connection](https://itsumura-h.github.io/nim-allographer/v1/connection.html)
[Schema Builder](https://itsumura-h.github.io/nim-allographer/v1/schema_builder.html)
[Query Builder](https://itsumura-h.github.io/nim-allographer/v1/query_builder.html)
## Development
### Branch naming rule
Please create this branch name when you will create a new pull request.
| Branch | Description |
| ------ | ----------- |
| feature-*** | New feature branch |
| hotfix-*** | Bug fix branch |
| chore-*** | Chore work or maintenance |
This naming rule automatically labels the pull request.