Поделиться через

спецификация пакета SDK для клиента VDI SQL Server на Linux

Область применения: SQL Server — Linux

В этой статье рассматриваются интерфейсы, предоставляемые клиентским пакетом SDK для интерфейса виртуальных устройств SQL Server на Linux (VDI).

Примечание.

Для SQL Server 2022 (16.x) в Linux можно создать резервную копию моментальных снимков Transact-SQL.

Независимые поставщики программного обеспечения (НЕЗАВИСИМЫе поставщики программного обеспечения) могут использовать интерфейс программирования приложения виртуального резервного копирования (API) для интеграции SQL Server в свои продукты. Как правило, VDI в Linux работает аналогично VDI в Windows, но со следующими отличиями:

  • Общая память Windows становится общей памятью POSIX.
  • Семафоры Windows становятся семафорами POSIX.
  • Типы Windows, такие как HRESULT и DWORD изменяются на целые эквиваленты.
  • Интерфейсы COM удаляются и заменяются парой классов C++.
  • SQL Server на Linux не поддерживает именованные экземпляры, поэтому ссылки на имя экземпляра удалены.
  • Общая библиотека реализована в libsqlvdi.so, установленной в /opt/mssql/lib/libsqlvdi.so.

Эта статья представляет собой надстройку в справочник по интерфейсу виртуального устройства (VDI), который содержит сведения о спецификациях VDI SQL Server в Windows.

Также ознакомьтесь с примером решения для резервного копирования VDI в репозитории GitHub с образцами для SQL Server.

Настройка разрешений пользователя

В Linux примитивы POSIX принадлежат создающему их пользователю и группе по умолчанию. Для объектов, созданных SQL Server, они принадлежат mssql пользователю и mssql группе по умолчанию. Чтобы разрешить общий доступ между SQL Server и клиентом VDI, рекомендуется использовать один из следующих двух методов:

  1. Запустите клиент VDI от имени mssql пользователя.

    Выполните следующую команду, чтобы переключиться на mssql пользователя:

    sudo su mssql

  2. mssql Добавьте пользователя в vdiuser группу и vdiuser пользователя в группуmssql.

    Выполните следующие команды:

    sudo useradd vdiuser
sudo usermod -a -G mssql vdiuser
sudo usermod -a -G vdiuser mssql

    Перезапустите сервер, чтобы получить новые группы для SQL Server и vdiuser.

Клиентские функции

В этом разделе содержатся описания каждого из клиентских функций. В описаниях приводятся следующие сведения:

  • Назначение функции
  • Синтаксис функции
  • Список параметров
  • Возвращаемые значения
  • Замечания

ClientVirtualDeviceSet::Create

Характер использования

Эта функция создает набор виртуальных устройств.

Синтаксис

int ClientVirtualDeviceSet::Create (
    char     *    name,    // name for the set
    VDConfig *    cfg      // configuration for the set
);
Параметры Аргумент Описание
name Определяет набор виртуальных устройств. Необходимо следовать правилам имен, используемых CreateFileMapping() . Любой символ, кроме обратной косой черты (\) может использоваться. Это символьная строка. К строке рекомендуется добавить префикс в виде названия продукта или компании пользователя и имени базы данных.
cfg Это конфигурация для набора виртуальных устройств.
Возвращаемые значения Аргумент Описание
NOERROR Функция выполнена успешно.
VD_E_NOTSUPPORTED Одно или несколько полей в конфигурации недопустимы или не поддерживаются.
VD_E_PROTOCOL Набор виртуальных устройств уже существует.

Замечания

Метод Create должен вызываться только один раз для каждой BACKUP операции или RESTORE операции. После вызова Close метода клиент может повторно использовать интерфейс для создания другого набора виртуальных устройств.

ClientVirtualDeviceSet::GetConfiguration

Характер использования

Эта функция используется для ожидания настройки набора виртуальных устройств сервера.

Синтаксис

int ClientVirtualDeviceSet::GetConfiguration (
    time_t        timeout,    // in milliseconds
    VDConfig *    cfg         // selected configuration
);
Параметры Аргумент Описание
timeout Это время ожидания в миллисекундах. Используйте INFINITE или любое отрицательное целое число, чтобы предотвратить время ожидания.
cfg После успешного выполнения содержит конфигурацию, выбранную сервером.
Возвращаемые значения Аргумент Описание
NOERROR Конфигурация возвращена.
VD_E_ABORT SignalAbort был вызван.
VD_E_TIMEOUT Время ожидания функции истекло.

Замечания

Эта функция блокирует состояние Alertable . После успешного вызова устройства в наборе виртуальных устройств можно открыть.

ClientVirtualDeviceSet::OpenDevice

Характер использования

Эта функция открывает одно из устройств в наборе виртуальных устройств.

Синтаксис

int ClientVirtualDeviceSet::OpenDevice (
    char                *     name,              // name for the set
    ClientVirtualDevice **    ppVirtualDevice    // returns interface to device
);
Параметры Аргумент Описание
name Определяет набор виртуальных устройств.
ppVirtualDevice После успешного выполнения функции возвращается указатель на виртуальное устройство. Это устройство используется для GetCommand и CompleteCommand.
Возвращаемые значения Аргумент Описание
NOERROR Функция выполнена успешно.
VD_E_ABORT Запрошено прерывание.
VD_E_OPEN Все устройства открыты.
VD_E_PROTOCOL Набор не находится в состоянии инициализации или это конкретное устройство уже открыто.
VD_E_INVALID Недопустимое имя устройства. Это не одно из имен, известных как набор.

Замечания

VD_E_OPEN может быть возвращен без проблем. Клиент может вызываться OpenDevice с помощью цикла, пока этот код не будет возвращен. Если настроено несколько устройств, например n , набор виртуальных устройств возвращает n уникальных интерфейсов устройств.

Функцию GetConfiguration можно использовать для ожидания открытия устройств.

Если эта функция не выполнена, то значение NULL возвращается через ppVirtualDevice.

ClientVirtualDevice::GetCommand

Характер использования

Эта функция используется для получения следующей команды в очереди на устройство. При запросе эта функция ожидает следующую команду.

Синтаксис

int ClientVirtualDevice::GetCommand (
    time_t           timeout,    // time-out in milliseconds
    VDC_Command**    ppCmd       // returns the next command
);
Параметры Аргумент Описание
timeout Это время ожидания (в миллисекундах). Используйте INFINITE для ожидания на неопределенный срок. Используется 0 для опроса команды. VD_E_TIMEOUT возвращается, если команда в настоящее время недоступна. Если наступает время ожидания, клиент принимает решение о следующем действии.
Время ожидания Это время ожидания (в миллисекундах). Используйте INFINITE или отрицательное значение, чтобы ждать неограниченное время. Используйте 0, чтобы запросить команду. VD_E_TIMEOUT возвращается, если команда не доступна до истечения срока ожидания. Если наступает время ожидания, клиент принимает решение о следующем действии.
ppCmd При успешном возвращении команды параметр возвращает адрес выполняемой команды. Возвращенная память доступна только для чтения. После завершения команды этот указатель передается в подпрограмму CompleteCommand .
Возвращаемые значения Аргумент Описание
NOERROR Команда получена.
VD_E_CLOSE Устройство было закрыто сервером.
VD_E_TIMEOUT Доступных команд не было. Время ожидания истекло.
VD_E_ABORT Клиент или сервер использовали SignalAbort принудительное завершение работы.

Замечания

При VD_E_CLOSE возвращении SQL Server закрыл устройство. Это часть нормального завершения работы. После закрытия всех устройств клиент вызывается ClientVirtualDeviceSet::Close для закрытия набора виртуальных устройств. Если эта подпрограмма должна блокировать ожидание команды, поток остается в Alertable состоянии.

ClientVirtualDevice::CompleteCommand

Характер использования

Эта функция используется для уведомления SQL Server о завершении команды. Должны возвращаться сведения о завершении, соответствующие команде.

Синтаксис

int ClientVirtualDevice::CompleteCommand (
    VDC_Command      pCmd,                // the command
    int              completionCode,      // completion code
    unsigned long    bytesTransferred,    // bytes transferred
    int64_t          position             // current position
);
Параметры Аргумент Описание
pCmd Это адрес команды, возвращенной ClientVirtualDevice::GetCommandранее.
completionCode Это код состояния, указывающий состояние завершения. Этот параметр должен возвращаться для всех команд. Возвращаемый код должен соответствовать выполняемой команде. ERROR_SUCCESS используется во всех случаях для обозначения успешно выполненной команды. Полный список возможных кодов см. в файле vdierror.h.
bytesTransferred Количество успешно переданных байт. Возвращается только для команд передачи Read данных и Write.
position Это ответ только на GetPosition команду.
Возвращаемые значения Аргумент Описание
NOERROR Завершение отмечено правильно.
VD_E_INVALID pCmd не была активной командой.
VD_E_ABORT Abort был сигналирован.
VD_E_PROTOCOL Устройство не открыто.

Замечания

нет

ClientVirtualDeviceSet::SignalAbort

Характер использования

Эта функция используется для сигнала о том, что должно произойти ненормальное завершение.

Синтаксис

int ClientVirtualDeviceSet::SignalAbort ();
Параметры Аргумент Описание
нет Неприменимо
Возвращаемые значения Аргумент Описание
NOERROR Уведомление Abort было успешно размещено.

Замечания

В любое время клиент может выбрать прерывание BACKUP или RESTORE операцию. Эта подпрограмма оповещает о необходимости прекращения всех операций. Состояние общего набора виртуальных устройств входит в Abnormally Terminated состояние. На устройства не возвращаются никакие дополнительные команды. Все незавершенные команды автоматически завершаются, возвращаясь ERROR_OPERATION_ABORTED в виде кода завершения. Клиент должен вызываться ClientVirtualDeviceSet::Close после безопасного завершения любого выдающегося использования буферов, предоставленных клиенту.

ClientVirtualDeviceSet::Close

Характер использования

Эта функция закрывает набор виртуальных устройств, созданный с помощью ClientVirtualDeviceSet::Create. В результате высвобождаются все ресурсы, связанные с набором виртуальных устройств.

Синтаксис

int ClientVirtualDeviceSet::Close ();
Параметры Аргумент Описание
нет Неприменимо
Возвращаемые значения Аргумент Описание
NOERROR Возвращается при успешном закрытии набора виртуальных устройств.
VD_E_PROTOCOL Никаких действий не было предприняно, так как набор виртуальных устройств не был открыт.
VD_E_OPEN Устройства по-прежнему открыты.

Замечания

Вызов — это объявление Close клиента о том, что все ресурсы, используемые набором виртуальных устройств, должны быть освобождены. Перед вызовом Closeклиент должен убедиться, что все действия, связанные с буферами данных и виртуальными устройствами, завершаются. Все интерфейсы виртуальных устройств, возвращаемые OpenDevice недействительными Close.

Клиент может выдавать Create вызов в интерфейсе набора виртуальных устройств после Close возврата вызова. Такой вызов создаст новый набор виртуальных устройств для последующей BACKUP или RESTORE операции.

Если Close вызывается при открытии одного или нескольких виртуальных устройств, VD_E_OPEN возвращается. В этом случае внутренне активируется, SignalAbort чтобы обеспечить надлежащее завершение работы, если это возможно. Высвобождаются ресурсы VDI. Перед вызовом VD_E_CLOSEClientVirtualDeviceSet::Closeклиент должен ожидать указания на каждом устройстве. Если клиент знает, что набор виртуальных устройств уже находится в Abnormally Terminated состоянии, он не должен ожидать VD_E_CLOSE от него указания GetCommandи может вызываться ClientVirtualDeviceSet::Close сразу после завершения действия в общих буферах.

ClientVirtualDeviceSet::OpenInSecondary

Характер использования

Эта функция открывает набор виртуальных устройств в дополнительном клиенте. Основной клиент должен уже использовать Create и GetConfiguration настроить набор виртуальных устройств.

Синтаксис

int ClientVirtualDeviceSet::OpenInSecondary (
    char *    setName    // name of the set
);
Параметры Аргумент Описание
setName Определяет набор. Это имя учитывает регистр и должно соответствовать имени, используемому основным клиентом при вызове ClientVirtualDeviceSet::Create.
Возвращаемые значения Аргумент Описание
NOERROR Функция выполнена успешно.
VD_E_PROTOCOL Набор виртуальных устройств еще не создан, уже открыт на этом клиенте, или набор виртуальных устройств не готов принимать открытые запросы от вторичных клиентов.
VD_E_ABORT Операция прерывается.

Примечание. При использовании модели с несколькими процессами первичный клиент несет ответственность за обнаружение нормального и аномального завершения работы вторичных клиентов.

ClientVirtualDeviceSet::GetBufferHandle

Характер использования

Для работы с буферами, возвращаемыми в ClientVirtualDevice::GetCommandнекоторых приложениях, может потребоваться несколько процессов. В таких случаях процесс, получающий команду, может использовать GetBufferHandle для получения независимого дескриптора процесса, идентифицирующее буфер. Затем этот дескриптор можно передать в любой другой процесс, где открыт тот же набор виртуальных устройств. Затем этот процесс будет использоваться ClientVirtualDeviceSet::MapBufferHandle для получения адреса буфера. Этот адрес, скорее всего, будет отличаться от адреса партнера, так как каждый процесс может быть сопоставлен буферами по разным адресам.

Синтаксис

int ClientVirtualDeviceSet::GetBufferHandle (
    uint8_t*         pBuffer,         // in: buffer address
    unsigned int*    pBufferHandle    // out: buffer handle
);
Параметры Аргумент Описание
pBuffer Это адрес буфера, полученного из Read команды или Write команды.
BufferHandle Возвращается уникальный идентификатор буфера.
Возвращаемые значения Аргумент Описание
NOERROR Функция выполнена успешно.
VD_E_PROTOCOL В настоящее время набор виртуальных устройств не открыт.
VD_E_INVALID Недопустимый pBuffer адрес.

Замечания

Процесс, GetBufferHandle вызывающий функцию, отвечает за вызов ClientVirtualDevice::CompleteCommand при завершении передачи данных.

ClientVirtualDeviceSet::MapBufferHandle

Характер использования

Эта функция используется для получения допустимого адреса буфера из дескриптора буфера, полученного из другого процесса.

Синтаксис

int ClientVirtualDeviceSet::MapBufferHandle (
    int          dwBuffer,    // in: buffer handle
    uint8_t**    ppBuffer     // out: buffer address
);
Параметры Аргумент Описание
dwBuffer Это дескриптор, возвращаемый ClientVirtualDeviceSet::GetBufferHandle.
ppBuffer Это адрес буфера, допустимый в текущем процессе.
Возвращаемые значения Аргумент Описание
NOERROR Функция выполнена успешно.
VD_E_PROTOCOL В настоящее время набор виртуальных устройств не открыт.
VD_E_INVALID Недопустимый ppBuffer дескриптор.

Замечания

Следите за правильной связью дескрипторов. Дескрипторы являются локальными по отношению к одному набору виртуальных устройств. Партнерские процессы совместно используют дескриптор, чтобы дескриптор буфера использовался только в пределах набора виртуальных устройств, из которого буфер был первоначально получен.