Introduction

This article is only applicable to .NET 6 and later, and is not applicable to eXtremeDB for .NET Framework

eXtremeSQL C# API can be used with Microsoft's .NET Core™ 6.0 on various operating systems and hardware platforms, including Linux / ARM.

The eXtremeDB .NET module for the Microsoft's .NET Core™ 6.0 can be downloaded from the McObject website.

Microsoft's .NET Core™ 6.0 can be downloaded from this site.

The eXtremeDB's .NET module provides applications running under .NET Core with the SQL-based interface to eXtremeDB databases.

It supports eXtremeSQL local and remote operations, and dynamic schema definition via SQL DDL.

Note that sequences, static schema definition via class decorators, and class-level object database access are not currently supported by the eXtremeDB .NET Core module.

Quick start

Make sure you have installed the eXtremeDB package. The environment variable MCO_ROOT must be defined and point to the installation of the main eXtremeDB package for correct setup of eXtremeDB for .NET Core:

    export MCO_ROOT=/your/path/to/eXtremeDB
                        

Unpack eXtremeDB for .NET Core package into a directory where you have sufficient rights for

Build (for Linux platforms) or copy (Windows platforms) supporting dynamic library. It's also possible to build a supporting library on Windows as well, but Visual Studio installation is required for it.

Build a sample:

    cd netcore/samples/SQL
    dotnet build
                        

and run it:

    dotnet run
                        

Programming Overview

An eXtremeDB environment and database are controlled via the Database class:

     Database db = new Database(mode);
                        

where mode is a bitmask (enum-based) defining the set of eXtremeDB features to load and enable. Note that the set of features cannot be changed later at runtime. See below for a detailed explanation of the possible values.

After a Database instance has been created, the database shall be opened with the database parameters specified via Database.Parameters. See below for a description of the parameters and their relation to the eXremeDB mco_params_t core runtime structure.

When the database is opened the database devices can be created. An eXtremeDB in-memory database operates within a preallocated fixed-sized memory segment. For persistent databases three additional storage locations need to be configured. These additional devices are used for the database cachie, persistent storage and a log file.

Note that in addition to these devices. SQL statement execution uses heap memory allocation.

Please refer to this documentation article for the details of memory management.

To create the database segment, the Database.Device class is used. The basic, purely in-memory database runtime configuration that requires just one segment is illustrated below

    devs = new Database.Device[1];
    devs[0] = new Database.PrivateMemoryDevice(Database.Device.Kind.Data, 16*1024*1024 );
			

This code snippet allocates a 16Mb memory segment for in-memory database operations.

Now we can open the database:

    db.Open("sqldb", parameters, devs);
			

The next step is to create the SQL local connection object that will create and attach the SQL engine to the database:

    SqlLocalConnection con = db.ConnectSql();
			

Once the database is connected to, it is ready to be used. Transaction processing is enabled, tables and indexes can be created, data can be inserted into the database and other SQL statements (such as SELECT statements) can be applied using standard SQL'89 . For a detailed description of the eXtremeDB SQL language and available extensions follow link to the relevant documentation articles. An application’s code-flow pattern is illustrated below

Create a table:

    con.ExecuteStatement("create table MyTable (pk int primary key, value varchar)");
                        

Start a transaction explicitly:

    con.StartTransaction(Database.TransactionType.ReadWrite);
                        

Insert data:

    con.ExecuteStatement("insert into MyTable (pk,value) values (?,?)", 2012, "Good bye");
    con.ExecuteStatement("insert into MyTable (pk,value) values (?,?)", 2013, "Hello");
                        

Commit the changes:

    con.CommitTransaction();
                        

Lookup and traversing through the result set:



        using (SqlResultSet result = con.ExecuteQuery("select pk,value from MyTable where pk>=?", 2013))
        {
            foreach (string column in result.ColumnNames)
            {
                Console.Write(column + ", ");
            }
            Console.WriteLine();
            foreach (SqlTuple tuple in result)
            {
                Console.WriteLine(tuple[0] + ", " + tuple["value"]);
            }
        } 
                        

When we are done, the connection should be closed:

      con.Disconnect();
                        

and then the database is closed:

    db.Close();
                        

For more details, please refer to the eXtremeDB and eXtremeSQL samples for .NET Core and native C.