diff --git a/.github/scripts/publish.sh b/.github/scripts/publish.sh index 3e97d4cb..970eec02 100644 --- a/.github/scripts/publish.sh +++ b/.github/scripts/publish.sh @@ -47,7 +47,7 @@ CHANGELOG="$CHANGELOG Full Changelog: [$LAST_TAG...$TAG](https://github.com/ydb-platform/ydb-dotnet-sdk/compare/$LAST_TAG...$TAG)" -cd src +cd src/Ydb.Sdk/src dotnet pack -c Release -o out /p:Version=$VERSION gh release create $TAG -t "$TAG" --notes "$CHANGELOG" dotnet nuget push out/Ydb.Sdk.$VERSION.nupkg --skip-duplicate --api-key $NUGET_TOKEN --source https://api.nuget.org/v3/index.json diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index df5302b0..58949b9a 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -24,7 +24,7 @@ jobs: env: VERSION_CHANGE: ${{ github.event.inputs.version-change }} RELEASE_CANDIDATE: ${{ github.event.inputs.release-candidate }} - CHANGELOG_FILE: CHANGELOG.md + CHANGELOG_FILE: ./src/Ydb.Sdk/CHANGELOG.md GITHUB_TOKEN: ${{ secrets.YDB_PLATFORM_BOT_TOKEN_REPO }} NUGET_TOKEN: ${{ secrets.YDB_PLATFORM_NUGET_TOKEN }} steps: @@ -42,7 +42,7 @@ jobs: 9.0.x - name: Build run: | - cd src + cd src/Ydb.Sdk/src dotnet build --configuration Release - name: Publish run: bash .github/scripts/publish.sh diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e53e2e92..110fb528 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,14 +2,14 @@ ## Common -YDB is a free and open project and we appreciate to receive contributions from our community. +YDB is a free and open project, and we appreciate to receive contributions from our community. ## Contributing code changes If you would like to contribute a new feature or a bug fix, please discuss your idea first on the GitHub issue. If there is no issue for your idea, please open one. It may be that somebody is already working on it, or that there are some complex obstacles that you should know about before starting the implementation. -Usually there are several ways to fix a problem and it is important to find the right approach before spending time on a PR +Usually there are several ways to fix a problem, and it is important to find the right approach before spending time on a PR that cannot be merged. ## Provide a contribution diff --git a/README.md b/README.md index 13240444..22d7d510 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,37 @@ -[![Nuget](https://img.shields.io/nuget/v/Ydb.Sdk)](https://www.nuget.org/packages/Ydb.Sdk/) +# YDB .NET Ecosystem -# YDB .NET SDK -Provides an ADO.NET standard implementation for working with YDB, as well as native clients for lightweight interaction with YDB. +[![Telegram](https://img.shields.io/badge/Telegram-Русский_чат-2ba2d9.svg?logo=telegram)](https://t.me/ydb_ru) +[![Telegram](https://img.shields.io/badge/Telegram-English_chat-2ba2d9.svg?logo=telegram)](https://t.me/ydb_en) +[![WebSite](https://img.shields.io/badge/website-ydb.tech-blue.svg)](https://ydb.tech) -## Prerequisites -.NET 6 or above +## Overview -## Features +This repository contains all official C# components for working with YDB: -- **ADO.NET**: Full support for standard ADO.NET interfaces including DbConnection, DbCommand, DbDataReader, and more. This allows you to use familiar methods and patterns for database operations while leveraging the power and flexibility of YDB. +- **Ydb.Sdk** - Core SDK includes an ADO.NET provider and a topic (Writer / Reader) client. +- **EntityFrameworkCore.Ydb** - Entity Framework Core integration. -## Versioning - -We follow the **[SemVer 2.0.0](https://semver.org)**. In particular, we provide backward compatibility in the `MAJOR` releases. New features without loss of backward compatibility appear on the `MINOR` release. In the minor version, the patch number starts from `0`. Bug fixes and internal changes are released with the third digit (`PATCH`) in the version. - -Major version zero (`0.y.z`) is considered prerelease and **do not guarantee any backward compatibility**. +## Packages -## Installation +| Package | NuGet | Readme | Documentation | +|-----------|--------------------------------------------------------------------------------------------|-----------------------------------|---------------| +| `Ydb.Sdk` | [![NuGet](https://img.shields.io/nuget/v/Ydb.Sdk)](https://www.nuget.org/packages/Ydb.Sdk) | [README](./src/Ydb.Sdk/README.md) | | -``` -dotnet add package Ydb.Sdk -``` - -## Usage ADO.NET +## Versioning -Example of using ADO.NET to execute a SQL query against YDB: +We follow the **[SemVer 2.0.0](https://semver.org)**. In particular, we provide backward compatibility in the `MAJOR` +releases. New features without loss of backward compatibility appear on the `MINOR` release. In the minor version, the +patch number starts from `0`. Bug fixes and internal changes are released with the third digit (`PATCH`) in the version. -```c# -var ydbConnectionBuilder = new YdbConnectionStringBuilder -{ - Host = "server", - Port = 2135, - Database = "/my-ydb", - UseTls = true, - CredentialsProvider = credentialsProvider // Credentials provider, see "Credentials" section -}; +Major version zero (`0.y.z`) is considered prerelease and **do not guarantee any backward compatibility**. -await using var connection = new YdbConnection(ydbConnectionBuilder); -await connection.OpenAsync(); +## Contributing -var ydbCommand = connection.CreateCommand(); -ydbCommand.CommandText = """ - SELECT series_id, season_id, episode_id, air_date, title - FROM episodes - WHERE series_id = @series_id AND season_id > @season_id - ORDER BY series_id, season_id, episode_id - LIMIT @limit_size; - """; -ydbCommand.Parameters.Add(new YdbParameter("series_id", DbType.UInt64, 1U)); -ydbCommand.Parameters.Add(new YdbParameter("season_id", DbType.UInt64, 1U)); -ydbCommand.Parameters.Add(new YdbParameter("limit_size", DbType.UInt64, 3U)); +We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines. -var ydbDataReader = await ydbCommand.ExecuteReaderAsync(); +## License -_logger.LogInformation("Selected rows:"); -while (await ydbDataReader.ReadAsync()) -{ - _logger.LogInformation( - "series_id: {series_id}, season_id: {season_id}, episode_id: {episode_id}, air_date: {air_date}, title: {title}", - ydbDataReader.GetUint64(0), ydbDataReader.GetUint64(1), ydbDataReader.GetUint64(2), - ydbDataReader.GetDateTime(3), ydbDataReader.GetString(4)); -} -``` +This repository is licensed under the Apache 2.0 License. ## Examples diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..14a90023 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,26 @@ +# Security Policy + +## Reporting a Vulnerability + +We're extremely grateful for security researchers and users who report vulnerabilities they discovered in YDB. All reports are thoroughly investigated. + +To report a potential vulnerability in YDB please email details to [security@ydb.tech](mailto:security@ydb.tech). + +### When Should I Report a Vulnerability? + +- You think you discovered a potential security vulnerability in YDB +- You are unsure how a vulnerability affects YDB + +## Security Vulnerability Response + +Each report is acknowledged and analyzed by YDB maintainers within 5 working days. +We will keep the reporter informed about the issue progress. + +## Public Disclosure Timing + +A public disclosure date is negotiated by YDB maintainers and the bug submitter. +We prefer to fully disclose the bug as soon as possible once a mitigation is available for YDB users. +It is reasonable to delay disclosure when the bug or the fix is not yet fully understood, +the solution is not well-tested, or for vendor coordination. +The timeframe for disclosure is from immediate (especially if it's already publicly known) to 90 days. +For a vulnerability with a straightforward mitigation, we expect report date to disclosure date to be on the order of 7 days. diff --git a/src/EFCore.Ydb/README.md b/src/EFCore.Ydb/README.md new file mode 100644 index 00000000..e69de29b diff --git a/CHANGELOG.md b/src/Ydb.Sdk/CHANGELOG.md similarity index 100% rename from CHANGELOG.md rename to src/Ydb.Sdk/CHANGELOG.md diff --git a/src/Ydb.Sdk/README.md b/src/Ydb.Sdk/README.md new file mode 100644 index 00000000..b979a78e --- /dev/null +++ b/src/Ydb.Sdk/README.md @@ -0,0 +1,65 @@ +# YDB .NET SDK + +[![NuGet](https://img.shields.io/nuget/v/Ydb.Sdk)](https://www.nuget.org/packages/Ydb.Sdk) + +## Overview + +Provides an ADO.NET standard implementation for working with YDB, as well as native clients for lightweight interaction with YDB. + +## Features + +- **Ydb.Sdk.Ado**: Full support for standard ADO.NET interfaces including DbConnection, DbCommand, DbDataReader, and more. This allows you to use familiar methods and patterns for database operations while leveraging the power and flexibility of YDB. +- **Ydb.Sdk.Services.Topic**: Writer and Reader topic clients implement core topic functionality for YDB – writing and reading message streams. + +## Installation + +``` +dotnet add package Ydb.Sdk +``` + +## Usage ADO.NET + +Example of using ADO.NET to execute a SQL query against YDB: + +```c# +var ydbConnectionBuilder = new YdbConnectionStringBuilder +{ + Host = "server", + Port = 2135, + Database = "/my-ydb", + UseTls = true +}; + +await using var connection = new YdbConnection(ydbConnectionBuilder); +await connection.OpenAsync(); + +var ydbCommand = connection.CreateCommand(); +ydbCommand.CommandText = """ + SELECT series_id, season_id, episode_id, air_date, title + FROM episodes + WHERE series_id = @series_id AND season_id > @season_id + ORDER BY series_id, season_id, episode_id + LIMIT @limit_size; + """; +ydbCommand.Parameters.Add(new YdbParameter("series_id", DbType.UInt64, 1U)); +ydbCommand.Parameters.Add(new YdbParameter("season_id", DbType.UInt64, 1U)); +ydbCommand.Parameters.Add(new YdbParameter("limit_size", DbType.UInt64, 3U)); + +var ydbDataReader = await ydbCommand.ExecuteReaderAsync(); + +_logger.LogInformation("Selected rows:"); +while (await ydbDataReader.ReadAsync()) +{ + _logger.LogInformation( + "series_id: {series_id}, season_id: {season_id}, episode_id: {episode_id}, air_date: {air_date}, title: {title}", + ydbDataReader.GetUint64(0), ydbDataReader.GetUint64(1), ydbDataReader.GetUint64(2), + ydbDataReader.GetDateTime(3), ydbDataReader.GetString(4)); +} +``` + +## More examples + +- [AdoNet simple guide](./../../examples/src/AdoNet) +- [AdoNet connect to Yandex Cloud](./../../examples/src/YC) +- [Dapper example](./../../examples/src/DapperExample) +- [Topic client](./../../examples/src/Topic) diff --git a/src/YdbSdk.sln b/src/YdbSdk.sln index 19250bf0..36ca04d5 100644 --- a/src/YdbSdk.sln +++ b/src/YdbSdk.sln @@ -4,6 +4,9 @@ Microsoft Visual Studio Solution File, Format Version 12.00 VisualStudioVersion = 16.0.29306.81 MinimumVisualStudioVersion = 10.0.40219.1 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Ydb.Sdk", "Ydb.Sdk", "{34D81B90-76BA-430B-B3B1-B830B7206134}" + ProjectSection(SolutionItems) = preProject + Ydb.Sdk\CHANGELOG.md = Ydb.Sdk\CHANGELOG.md + EndProjectSection EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{E21B559D-5E8D-47AE-950E-03435F3066DF}" EndProject