23 releases
0.2.1 | May 25, 2024 |
---|---|
0.2.0 | Feb 16, 2024 |
0.1.11-alpha | Oct 14, 2023 |
0.1.8-alpha | Sep 27, 2023 |
0.1.0 | Nov 27, 2023 |
#1625 in Procedural macros
Used in 2 crates
(via scyllax)
57KB
1K
SLoC
scyllax (sɪl-æks)
A SQLx and Discord inspired query system for Scylla.
Example
1. Model definition
Before you can write any queries, you have to define a model.
#[entity]
pub struct PersonEntity {
#[entity(primary_key)]
pub id: uuid::Uuid,
pub email: String,
pub created_at: i64,
}
2. Read queries
With the read_query
attribute, it's easy to define select queries.
#[read_query(
query = "select * from person where id = :id limit 1",
return_type = "PersonEntity"
)]
pub struct GetPersonById {
pub id: Uuid,
}
3. Upsert queries
With the upsert_query
attribute, it's easy to define upsert queries.
#[entity]
#[upsert_query(table = "person", name = UpsertPerson)]
pub struct PersonEntity {
#[entity(primary_key)]
pub id: uuid::Uuid,
pub email: String,
pub created_at: i64,
}
4. Query Collections
Scylla required queries be prepared before they can be executed. To prepare (and check) all queries at startup, create a query collection and pass it into an Executor.
create_query_collection!(
PersonQueries,
[
GetPersonById,
GetPersonByEmail
],
[
DeletePersonById,
UpsertPerson
]
);
let executor = Executor::<PersonQueries>::new(Arc::new(session)).await;
let user = executor.execute_read(GetPersonByEmail {
email: "user@truffle.vip".to_string(),
}).await?;
println!("{user:#?}");
Features
- Read Queries
- Write Queries (https://github.com/trufflehq/scyllax/pull/1)
- Request Coalescing
- Compile-time Select Query Validation
- ensure the where constraints exist on the struct
- ensure the where constraints are the same type as the struct
- Runtime Query Validation (structure matches schema)
Todo
- Eject
anyhow
, more refined errors
Usage
See the example for more details.
References
#[read_request(
query = "select * from foo where id = ? limit 1",
entity_type = "Foo"
)]
struct GetFooById {
#[shard_key]
id: i64
}
handle.execute_read(GetFooById { ... }).await
Messages from Jake
the answer though is that unlike the scylla rust wrapper, we don't need the fields to be in the right order for our stuff to work. we do 2 clever things:
SELECT *
is actually a lie. Never useSELECT *
in a prepared statement, ever. CQL suffers from a protocol level bug that can lead to data corruption on schema change when doing aSELECT *
due to a schema de-sync condition that is possible between the client & server. So instead, what we do is, we look at the entity type struct, and we transformSELECT *
intoSELECT col_a, col_b, col_c
. That means if a column present in the schema, but not in the struct we're going to de-serialize to, we don't actually query it. The gist of the bug is that, when a new column is added to a table, the database may start returning data for that column, without the client being aware of that. In the pathological case, this can cause a mis-aligned deserialziation of the data. https://docs.datastax.com/en/developer/java-driver/3.0/manual/statements/prepared/#avoid-preparing-select-queries - although this does look like it's finally fixed in native protocol v5, I'm unsure if scylla is using that yet.
- For binding of the query parameters as well, we essentially parse the SQL statement and figure out all of the bind positions, and then generate code that will bind the fields in the proper order (since on the wire level, they need to be specified in the order that they're defined in the query.) We do this at compile time in a proc macro to generate the code that does the serialization of the query, so we incur no runtime overhead of re-ordering things.
At startup we prepare everything and also type check the structs in code against what's in the db Registering everything manually is fine You can make it fail at compile time If you try to use an unregistered query
Dependencies
~2–2.6MB
~50K SLoC