Modern, modular SDK for YDB in TypeScript/JavaScript.
- Type‑safe YQL queries with tagged templates
- Automatic parameter binding and transactions
- Rich value/type system with
@ydbjs/value - Clear errors, retries, and diagnostics
@ydbjs/core: Core connection and utilities@ydbjs/query: YQL queries, transactions, parameters@ydbjs/value: YDB types and values@ydbjs/api: gRPC/Protobuf service definitions@ydbjs/error: YDB error handling@ydbjs/auth: Authentication (tokens, anonymous, metadata)@ydbjs/retry: Flexible retry policies
npm install @ydbjs/core @ydbjs/queryimport { Driver } from '@ydbjs/core'
import { query } from '@ydbjs/query'
const driver = new Driver('grpc://localhost:2136/local')
await driver.ready()
const sql = query(driver)
const resultSets = await sql`SELECT 1 + 1 AS sum`
console.log(resultSets) // [ [ { sum: 2 } ] ]Project docs:
Examples
- Parameterized query:
import { Int64, Optional, PrimitiveType } from '@ydbjs/value'
const sql = query(driver)
await sql`SELECT ${new Optional(new Int64(100n), new PrimitiveType('INT64'))};`– Transactions:
await sql.begin(async (tx, signal) => {
await tx`INSERT INTO users (id, name) VALUES (1, 'Alice')`
await tx`UPDATE users SET name = 'Bob' WHERE id = 1`
})– Error handling:
import { YdbError } from '@ydbjs/error'
try {
await sql`SELECT * FROM non_existent_table`
} catch (e) {
if (e instanceof YdbError) {
console.error('YDB Error:', e.message)
}
}For projects using YDB SDK, you can configure AI assistants (GitHub Copilot, Cursor, etc.) to generate secure YQL code.
Multiple example configuration files are provided in packages/query/ai-instructions/:
.cursorrules.example- Cursor AI instructions.instructions.example.md- General AI assistant guidelines.copilot-instructions.example.md- GitHub Copilot specific.ai-instructions.example.md- Alternative general format
Copy the appropriate file to your project root to enable secure AI code generation that follows YDB security best practices.
- Add a new service? Use
@ydbjs/apifor gRPC definitions. - Work with YDB types? Use
@ydbjs/value. - Implement retries? Use
@ydbjs/retry. - More examples? See package docs, local examples, or explore ydb-js-examples repository with comprehensive real-world examples.
- Build:
npm run build - Test (all):
npm test - Lint:
npm run lint
