Data SDK

The data SDK is the Vix.cpp profile for persistence-oriented projects.

Install it when a project needs database access, ORM workflows, key-value storage, or cache support. The profile includes the common Vix foundation, then adds the modules used to store, query, migrate, cache, and organize application data.

vix upgrade --sdk data

After the profile is installed, the development workflow stays the same. You still use vix build, vix run, and vix dev. The CLI resolves the installed SDK profile when it builds or runs the project.

Install the Data SDK

Install the CLI first if it is not already installed.

Linux and macOS:

curl -fsSL https://vixcpp.com/install.sh | bash

Windows PowerShell:

irm https://vixcpp.com/install.ps1 | iex

Then install the data profile:

vix upgrade --sdk data

Inspect the profile before installing it:

vix upgrade --sdk info data

Use this command when you want to see the modules, notes, version information, and system dependencies for the current release.

What the Data SDK includes

The data profile includes the common Vix foundation.

common foundation
  cli
  core
  json
  error
  path
  fs
  io
  env
  os
  utils
  log
  async
  time
  process
  threadpool
  template
  ui
  note

It then adds the data-oriented modules.

data
  db
  orm
  kv
  cache

This makes the profile suitable for applications that need database access, migration workflows, lightweight key-value storage, and cache-backed application behavior.

When to use it

Use the Data SDK when the project’s main work is around stored application state.

That includes backend applications with database models, tools that manage local SQLite state, services that need migrations, projects that use the Vix ORM workflow, and applications that need KV or cache modules as part of their runtime.

vix upgrade --sdk data

The default SDK is enough for the base Vix workflow, but it does not include the data module family. When a project starts using db, orm, kv, or cache, install the data profile.

Use it with a project

A normal data-oriented project workflow looks like this:

vix new api
cd api
vix install
vix dev

Build without running:

vix build

Run manually:

vix run

Start the development loop:

vix dev

The SDK profile stays behind the CLI workflow. You install the profile once, then work with the project through Vix commands.

Build a data project

Use vix build when you only want to compile the project.

vix build

Use verbose output when you need more detail from the Vix build workflow.

vix build -v

Use a release build when preparing an optimized binary.

vix build --preset release

If the project needs SQLite-related build support, enable it through the CLI.

vix build --with-sqlite

For MySQL-related support:

vix build --with-mysql

Release examples:

vix build --preset release --with-sqlite
vix build --preset release --with-mysql

The build command detects the project, resolves the local Vix environment, and uses the installed SDK profile during the build.

Database command workflow

The Data SDK is closely related to the database commands exposed by the Vix CLI.

Use vix db for database inspection and operational workflows such as status checks, migrations, and backups.

vix db status
vix db migrate
vix db backup

Use vix orm for ORM migration workflows.

vix orm status
vix orm migrate

When generating a migration, the command should be run from the project where the schema and migration directory belong.

vix orm makemigrations --new ./schema.new.json --dir ./migrations --name add_users

The exact workflow depends on the project structure, but the important point is simple: data projects should stay inside the Vix command surface. The SDK gives the machine the native data modules, and the CLI gives the project a consistent way to build, run, inspect, and migrate.

Cache and KV workflows

The data profile includes both kv and cache.

Use kv when the project needs simple key-value storage behavior. Use cache when the project needs a cache layer around data that can be recomputed, restored, or refreshed. These modules belong in the data profile because they are part of how applications keep state close to the runtime without turning every project into a full database application.

kv
cache

The module-specific pages should be used for API-level examples. This page only explains which SDK profile provides the native modules.

Verify the installation

After installing the data profile, inspect it:

vix upgrade --sdk info data

Check the environment:

vix doctor

Print Vix paths and local state:

vix info

Then run a small file to confirm that the CLI and SDK are usable.

cat > main.cpp <<'CPP'
#include <vix.hpp>

int main()
{
  vix::print("Hello from the Vix Data SDK");
  return 0;
}
CPP

vix run main.cpp

Expected output:

Hello from the Vix Data SDK

If this compiles and runs, the CLI can find the installed SDK profile.

Update the Data SDK

Install or update the latest data profile:

vix upgrade --sdk data

Preview the update without changing files:

vix upgrade --sdk data --dry-run

Install a specific version:

vix upgrade --sdk data --version v2.7.0

Use JSON output for scripts:

vix upgrade --sdk data --json

Remove the Data SDK

Remove the data profile when it is no longer needed:

vix uninstall --sdk data

Preview the removal first:

vix uninstall --sdk data --dry-run

Remove a specific version:

vix uninstall --sdk data --version v2.7.0

List installed SDK profiles known to the uninstall command:

vix uninstall --sdk-list

System dependencies

The data profile may require native libraries used by its modules, especially when the project uses a database backend such as SQLite or MySQL.

Check the current release information before installing or debugging the profile.

vix upgrade --sdk info data

Install the system packages shown by that command for your operating system. The SDK profile gives Vix the native data module layer, but the operating system still needs the database libraries and development packages those modules depend on.

When the Data SDK is not enough

The data profile is focused on persistence and cache workflows. If the project also moves into another domain, install the matching profile beside it.

For backend, WebSocket, WebRPC, middleware, validation, crypto, or outgoing HTTP requests:

vix upgrade --sdk web

For P2P nodes, local-first sync, or peer networking:

vix upgrade --sdk p2p

For desktop applications:

vix upgrade --sdk desktop

For game-oriented workflows:

vix upgrade --sdk game

For agent tooling:

vix upgrade --sdk agent

A machine can have multiple SDK profiles installed. Use the smallest set that matches the projects you are actively building.

Common mistakes

Using the default SDK for data modules

The default profile is the base development layer. It does not include the data module family.

If the project uses db, orm, kv, or cache, install the data profile.

vix upgrade --sdk data

Installing the full SDK for one data project

The full SDK works, but it is usually more than a normal data project needs.

vix upgrade --sdk all

For database, ORM, KV, and cache work, use the data profile.

vix upgrade --sdk data

This keeps setup smaller and avoids unrelated dependencies.

Forgetting database build options

Installing the Data SDK gives Vix the data modules, but a project may still need database-specific build options depending on the backend it uses.

For SQLite:

vix build --with-sqlite

For MySQL:

vix build --with-mysql

Use the option that matches the project instead of enabling every database backend by default.

Passing runtime arguments to vix build

vix build compiles only. It does not start the app.

vix build

Use vix run when you want to run the program.

vix run --run --port 8080

Running database commands outside the project

Database and ORM commands usually depend on project files, environment, or migration directories.

Wrong:

vix orm status

Correct:

cd api
vix orm status

Keep data commands close to the project they operate on.

Daily workflow

A typical data project workflow looks like this:

vix new api
cd api
vix install
vix dev

Check database state when needed:

vix db status
vix orm status

Before committing:

vix fmt --check
vix check --tests

Before release:

vix build --preset release
vix tests --preset release

When the project uses a specific database backend, build with the matching backend option.

vix build --preset release --with-sqlite

The data SDK stays behind the CLI workflow. Once installed, the profile gives Vix the native modules needed for database, ORM, KV, and cache projects.

Next step

Continue with the Desktop SDK when the project needs the Vix desktop shell and UI WebView support.

Open the Desktop SDK guide