A data snapshot provides a point-in-time view of a data file. A database client that reads the snapshot reads the records from the data file as they existed at that point in time, even if the data file has been updated since then. Non-snapshot readers read the data file in its current state. The snapshot log contains record images as they existed at the time of the snapshot. The log exists until the snapshot is deleted.
Data snapshot attributes
A data snapshot includes the following attributes:
- The name of the data file.
- The snapshot ID.
- The transaction log position at which the data snapshot was created.
Data snapshot limitations
- When a data file is included in a data snapshot, we do not allow database connections to open it in exclusive mode. An exclusive open request will fail with error code SNAPSHOT_EXISTS_FOR_FILE (1220), indicating that an active snapshot prevents the operation. This restriction prevents operations on the data file that could change the file’s definitions in a way that would interfere with snapshot readers.
- Data snapshot is only supported on a data file that uses full transaction control (ctTRNLOG transaction mode).
- Data snapshot is supported on fixed-length and variable-length record data files. It is supported on partitioned files.
- Data snapshots are not supported on superfiles, memory files, or segmented files.
- A data file can have only one active snapshot at a time.
Data snapshot operations
We support the following operations for a data snapshot:
1) Create a data snapshot
Function name
NINT CreateDataSnapshot(CREATE_DATA_SNAPSHOT* options);
Description
Create a data snapshot for the specified data file. A data snapshot provides a point-in-time view of the file's contents.
| CREATE_DATA_SNAPSHOT Field | Type | Description | Version |
| ULONG version | Input |
The structure version. Supported versions are: CREATE_DATA_SNAPSHOT_VERSION_1 |
1 |
| ULONG options | Input |
One of the following values: createByDataFileName indicates that the dataFileName field contains the name of the data file. createByDataFileNumber indicates that the dataFileNumber field contains the file number of the data file, which the caller has already opened. |
1 |
| const char* dataFileName | Input | [Optional] If options specifies createByDataFileName, this field specifies the name of the data file to include in the snapshot. The caller must be able to open the file. | 1 |
| FILNO dataFileNumber | Input | [Options] If options specifies createByDataFileNumber, this field specifies the file number of the data file open by the caller. | 1 |
| ULONG isamErrorCode | Output | If the function fails, this field returns the ISAM error code. | 1 |
| ULONG systemErrorCode | Output | If the function fails, this field returns the system error code. | 1 |
| LONG8 snapshotID | Output | On success, this field returns a unique ID for the snapshot. | 1 |
| ctLOGP logPosition | Output | On success, this field returns the transaction log position at which the snapshot was created. | 1 |
| char* errorBuffer | Output | [Optional] If the function call fails, an error message is written to this buffer. | 1 |
| size_t errorBufferSize | Input | The size of errorBuffer in bytes. | 1 |
2) Read a data snapshot
Use a batch physical read to read a data file's snapshot. Call DoBatchXtd() with the BAT_PHYS and BAT_SNAP bits set in the batchmode2 field. The function call behaves like a normal batch read call does, except for the following differences:
DoBatchXtd() reads records from the snapshot instead of from the current state of the data file.
The batch lock request options BAT_LOK_RED and BAT_LOK_WRT are ignored.
To read a data file's snapshot using the c-treeDB API, call ctdbSetBatch() with the CTBATCH_PHYS and CTBATCH_READ_SNAPSHOT batch modes.
3) Delete a data snapshot
Function name
NINT DeleteDataSnapshot(DELETE_DATA_SNAPSHOT* options);
Description
Delete the data snapshot that has the specified snapshot ID.
| DELETE_DATA_SNAPSHOT Field | Type | Description | Version |
| ULONG version | Input |
The structure version. Supported versions are: DELETE_DATA_SNAPSHOT_VERSION_1
|
1 |
| ULONG options | Input |
deleteBySnapshotID indicates that the snapshotID field contains the unique ID of the snapshot to delete. deleteByDataFileName indicates that the dataFileName field contains the name of the data file. deleteByDataFileNumber indicates that the dataFileNumber field contains the file number of the data file that the caller has already opened. |
1 |
| ULONG8 snapshotID | Input | [Optional] If options specifies deleteBySnapshotID, this field specifies the ID of the snapshot to delete. | 1 |
| const char* dataFileName | Input | [Optional] If options specifies deleteByDataFileName, this field specifies the data file name. | 1 |
| FILNO dataFileNumber | Input | [Optional] If the option specifies deleteByDataFileNumber, this field specifies the file number of the data file already opened by the caller. | 1 |
| char* errorBuffer | Output | [Optional] If the function fails, it writes an error message to the errorBuffer buffer. | 1 |
| size_t errorBufferSize | Input | The size of errorBuffer in bytes. | 1 |
| LONG systemErrorCode | Output | [Optional] If the function fails, systemErrorCode is set to the system error code (or zero if no system-level error occurred). | 1 |