= TQL :source-highlighter: pygments
Compile-time ORM, inspired by Django ORM, written in Rust. Tql is implemented as a procedural macro and even works on the stable version of Rust (https://github.com/antoyo/tql/tree/master/examples/todo-stable[look at this example to see how to use tql on stable]).
This library is in alpha stage: it has not been thoroughly tested and its API may change at any time.
image:https://img.shields.io/travis/antoyo/tql/master.svg[link="https://travis-ci.org/antoyo/tql"] image:https://img.shields.io/crates/l/tql.svg[link="LICENSE"] image:https://img.shields.io/gitter/room/tql-rs/Lobby.svg[link="https://gitter.im/tql-rs/Lobby"]
== Requirements
Currently, tql only supports the PostgreSQL database (more databases will be supported in the future).
So, you need to install PostgreSQL in order to use this crate.
== Usage
First, add this to you Cargo.toml:
[dependencies] chrono = "^0.4.0" tql = { git = "https://github.com/antoyo/tql" } tql_macros = { git = "https://github.com/antoyo/tql" }
[dependencies.postgres] features = ["with-chrono"]
(You can remove the chrono stuff if you don't want to use the date and time types in your model.)
Next, add this to your crate:
extern crate chrono; extern crate postgres; extern crate tql;
extern crate tql_macros;
use postgres::{Connection, TlsMode}; use tql::PrimaryKey;
Then, create your model:
use chrono::DateTime; use chrono::offset::Utc;
struct Model {
id: PrimaryKey,
text: String,
date_added: DateTime
Next, create an accessor for your connection:
fn get_connection() -> Connection { Connection::connect("postgres://test:test@localhost/database", TlsMode::None).unwrap()
Finally, we can use the sql! macro to execute an SQL query:
fn main() { let connection = get_connection();
// We first create the table.
// (You might not want to execute this query every time.)
let _ = sql!(Model.create());
// Insert a row in the table.
let text = String::new();
let id = sql!(Model.insert(text = &text, date_added = Utc::now())).unwrap();
// Update a row.
let result = sql!(Model.get(id).update(text = "new-text"));
// Delete a row.
let result = sql!(Model.get(id).delete());
// Query some rows from the table:
// get the last 10 rows sorted by date_added descending.
let items = sql!(Model.sort(-date_added)[..10]);
The sql!() macro uses the identifier connection by default.
Look at the https://github.com/antoyo/tql#syntax-table[following table] to see more examples.
== Using on stable Rust
If you want to use tql on stable, there are a few changes that are required in order to work:
First, remove these lines:
// …
And add the following line before extern crate tql:
This is how the start of the file now looks:
extern crate chrono; extern crate postgres;
extern crate tql;
extern crate tql_macros;
use postgres::{Connection, TlsMode};
Finally, disable the unstable feature by updating the tql dependency to:
With this small change, we can use the sql!() macro like before.
=== Why not always using the stable version?
Procedural macros do not currently support emitting errors at specific positions on the stable version, so with this version, you will get errors that are less useful, like in the following output:
error[E0308]: mismatched types
--> src/main.rs:47:18
|
47 | let result = sql!(Model.insert(text = text, date_added = Utc::now(), done = false));
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ expected &str, found struct std::string::String
|
= note: expected type &str
found type std::string::String
= help: try with &sql!(Model.insert(text = text, date_added = Utc::now(), done = false))
While you will get this nicer error when using the nightly version of Rust:
error[E0308]: mismatched types
--> examples/todo.rs:49:46
|
49 | let result = sql!(Model.insert(text = text, date_added = Utc::now(), done = false));
| ^^^^
| |
| expected &str, found struct std::string::String
| help: consider borrowing here: &text
|
= note: expected type &str
std::string::StringSo, a good workflow is to develop on nightly and then ship on stable. This way, you get the best of both worlds: you have nice errors and you can deploy with the stable version of the compiler. This is not an issue at all because you're not supposed to have compiler errors when you're ready to deploy (and you can see the errors anyway).
NOTE: Compile with RUSTFLAGS "--cfg procmacro2_semver_exempt" to get even better error messages.
== Syntax table
The left side shows the generated SQL and the right side shows the syntax you can use with tql.
[cols="1a,1a", options="header"] |=== | SQL | Rust
|
|
|
|
|
|
Table.get(42)
// Shortcut for:
|
|
Table.get(field1 == "value1")
// Shortcut for:
|
|
|
|
|
|
|
|
|
|
|
SELECT * FROM Table WHERE field1 = 'value1' AND field2 < 100 ORDER BY field2 DESC
|
Table.filter(field1 == "value1" && field2 < 100)
|
|
|
|
Table.get(1).update(field1 = "value1", field2 = 55);
// or
|
|
Table.get(1).delete();
// ou
|
|
|
|
|
SELECT AVG(field1) as average FROM Table1 GROUP BY field2
|
Table1.values(field2).annotate(average = avg(field1))
|
SELECT AVG(field1) as average FROM Table1 WHERE field1 < 10 GROUP BY field2
|
Table1.filter(field1 < 10).values(field2)
|
SELECT Table1.field1, Table2.field1 FROM Table1
|
struct Table1 { pk: PrimaryKey, field1: i32, }
struct Table2 {
field1: i32,
fk: ForeignKey
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
CREATE TABLE IF NOT EXISTS Table1 ( pk INTEGER NOT NULL AUTO_INCREMENT, field1 INTEGER, PRIMARY KEY (pk)
|
struct Table1 { pk: PrimaryKey, field1: i32, }