Direct node storage access

Data Structures
struct	qdb_backup_options_t
	Backup additional parameters. More...
struct	qdb_backup_s3_options_t
	Backup S3 additional parameters. More...
struct	qdb_backup_progress_t
	Backup progress details. More...

Typedefs
typedef enum qdb_backup_flags_t	qdb_backup_flags_t
	Backup modification flags.

Enumerations
enum	qdb_backup_flags_t { qdb_backup_checkpoint = 1, qdb_backup_checkpoint_trim, qdb_backup_full }
	Backup modification flags. More...

Functions
QDB_API_LINKAGE qdb_direct_handle_t	qdb_direct_connect (qdb_handle_t handle, const char *uri)
	Opens a direct connection to a node for use with the direct API. More...
QDB_API_LINKAGE void	qdb_direct_close (qdb_direct_handle_t handle)
	Close a direct handle initially opened with qdb_direct_connect. More...
QDB_API_LINKAGE qdb_error_t	qdb_direct_blob_get (qdb_direct_handle_t handle, const char *alias, const void **content, qdb_size_t *content_length)
	Retrieves an entry's content from a quasardb node's local storage. More...
QDB_API_LINKAGE qdb_error_t	qdb_direct_blob_put (qdb_direct_handle_t handle, const char *alias, const void *content, qdb_size_t content_length, qdb_time_t expiry_time)
	Creates a new entry and sets its content to the provided blob. More...
QDB_API_LINKAGE qdb_error_t	qdb_direct_blob_update (qdb_direct_handle_t handle, const char *alias, const void *content, qdb_size_t content_length, qdb_time_t expiry_time)
	Creates or updates an entry and sets its content to the provided blob. More...
QDB_API_LINKAGE qdb_error_t	qdb_direct_remove (qdb_direct_handle_t handle, const char *alias)
	Removes an entry from the local node's storage, regardless of its type. More...
QDB_API_LINKAGE qdb_error_t	qdb_direct_int_put (qdb_direct_handle_t handle, const char *alias, qdb_int_t integer, qdb_time_t expiry_time)
	Creates a new signed 64-bit integer. More...
QDB_API_LINKAGE qdb_error_t	qdb_direct_int_update (qdb_direct_handle_t handle, const char *alias, qdb_int_t integer, qdb_time_t expiry_time)
	Creates or updates a signed 64-bit integer. More...
QDB_API_LINKAGE qdb_error_t	qdb_direct_int_get (qdb_direct_handle_t handle, const char *alias, qdb_int_t *integer)
	Retrieves the value of a signed 64-bit integer. More...
QDB_API_LINKAGE qdb_error_t	qdb_direct_int_add (qdb_direct_handle_t handle, const char *alias, qdb_int_t addend, qdb_int_t *result)
	Atomically increases or decreases a signed 64-bit integer. More...
QDB_API_LINKAGE qdb_error_t	qdb_direct_node_backup (qdb_direct_handle_t handle, const char *output_directory, const qdb_backup_options_t *options)
	Run backup process on the node. More...
QDB_API_LINKAGE qdb_error_t	qdb_direct_node_get_backup_progress (qdb_direct_handle_t handle, qdb_uint_t *completed)
	Get the backup progress. More...
QDB_API_LINKAGE qdb_error_t	qdb_direct_node_abort_backup (qdb_direct_handle_t handle)
	Abort the running backup. More...
QDB_API_LINKAGE qdb_error_t	qdb_direct_node_s3_backup (qdb_direct_handle_t handle, const char *bucket, const char *path_prefix, const char *region, const qdb_backup_s3_options_t *options)
	Run backup process to S3 on the node. More...
QDB_API_LINKAGE qdb_error_t	qdb_direct_node_get_s3_backup_progress (qdb_direct_handle_t handle, qdb_backup_progress_t *progress)
	Get the S3 backup progress. More...

Detailed Description

Enumeration Type Documentation

enum qdb_backup_flags_t

Backup modification flags.

Enumerator
qdb_backup_checkpoint	Make checkpoint backup.
qdb_backup_checkpoint_trim	Control number of checkpoints in backup.
qdb_backup_full	Make full backup. Incompatible with checkpoint flags.

Function Documentation

QDB_API_LINKAGE qdb_error_t qdb_direct_blob_get	(	qdb_direct_handle_t	handle,
		const char *	alias,
		const void **	content,
		qdb_size_t *	content_length
	)

Retrieves an entry's content from a quasardb node's local storage.

If the entry does not exist, the function will fail and return qdb_e_alias_not_found.

This function bypasses the clustering mechanism and accesses the node local storage. Entries in the local node storage are not accessible via the regular API and vice versa.

The function will allocate a buffer large enough to hold the entry's content. This buffer must be released by the caller with a call to qdb_release().

Parameters

	handle	A valid handle previously initialized by qdb_direct_connect
	alias	A pointer to a null-terminated UTF-8 string representing the alias of the entry.
[out]	content	A pointer to a pointer that will be set to a function-allocated buffer holding the entry's content.
[out]	content_length	A pointer to a qdb_size_t that will be set to the content's size, in bytes.

Returns

A qdb_error_t code indicating success or failure.

QDB_API_LINKAGE qdb_error_t qdb_direct_blob_put	(	qdb_direct_handle_t	handle,
		const char *	alias,
		const void *	content,
		qdb_size_t	content_length,
		qdb_time_t	expiry_time
	)

Creates a new entry and sets its content to the provided blob.

If the entry already exists the function will fail and will return qdb_e_alias_already_exists.

This function bypasses the clustering mechanism and accesses the node local storage. Entries in the local node storage are not accessible via the regular API and vice versa.

You can specify an expiry or use qdb_never_expires if you don't want the entry to expire.

There is no software-defined limit to the size of blobs.

Parameters

handle	A valid handle previously initialized by qdb_direct_connect
alias	A pointer to a null-terminated UTF-8 string representing the alias of the entry.
content	A pointer to the buffer with the blob content
content_length	The length of the buffer, in bytes
expiry_time	This parameter is currently ignored.

Returns

A qdb_error_t code indicating success or failure.

QDB_API_LINKAGE qdb_error_t qdb_direct_blob_update	(	qdb_direct_handle_t	handle,
		const char *	alias,
		const void *	content,
		qdb_size_t	content_length,
		qdb_time_t	expiry_time
	)

Creates or updates an entry and sets its content to the provided blob.

If the entry already exists, the function will modify the entry.

This function bypasses the clustering mechanism and accesses the node local storage. Entries in the local node storage are not accessible via the regular API and vice versa.

You can specify an expiry or use qdb_never_expires if you don't want the entry to expire.

There is no software-defined limit to the size of blobs.

Parameters

handle	A valid handle previously initialized by qdb_direct_connect
alias	A pointer to a null-terminated UTF-8 string representing the alias of the entry.
content	A pointer to the buffer with the blob content
content_length	The length of the buffer, in bytes
expiry_time	This parameter is currently ignored.

Returns

A qdb_error_t code indicating success or failure.

QDB_API_LINKAGE void qdb_direct_close

(

qdb_direct_handle_t

handle

)

Close a direct handle initially opened with qdb_direct_connect.

Parameters

handle

A valid handle previously initialized by qdb_direct_connect

QDB_API_LINKAGE qdb_direct_handle_t qdb_direct_connect	(	qdb_handle_t	handle,
		const char *	uri
	)

Opens a direct connection to a node for use with the direct API.

The returned handled must be freed with qdb_direct_close. Releasing the direct handle has no impact on non-direct connections or other direct handles.

Parameters

handle	A valid handle previously initialized by qdb_open or qdb_open_tcp.
uri	A string representing the node address and port (without the qdb:// prefix)

Returns

A valid qdb_direct_handle_t if successful, a null pointer.

QDB_API_LINKAGE qdb_error_t qdb_direct_int_add	(	qdb_direct_handle_t	handle,
		const char *	alias,
		qdb_int_t	addend,
		qdb_int_t *	result
	)

Atomically increases or decreases a signed 64-bit integer.

This function bypasses the clustering mechanism and accesses the node local storage. Entries in the local node storage are not accessible via the regular API and vice versa.

The specified entry will be atomically increased (or decreased) according to the given addend value:

• To increase the value, specify a positive addend
• To decrease the value, specify a negative addend

The function return the result of the operation.

The entry must already exist. If the entry is not an integer, the function will return qdb_e_incompatible_type.

Parameters

handle	A valid handle previously initialized by qdb_direct_connect
alias	A pointer to a null-terminated UTF-8 string representing the alias of the entry.
addend	The value to add to the existing value.
result	A pointer to an integer that will receive the current value of the entry, if successful.

Returns

A qdb_error_t code indicating success or failure.

See Also

qdb_int_put, qdb_int_update, qdb_int_get

QDB_API_LINKAGE qdb_error_t qdb_direct_int_get	(	qdb_direct_handle_t	handle,
		const char *	alias,
		qdb_int_t *	integer
	)

Retrieves the value of a signed 64-bit integer.

Atomically retrieves the value of an existing 64-bit integer.

This function bypasses the clustering mechanism and accesses the node local storage. Entries in the local node storage are not accessible via the regular API and vice versa.

If the entry is not an integer, the function will return qdb_e_incompatible_type.

Parameters

handle	A valid handle previously initialized by qdb_direct_connect
alias	A pointer to a null-terminated UTF-8 string representing the alias of the entry.
integer	A pointer to an integer that will receive the current value of the entry, if successful.

Returns

A qdb_error_t code indicating success or failure.

See Also

qdb_int_put, qdb_int_update, qdb_int_add

QDB_API_LINKAGE qdb_error_t qdb_direct_int_put	(	qdb_direct_handle_t	handle,
		const char *	alias,
		qdb_int_t	integer,
		qdb_time_t	expiry_time
	)

Creates a new signed 64-bit integer.

Atomically creates an entry of the given alias and sets it to a cross-platform signed 64-bit integer. If the entry already exists, the function returns an error.

This function bypasses the clustering mechanism and accesses the node local storage. Entries in the local node storage are not accessible via the regular API and vice versa.

You can specify an expiry or use qdb_never_expires if you don't want the entry to expire.

If you want to create or update an entry use qdb_int_update.

The value will be correctly translated independently of the endianness of the client's platform.

Parameters

handle	A valid handle previously initialized by qdb_direct_connect
alias	A pointer to a null-terminated UTF-8 string representing the alias of the entry.
integer	The value to which the integer must be set.
expiry_time	This parameter is currently ignored.

Returns

A qdb_error_t code indicating success or failure.

See Also

qdb_int_update, qdb_int_get, qdb_int_add

QDB_API_LINKAGE qdb_error_t qdb_direct_int_update	(	qdb_direct_handle_t	handle,
		const char *	alias,
		qdb_int_t	integer,
		qdb_time_t	expiry_time
	)

Creates or updates a signed 64-bit integer.

Atomically updates an entry of the given alias to the provided value. If the entry doesn't exist, it will be created. If the entry is not an integer, the function will return qdb_e_incompatible_type.

This function bypasses the clustering mechanism and accesses the node local storage. Entries in the local node storage are not accessible via the regular API and vice versa.

You can specify an expiry time or use qdb_never_expires if you don't want the entry to expire.

Parameters

handle	A valid handle previously initialized by qdb_direct_connect
alias	A pointer to a null-terminated UTF-8 string representing the alias of the entry.
integer	The value to which the integer must be set.
expiry_time	This parameter is currently ignored.

Returns

A qdb_error_t code indicating success or failure.

See Also

qdb_int_put, qdb_int_get, qdb_int_add

QDB_API_LINKAGE qdb_error_t qdb_direct_node_abort_backup

(

qdb_direct_handle_t

handle

)

Abort the running backup.

This function aborts the last active backup.

See Also

qdb_direct_node_backup

Parameters

handle

A valid handle previously initialized by qdb_direct_connect

Returns

A qdb_error_t code indicating success or failure.

QDB_API_LINKAGE qdb_error_t qdb_direct_node_backup	(	qdb_direct_handle_t	handle,
		const char *	output_directory,
		const qdb_backup_options_t *	options
	)

Run backup process on the node.

This function bypasses the clustering mechanism and accesses the node local storage. Entries in the local node storage are not accessible via the regular API and vice versa.

Triggers a backup of the node into the specified directory. The function returns right after the backup is started and will not wait for its completion. Only one backup per node can be running at any point in time. Returns an error if a backup is already in progress.

Parameters

handle	A valid handle previously initialized by qdb_direct_connect
output_directory	A pointer to a null-terminated UTF-8 string representing the target backup path on the node size. Can't be null or empty.
options	Additional backup parameters (optional).

Returns

A qdb_error_t code indicating success or failure.

QDB_API_LINKAGE qdb_error_t qdb_direct_node_get_backup_progress	(	qdb_direct_handle_t	handle,
		qdb_uint_t *	completed
	)

Get the backup progress.

This function returns last backup progress.

See Also

qdb_direct_node_backup

Parameters

handle	A valid handle previously initialized by qdb_direct_connect
completed	An actually backupped part in Bytes.

Returns

A qdb_error_t code indicating success or failure.

QDB_API_LINKAGE qdb_error_t qdb_direct_node_get_s3_backup_progress	(	qdb_direct_handle_t	handle,
		qdb_backup_progress_t *	progress
	)

Get the S3 backup progress.

This function returns last backup progress.

See Also

qdb_direct_node_s3_backup

Parameters

handle	A valid handle previously initialized by qdb_direct_connect
progress	A backup progress details.

Returns

A qdb_error_t code indicating success or failure.

QDB_API_LINKAGE qdb_error_t qdb_direct_node_s3_backup	(	qdb_direct_handle_t	handle,
		const char *	bucket,
		const char *	path_prefix,
		const char *	region,
		const qdb_backup_s3_options_t *	options
	)

Run backup process to S3 on the node.

This function bypasses the clustering mechanism and accesses the node local storage. Entries in the local node storage are not accessible via the regular API and vice versa.

Triggers a backup of the node into the S3 cloud. The function returns right after the backup is started and will not wait for its completion. Only one backup per node can be running at any point in time. Returns an error if a backup is already in progress.

See Also

qdb_direct_node_get_s3_backup_progress

Parameters

handle	A valid handle previously initialized by qdb_direct_connect
bucket	A pointer to a null-terminated UTF-8 string representing the bucket name.
path_prefix	A pointer to a null-terminated UTF-8 string representing the object path prefix.
region	A pointer to a null-terminated UTF-8 string representing the region (optional).
options	Additional backup parameters (optional).

Returns

A qdb_error_t code indicating success or failure.

QDB_API_LINKAGE qdb_error_t qdb_direct_remove	(	qdb_direct_handle_t	handle,
		const char *	alias
	)

Removes an entry from the local node's storage, regardless of its type.

This function bypasses the clustering mechanism and accesses the node local storage. Entries in the local node storage are not accessible via the regular API and vice versa.

The call is ACID, regardless of the type of the entry and a transaction will be created if need be.

Parameters

handle	A valid handle previously initialized by qdb_direct_connect
alias	A pointer to a null-terminated UTF-8 string representing the alias of the entry.

Returns

A qdb_error_t code indicating success or failure.