Installation | ARX.SDK Documentation

ARX.SDK is a set of NuGet packages: one per database, each bringing the core package ARX.SDK with it. They are on nuget.org as a preview, 1.0.0-rc.1: the API may still change before 1.0, and every change is listed in the Version history. The packages are free to use, commercial use included, under the Apache License 2.0 (MIT through 0.1.0-preview.3).

Working with an AI coding assistant? Give it llms.txt: it points to a knowledge base per provider, generated from samples that were built and run, and to the arx-sdk skill for coding agents.

Prerequisites

The .NET 10 SDK (the packages target net10.0).
A database ARX can reach: PostgreSQL, SQL Server, MySQL, MongoDB (a replica set, for transactions and writes of several documents) or DynamoDB. Each provider's Get started page shows how to run one in Docker for the samples.

Install the provider for your database

Add one provider package. The core package and the database driver come with it, so there is nothing else to add. Name the version: dotnet add package picks only stable versions by itself, and this is a preview.

Database	Package	Command
PostgreSQL	ARX.SDK.PostgreSql	dotnet add package ARX.SDK.PostgreSql --version 1.0.0-rc.1
SQL Server	ARX.SDK.SQL	dotnet add package ARX.SDK.SQL --version 1.0.0-rc.1
MySQL	ARX.SDK.MySQL	dotnet add package ARX.SDK.MySQL --version 1.0.0-rc.1
MongoDB	ARX.SDK.MongoDb	dotnet add package ARX.SDK.MongoDb --version 1.0.0-rc.1
DynamoDB	ARX.SDK.DynamoDb	dotnet add package ARX.SDK.DynamoDb --version 1.0.0-rc.1

Set it up once

An application has one service per database, created at startup and shared (register it as a singleton). It takes the connection string, from your configuration rather than your code, and usually a schema catalog: what you declare about your tables, such as each table's id column.

using ARX.SDK;                       // the errors: ArxException, ArxErrorCode
using ARX.SDK.Query;                 // ArxQueryExpression, conditions, order
using ARX.SDK.Services;              // ArxEntity, ArxSchemaCatalog, ArxIdColumn, ArxColumnSet, options
using ARX.SDK.PostgreSql.Services;   // ArxPgDbService (each provider has its own)

// The variable the Quick Start and every sample read; in your application, read it from your own configuration.
string connectionString = Environment.GetEnvironmentVariable("ARX_SAMPLES_POSTGRESQL")
    ?? throw new InvalidOperationException("Set ARX_SAMPLES_POSTGRESQL to the database's connection string.");

ArxSchemaCatalog schema = ArxSchemaCatalog.Create()
    .Table("account", ArxIdColumn.Generated<long>("id"))      // the database makes the id
    .Table("country", ArxIdColumn.Supplied<string>("code"))   // the application gives it
    .Build();

var service = new ArxPgDbService(connectionString, schema);

// In ASP.NET Core: builder.Services.AddSingleton(service);

ARX needs to know each table's id column to return the id a create makes and to find rows by id. There are three ways to tell it, and the choice is yours:

Way	What ARX does	When to use it
A schema catalog (above)	Uses only what you declare. It never reads table definitions during a call, and refuses a write, or a read by id, to a table you didn't declare (ARX1016). Queries aren't restricted to declared tables: limit what a service can read with Strict mode or the database user's permissions.	Most applications: the fastest, and the tables an application may touch are written down in one place.
A preload (ArxPreLoadTable)	Reads the ids, keys, lookups and column types of the tables you name once, at startup, and builds the catalog from them.	Existing databases: nothing to declare twice, at the cost of one read at startup.
No catalog (only a connection string)	Reads each table's primary key and column types from the database before every call that needs them (PostgreSQL, SQL Server and MySQL).	Small applications and scripts: the simplest to start with, and noticeably slower per call.

The usings every page assumes are the four above (ArxJoinOperator, for links, is in ARX.SDK.Query with the other query types). Two more appear when a sample needs them: ARX.SDK.Models (ArxJsonB, ArxBytea, ArxFullTextSearch, ArxIgnore) and ARX.SDK.Extensions (reading selection sets). Every sample page lists the usings it needs. MongoDB takes the database name as well, and DynamoDB an IAmazonDynamoDB client and a model of its tables: see their Get started pages.

Check the installation

ValidateSchemaAsync compares every table in the schema catalog with the database: it connects, finds each table and its id column, and throws with the difference when something doesn't match. Run it once, at startup or in a test.

await service.ValidateSchemaAsync();
Console.WriteLine("Connected, and every declared table matches the database.");

Next: the Quick Start creates and reads a first record, and each provider's Get started page sets up the sample database every sample runs against. Before production, read Running in production and Using your own tables.