ydb-platform · scarlettnik · May 8, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -32,6 +32,7 @@ jobs:
       - uses: ./.github/actions/setup
       - run: npm run build
       - run: npm run attw
+      - run: npm run check:surface --workspace=@ydbjs/drizzle-adapter
 
   test:
     name: Test

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -18,6 +18,7 @@ export default defineConfig({
 				nav: [
 					{ text: 'Getting Started', link: '/guide/core' },
 					{ text: 'Query', link: '/guide/query/' },
+					{ text: 'Drizzle', link: '/guide/drizzle-adapter/' },
 					{ text: 'Topic', link: '/guide/topic/' },
 					{ text: 'Coordination', link: '/guide/coordination/' },
 					{ text: 'Advanced', link: '/advanced/' },
@@ -100,6 +101,86 @@ export default defineConfig({
 							},
 						],
 					},
+					{
+						text: 'Drizzle',
+						items: [
+							{ text: 'Overview', link: '/guide/drizzle-adapter/' },
+							{
+								text: 'Options & API',
+								link: '/guide/drizzle-adapter/options',
+							},
+							{
+								text: 'Getting Started',
+								link: '/guide/drizzle-adapter/getting-started',
+							},
+							{
+								text: 'Examples',
+								link: '/guide/drizzle-adapter/examples',
+							},
+							{ text: 'Schema', link: '/guide/drizzle-adapter/schema' },
+							{
+								text: 'Database API',
+								link: '/guide/drizzle-adapter/database-api',
+							},
+							{
+								text: 'Query Builders',
+								link: '/guide/drizzle-adapter/query-builders',
+							},
+							{
+								text: 'Migrations and DDL',
+								link: '/guide/drizzle-adapter/migrations-ddl',
+							},
+							{
+								text: 'YQL Helpers',
+								link: '/guide/drizzle-adapter/yql-helpers',
+							},
+							{
+								text: 'Driver, Session, Dialect',
+								link: '/guide/drizzle-adapter/internals',
+							},
+							{
+								text: 'Public API',
+								link: '/guide/drizzle-adapter/api-index',
+							},
+							{
+								text: 'Examples',
+								items: [
+									{
+										text: 'Runnable examples',
+										link: '/guide/drizzle-adapter/examples',
+									},
+									{
+										text: 'Schema with YDB options',
+										link: '/guide/drizzle-adapter/#examples-schema',
+									},
+									{
+										text: 'CRUD',
+										link: '/guide/drizzle-adapter/#examples-crud',
+									},
+									{
+										text: 'Relations',
+										link: '/guide/drizzle-adapter/#examples-relations',
+									},
+									{
+										text: 'Transactions',
+										link: '/guide/drizzle-adapter/#examples-transactions',
+									},
+									{
+										text: 'Migrations',
+										link: '/guide/drizzle-adapter/#examples-migrations',
+									},
+									{
+										text: 'YQL helpers',
+										link: '/guide/drizzle-adapter/#examples-yql-helpers',
+									},
+									{
+										text: 'Vector search',
+										link: '/guide/drizzle-adapter/#examples-vector-search',
+									},
+								],
+							},
+						],
+					},
 					{
 						text: 'Topic',
 						items: [
@@ -229,6 +310,7 @@ export default defineConfig({
 				nav: [
 					{ text: 'Начало работы', link: '/ru/guide/core' },
 					{ text: 'Query', link: '/ru/guide/query/' },
+					{ text: 'Drizzle', link: '/ru/guide/drizzle-adapter/' },
 					{ text: 'Topic', link: '/ru/guide/topic/' },
 					{ text: 'Coordination', link: '/ru/guide/coordination/' },
 					{ text: 'Расширенные темы', link: '/ru/advanced/' },
@@ -317,6 +399,89 @@ export default defineConfig({
 							},
 						],
 					},
+					{
+						text: 'Drizzle',
+						items: [
+							{ text: 'Обзор', link: '/ru/guide/drizzle-adapter/' },
+							{
+								text: 'Опции и API',
+								link: '/ru/guide/drizzle-adapter/options',
+							},
+							{
+								text: 'Быстрый старт',
+								link: '/ru/guide/drizzle-adapter/getting-started',
+							},
+							{
+								text: 'Примеры',
+								link: '/ru/guide/drizzle-adapter/examples',
+							},
+							{
+								text: 'Схема данных',
+								link: '/ru/guide/drizzle-adapter/schema',
+							},
+							{
+								text: 'Database API',
+								link: '/ru/guide/drizzle-adapter/database-api',
+							},
+							{
+								text: 'Построители запросов',
+								link: '/ru/guide/drizzle-adapter/query-builders',
+							},
+							{
+								text: 'Миграции и DDL',
+								link: '/ru/guide/drizzle-adapter/migrations-ddl',
+							},
+							{
+								text: 'YQL Helpers',
+								link: '/ru/guide/drizzle-adapter/yql-helpers',
+							},
+							{
+								text: 'Driver, Session, Dialect',
+								link: '/ru/guide/drizzle-adapter/internals',
+							},
+							{
+								text: 'Публичный API',
+								link: '/ru/guide/drizzle-adapter/api-index',
+							},
+							{
+								text: 'Примеры',
+								items: [
+									{
+										text: 'Runnable-примеры',
+										link: '/ru/guide/drizzle-adapter/examples',
+									},
+									{
+										text: 'Схема с YDB options',
+										link: '/ru/guide/drizzle-adapter/#examples-schema',
+									},
+									{
+										text: 'CRUD',
+										link: '/ru/guide/drizzle-adapter/#examples-crud',
+									},
+									{
+										text: 'Relations',
+										link: '/ru/guide/drizzle-adapter/#examples-relations',
+									},
+									{
+										text: 'Транзакции',
+										link: '/ru/guide/drizzle-adapter/#examples-transactions',
+									},
+									{
+										text: 'Миграции',
+										link: '/ru/guide/drizzle-adapter/#examples-migrations',
+									},
+									{
+										text: 'YQL helpers',
+										link: '/ru/guide/drizzle-adapter/#examples-yql-helpers',
+									},
+									{
+										text: 'Vector search',
+										link: '/ru/guide/drizzle-adapter/#examples-vector-search',
+									},
+								],
+							},
+						],
+					},
 					{
 						text: 'Topic',
 						items: [

diff --git a/docs/guide/drizzle-adapter/api-index.md b/docs/guide/drizzle-adapter/api-index.md
@@ -0,0 +1,80 @@
+---
+title: Drizzle Adapter — Public API
+---
+
+# Public API Index
+
+This page lists the primary public exports of `@ydbjs/drizzle-adapter`.
+
+## Connection and Database
+
+Root runtime names:
+
+- `createDrizzle(input, config?)` and `drizzle(input, config?)` create the database object.
+- `YdbDriver` is the default executor backed by `@ydbjs/core` and `@ydbjs/query`.
+- Error classes: `YdbUniqueConstraintViolationError`, `YdbAuthenticationError`, `YdbCancelledQueryError`, `YdbTimeoutQueryError`, `YdbUnavailableQueryError`, `YdbOverloadedQueryError`, and `YdbRetryableQueryError`.
+- Type exports cover `YdbDrizzleDatabase`, `YdbDrizzleOptions`, `YdbExecutor`, `YdbTransactionalExecutor`, and transaction configuration.
+
+Implementation classes such as the dialect, session, transaction, and concrete builders are intentionally not root runtime exports. The stable runtime surface is the database object returned by `createDrizzle()`.
+
+Mapped YDB query errors expose `kind`, `retryable`, `statusCode`, and original diagnostic fields such as `code`, `status`, and `issues` when the driver provides them.
+
+## Tables and Schema
+
+- `ydbTable`, `ydbTableCreator`
+- `primaryKey`
+- `unique`
+- `relations`, `one`, `many`
+- `index`, `uniqueIndex`, `vectorIndex`
+- `indexView`, `vectorIndexView`
+- `tableOptions`, `rawTableOption`
+- `ttl`
+- `partitionByHash`
+- `columnFamily`
+
+## Column Builders
+
+`integer`, `int`, `text`, `bigint`, `boolean`, `bytes`, `binary`, `date`, `date32`, `datetime`, `datetime64`, `decimal`, `double`, `dyNumber`, `float`, `int8`, `int16`, `interval`, `interval64`, `json`, `jsonDocument`, `timestamp`, `timestamp64`, `uint8`, `uint16`, `uint32`, `uint64`, `uuid`, `yson`, and `customType`.
+
+## Query Builders
+
+Database entry points:
+
+- SELECT: `db.select`, `db.selectDistinct`, `db.selectDistinctOn`, `db.with`, `db.$with`
+- Mutations: `db.insert`, `db.upsert`, `db.replace`, `db.update`, `db.batchUpdate`, `db.delete`, `db.batchDelete`
+- Utilities: `db.execute`, `db.all`, `db.get`, `db.values`, `db.$count`, `db.transaction`
+
+Builder methods:
+
+- SELECT sources: `.from()`, `.fromAsTable()`, `.fromValues()`
+- SELECT clauses: `.where()`, `.having()`, `.groupBy()`, `.groupCompactBy()`, `.orderBy()`, `.assumeOrderBy()`, `.limit()`, `.offset()`
+- YDB SELECT extensions: `.without()`, `.flattenBy()`, `.flattenListBy()`, `.flattenDictBy()`, `.flattenOptionalBy()`, `.flattenColumns()`, `.sample()`, `.tableSample()`, `.matchRecognize()`, `.window()`, `.intoResult()`, `.uniqueDistinct()`, `.distinct()`, `.distinctOn()`
+- Joins: `.innerJoin()`, `.leftJoin()`, `.rightJoin()`, `.fullJoin()`, `.crossJoin()`, `.leftSemiJoin()`, `.rightSemiJoin()`, `.leftOnlyJoin()`, `.rightOnlyJoin()`, `.exclusionJoin()`
+- Set operators: `.union()`, `.unionAll()`, `.intersect()`, `.except()`, `union()`, `unionAll()`, `intersect()`, `except()`
+- Mutations: `.values()`, `.select()`, `.set()`, `.where()`, `.using()`, `.on()`, `.returning()`, `.onDuplicateKeyUpdate()`
+- Execution and rendering: `.getSQL()`, `.toSQL()`, `.prepare()`, `.execute()`, `.all()`, `.get()`, `.values()`
+- Utilities are exposed through database methods such as `db.$count()` and callback builders passed to `.select()`, `.on()`, and mutation helpers.
+
+## YQL Helpers
+
+- Sources: `asTable`, `values`, `valuesTable`
+- Scripts: `yqlScript`, `pragma`, `declareParam`, `commit`, `defineAction`, `doAction`, `doBlock`, `intoResult`
+- Grouping: `rollup`, `cube`, `groupingSets`, `grouping`, `groupKey`
+- Windows: `windowDefinition`, `sessionWindow`, `sessionStart`, `hop`, `hopStart`, `hopEnd`
+- Vector search: `knnDistance`, `knnSimilarity`, `knnCosineDistance`, `knnEuclideanDistance`, `knnManhattanDistance`, `knnCosineSimilarity`, `knnInnerProductSimilarity`, `kMeansTreeSearchTopSize`
+- Pattern matching and hints: `matchRecognize`, `uniqueHint`, `distinctHint`
+- Set operators: `union`, `unionAll`, `intersect`, `except`
+
+## Migrations and DDL
+
+- `migrate`
+- Migration metadata: `buildMigrationSql`, `buildMigrationLockTableBootstrapSql`
+- Tables: `buildCreateTableSql`, `buildDropTableSql`, `buildAlterTableSql`, `buildRenameTableSql`, `buildAnalyzeSql`, `buildShowCreateSql`
+- Columns and families: `buildAddColumnsSql`, `buildDropColumnsSql`, `buildAddColumnFamilySql`, `buildAlterColumnFamilySql`, `buildAlterColumnSetFamilySql`
+- Table options: `buildAlterTableSetOptionsSql`, `buildAlterTableResetOptionsSql`
+- Indexes and CDC: `buildAddIndexSql`, `buildDropIndexSql`, `buildAddChangefeedSql`, `buildDropChangefeedSql`
+- Topics: `buildCreateTopicSql`, `buildAlterTopicSql`, `buildDropTopicSql`
+- Users and groups: `buildCreateUserSql`, `buildAlterUserSql`, `buildDropUserSql`, `buildCreateGroupSql`, `buildAlterGroupSql`, `buildDropGroupSql`
+- ACL: `buildGrantSql`, `buildRevokeSql`
+- Views: `buildCreateViewSql`, `buildDropViewSql`
+- Services: `buildCreateAsyncReplicationSql`, `buildAlterAsyncReplicationSql`, `buildDropAsyncReplicationSql`, `buildCreateTransferSql`, `buildAlterTransferSql`, `buildDropTransferSql`, `buildCreateSecretSql`