Getting started with YDB as an Application Developer / Software Engineer

First of all, you'll need to obtain access to a YDB cluster. Follow the quickstart instructions to get a basic local instance. Later on, you can work with your DevOps team to build a production-ready cluster or leverage one of the cloud service providers that offer a managed YDB service.

The second step is designing a data schema for an application you will build from scratch or adapt the schema of an existing application if you're migrating from another database management system.

In parallel with designing the schema, you need to set up your development environment for interaction with YDB. There are a few main aspects to it, explored below.

Choosing API

Choose the YDB API you want to use; there are several options:

  • The recommended way for mainstream programming languages is using a YDB SDK. They provide high-level APIs and implement best practices on working with YDB. YDB SDKs are available for several popular languages and strive for feature parity, but not all are feature-complete. Refer to the SDK feature comparison table to check if the SDK for the programming language you had in mind will fit your needs or to choose a programming language with better feature coverage if you're flexible.
  • Alternatively, YDB provides PostgreSQL-compatible API. It is intended to simplify migrating existing applications that have outgrown PostgreSQL. However, it is also useful for exotic programming languages that have a PostgreSQL client library but don't have a YDB SDK. Refer to PostgreSQL compatibility documentation to check if its completeness will suit your needs.
  • If you are interested in YDB topics feature, it is worth noting that they also provide Kafka-compatible API. Follow that link if this use case is relevant.
  • As a last resort, YDB's native API is based on the gRPC protocol, which has an ecosystem around it, including code generation of clients. YDB's gRPC specs are hosted on GitHub and you could leverage them in your application. The generated clients are low-level and will require extra work to handle aspects like retries and timeouts properly, so go this route only if other options above aren't possible and you know what you're doing.

Install prerequisites

Choose the specific programming language you'll be using. Install the respective YDB SDK or a PostgreSQL driver depending on the route you have chosen above.

Additionally, you'd want to set up at least one of the available ways to run ad-hoc queries for debugging purposes. Choose at least one according to your preferences:

Start coding

For YDB SDK route

  • Go through YQL tutorial to get familiar with YDB's SQL dialect.
  • Explore example applications to see how working with SDK's looks like.
  • Check out SDK recipies for typical SDK use cases, which you can refer to later.
  • Leverage your IDE capabilities to navigate the SDK code.

For PostgreSQL-compatibility route

  • Learn how to connect PostgreSQL driver with YDB cluster.
  • The rest should be similar to using vanilla PostgreSQL. Use your experience with it or refer to any favorite resources. However, refer to the list of functions and statements to adjust your expectations.

Testing

To write tests on applications working with YDB:

  • For functional tests, you can mock YDB's responses using a suitable testing framework for your chosen programming language.
  • For integrational tests, you can launch a single-node YDB instance in your CI/CD environment with either a Docker image or executable similarly to how it is done in the Quickstart article. It is recommended to test against a few versions of YDB: the one you have in production to check for issues you can encounter when updating your application and the newer versions to identify the potential issues of upgrading YDB early on.
  • For performance tests, you'd want to use a cluster deployed according to instructions for production use as single-node won't yield realistic results. You can run ydb workload if you want to see how your YDB cluster performs in generic scenarios even before writing any application code. Then you can use the source code of the library behind this tool as an example of how to write your own performance tests with YDB. It'd be great if you could contribute an anonymized version of your workload to upstream so it can be included in performance testing of YDB itself.

What's next

The above should be enough to start developing applications that interact with YDB. Along the way use YQL and YDB SDK reference documentation and other resources in this documentation section.

In case of any issues, feel free to discuss them in YDB Discord.

Previous
For Developers
Next
YQL tutorial