Data Export and Import in C#

Database Backup

The eXtremeDB database backup and restore functionality is implemented by the CreateBackup() and RestoreBackup() methods of the Connection class. Please see the SDK sample IncBackup for implementation details.

CreateBackup()

The CreateBackup() method has two overloads:

    public virtual void CreateBackup(string fileName, string label, Database.BackupType type);

    public virtual void CreateBackup(string fileName, string label, Database.BackupType type,
                                     int compressionLevel, string cipher);
            

where the backup type and compressionLevel are defined as follows:

    public enum BackupType
    {
        Auto,
        Snapshot,
        Incremental
    };

    public const int BACKUP_FLAG_COMPRESSED = 1;
    public const int BACKUP_FLAG_ENCRYPTED  = 2;
            

RestoreBackup()

Similarly, the RestoreBackup() method can be called with or without an encryption key:

    public virtual void RestoreBackup(string fileName, string label);

    public void RestoreBackup(string fileName, string label, string cipher);
            

ListBackup()

In addition, the ListBackup() method can be called to retrieve information from a backup file. It returns an array of BackupInfo structures:

    public virtual Database.BackupInfo[] ListBackup(string fileName);

    public static class BackupInfo
    {
        public int        ProtocolVersion;
        public BackupType Type;
        public int        Flags;
        public int        BackupNo;
        public long       Timestamp;
        public long       Size;
        public long       Offset;
        public int        Crc;
        public long       TransNo;
        public int        MemPageSize;
        public int        DiskPageSize;
        public long       NPagesTotal;
        public string     DbName;
        public string     Label;
    }
            

Additional Backup Parameters

Further backup parameters can be specified in the Database.Parameters object used for the Open() method:

    /// <summary>
    /// Size of backup counters array, bytes, power of two. Ignored if disk_max_database_size is set.
    /// Default is 0 - disable backup feature.
    /// </summary>
    public long BackupMapSize;

    /// <summary>
    /// Number of pages for last exclusive pass of backup procedure. Set to zero to disable threshold.
    /// Default is 0.
    /// </summary>
    public int BackupMinPages;

    /// <summary>
    /// Max number of passes before exclusive pass of backup procedure. Default is 10.
    /// </summary>
    public int BackupMaxPasses;

    /// <summary>
    /// Name of a file used to store backup temporary data on mco_db_close() call.
    /// Optional. Set to null for default "<persistent-storage>.bmap" file located at the same location
    /// as the persistent storage file.
    /// </summary>
    public string BackupMapFile;
            

(These parameters correspond to backup_map_size, backup_min_pages, backup_max_passes, and backup_map_filename in the mco_db_params_t structure of the C API.)

Database Snapshots

To save an image of a database to a specified file, the Connection class provides the SaveSnapshot() method. This snapshot can later be loaded by the Database method Open() if the corresponding file path is specified in the Database.Parameters property DatabaseSnapshotFilePath. A file is always created, or overwritten if it already exists. The method returns true if the snapshot was successfully saved, and false if the specified file cannot be opened.

The method signature is:

    public bool SaveSnapshot(string databaseSnapshotFilePath)
            

Saving and Loading Individual Classes

It is sometimes desirable to export or import only the data for an individual database class. The Connection class provides the following methods for this purpose:

    public bool SaveClass(string filePath, Type cls)

    public bool LoadClass(string filePath, Type cls, bool doMerge)
            

Note that if the doMerge argument is false, the existing data content of this class is cleared before loading from the image file. If true, the loaded objects are added to the existing class data. The methods return true if the objects were successfully saved or loaded, and false if the specified file cannot be opened.

Saving Database Metadata

It is possible to save the database metadata (data layout information) in xSQL config file format (JSON). This file is suitable for loading into xSQL to connect to the database as a client application. The Connection class provides the SaveMetadata() method. The method signature is:

    public void SaveMetadata(string databaseMetadataFilePath, bool saveDefaults)
            

Saving Database Schema

It is possible to save the database schema to an external file. The Connection class provides the SaveDictionary() method.

    public void SaveDictionary(string databaseDictionaryFilePath)
            

XML Export and Import

The C# wrapper exposes XML export/import through the ExtremeDB.Connection class:

    public bool ExportXML(String filePath)
    public bool ImportXML(String filePath, int transactionSize)
    public bool ImportXML(String filePath)

ImportXML(filePath) is a convenience overload equivalent to ImportXML(filePath, 0).

ExportXML() and ImportXML() return false when the specified XML file cannot be opened. Database-level errors are reported through the usual C# wrapper error mechanism.

Example usage:

    const int IMPORT_TRANSACTION_SIZE = 25;
    const string XML_FILENAME = "db.xml";

    Database db = new Database(new ExtremedbWrapper(), mode);
    db.Open("xml-export-db", CreateParameters(), CreateDevices());
    Connection con = new Connection(db);

    // Insert data here.

    if (!con.ExportXML(XML_FILENAME))
    {
        throw new Exception("Failed to create XML file: " + XML_FILENAME);
    }

    con.Disconnect();
    db.Close();

    Database targetDb = new Database(new ExtremedbWrapper(), mode);
    targetDb.Open("xml-import-db", CreateParameters(), CreateDevices());
    Connection targetCon = new Connection(targetDb);

    if (!targetCon.ImportXML(XML_FILENAME, IMPORT_TRANSACTION_SIZE))
    {
        throw new Exception("Failed to open XML file: " + XML_FILENAME);
    }

The full sample can be found in the samples/csharp/XML directory.