Sqlx intergration for ydb-rs-sdk

This crate provides Sqlx integration for ydb-rs-sdk. It is in under active development.

Basic examples

Starting local YDB in podman (or docker)

# get latest version from yandex

podman pull cr.yandex/yc/yandex-docker-local-ydb:latest

# run docker container

podman run -d --rm --name ydb-local -h localhost \
-p 2135:2135 -p 8765:8765 -p 2136:2136 \
#-v $(pwd)/ydb_certs:/ydb_certs -v $(pwd)/ydb_data:/ydb_data \
-e YDB_DEFAULT_LOG_LEVEL=NOTICE \
-e GRPC_TLS_PORT=2135 -e GRPC_PORT=2136 -e MON_PORT=8765 \
cr.yandex/yc/yandex-docker-local-ydb:latest

Connection from .env

You could use DATABASE_URL or YDB_CONNECTION_STRING environment variable to connect to ydb server.

# .env file
YDB_CONNECTION_STRING=grpc://localhost:2136?database=/local

# .env file
DATABASE_URL=grpcs://ydb.serverless.yandexcloud.net:2135/?database=/ru-central1/xxxxxxxxxxxxxxx/yyyyyyyyyy&connection_timeout=5&sa-key=./key.json

let pool = Ydb::connect_env().await?;

Connection options

let pool = Ydb::connect_env_opts(|opt|opt.log_statements(LevelFilter::Info)).await?;

Connection from url

let pool = Ydb::connect("grpc://localhost:2136?database=/local").await?;

or

let pool = Ydb::connect_opts("grpc://localhost:2136?database=/local", |opt|opt.log_statements(LevelFilter::Info)).await?;

Simple select

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {

    let pool = Ydb::connect_env().await?;
    let row: (i32,) = sqlx::query_as("SELECT 1+1").fetch_one(&pool).await?;
    assert_eq!(row.0, 2);

    Ok(())
}

Query with conditions and parse result to struct

#[derive(sqlx::FromRow)]
struct UserInfo {
    id: u64,
    name: String,
    age: u32,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let pool = Ydb::connect_env().await?;

    let users: Vec<UserInfo> =
        sqlx::query_as("SELECT * FROM test2 WHERE age >= $min_age AND age <= $max_age")
            .bind(("min_age", 30))
            .bind(("max_age", 40))
            .fetch_all(&pool)
            .await?;

    assert!(users.len() > 0);

    Ok(())
}

Schema queries

Schema queries should be executed with SchemaExecutor.

You could use pool.schema() or conn.schema() to get SchemaExecutor:

sqlx::query("CREATE TABLE test2 (id Uint64 NOT NULL, name Utf8, age UInt8, description Utf8, PRIMARY KEY (id))")
        .execute(pool.schema())
        .await?;

Arguments

There are two binding available:

• default unnamed - with generated name like $arg_1
• named by with_name function. you can specify name starting with or without dollr sign, but in query you should use $-started name.

      bind(with_name("age", 30))

• named by tuple ("name", value)

      bind(("age", 30))

Ydb requires that every query params should be declared with DECLARE clause like this:

DECLARE $age AS Uint32;

SELECT * FROM test2 WHERE age > $age;

The library do it for you. You specify only query and bind params to it with bind function.

Checklist

• Connect to ydb
• Default credentials (using fromEnv)
• Custom credentials with options
• Basic query
• Binding parameters
• Support types
  • Numeric
    • Bool
    • Int8
    • Int16
    • Int32
    • Int64
    • Uint8
    • Uint16
    • Uint32
    • Uint64
    • Float
    • Double
    • Decimal
  • String types
    • String
    • Utf8
    • Json
    • JsonDocument
    • Yson
    • Uuid
  • Date and time
    • Date
    • Datetime
    • Timestamp
    • Interval
  • Optional
• Prepared statements
• Transactions
• Compile-type checked queries
• Migrations
• Log Statements