Main Page » SFTP Functions

SFTP Functions

This module contains functions for accessing remote files over SFTP (the SSH File Transfer Protocol) from XQuery. It is based on the JSch library. A session is opened with sftp:connect, which returns an opaque session handle used by subsequent functions, and closed with sftp:disconnect.

Conventions

The module must be installed in the repository before it can be used. Pre-built module jars are available (via files.basex.org):

REPO INSTALL https://files.basex.org/modules/org/basex/modules/sftp-12.3.jar

In order to use it, it needs to be imported in the header of the query:

import module namespace sftp = 'http://basex.org/modules/sftp';

All functions in this module are assigned to the http://basex.org/modules/sftp namespace, which in the following is assumed to be bound to the sftp prefix.

Errors raised by the underlying SFTP library surface as a QueryException whose message is prefixed with SFTP:.

Session Management

`sftp:connect`

Signature

sftp:connect(
  $server    as xs:string,
  $user      as xs:string,
  $password  as xs:string,
  $port      as xs:integer  := 22,
  $options   as map(*)      := {}
) as item()

Summary

Opens an SFTP session against $server using the supplied credentials and returns an opaque session handle. If $port is omitted, the default port 22 is used. The $options map carries proxy and JSch session configuration. The following keys are recognized:

Key	Type	Description
`ProxyHost`	`xs:string`	HTTP proxy host. If supplied and non-empty, it overrides the BaseX `PROXYHOST` static option.
`ProxyPort`	`xs:integer`	HTTP proxy port. If supplied, it overrides the BaseX `PROXYPORT` static option.
any other key	`xs:string`	Passed through to JSch as session configuration (for example `StrictHostKeyChecking`).

When ProxyHost is absent from the map, the BaseX static options PROXYHOST and PROXYPORT are used as the fallback.

Examples

import module namespace sftp = 'http://basex.org/modules/sftp';

sftp:connect('sftp.example.org', 'user', 'password')

Opens an SFTP session on the default port.

import module namespace sftp = 'http://basex.org/modules/sftp';

sftp:connect('sftp.example.org', 'user', 'password', 2222)

Opens an SFTP session on a custom port.

import module namespace sftp = 'http://basex.org/modules/sftp';

sftp:connect('sftp.example.org', 'user', 'password', 22,
  { 'StrictHostKeyChecking': 'no' })

Opens an SFTP session and disables strict host-key checking.

`sftp:disconnect`

Signature

Signature	sftp:disconnect( $sftp as item() ) as empty-sequence()
Summary	Closes the SFTP session associated with the supplied handle `$sftp`.
Examples	`import module namespace sftp = 'http://basex.org/modules/sftp'; let $sftp := sftp:connect('sftp.example.org', 'user', 'password') return sftp:disconnect($sftp)` Closes an SFTP session.

sftp:disconnect(
  $sftp  as item()
) as empty-sequence()

Summary Closes the SFTP session associated with the supplied handle $sftp.

Examples

import module namespace sftp = 'http://basex.org/modules/sftp';

let $sftp := sftp:connect('sftp.example.org', 'user', 'password')
return sftp:disconnect($sftp)

Closes an SFTP session.

File and Directory Operations

`sftp:cd`

Signature

Signature	sftp:cd( $sftp as item(), $path as xs:string ) as empty-sequence()
Summary	Changes the remote working directory of the session `$sftp` to `$path`.
Examples	`import module namespace sftp = 'http://basex.org/modules/sftp'; let $sftp := sftp:connect('sftp.example.org', 'user', 'password') return ( sftp:cd($sftp, '/home/user'), sftp:disconnect($sftp) )` Changes into a remote directory.

sftp:cd(
  $sftp  as item(),
  $path  as xs:string
) as empty-sequence()

Summary Changes the remote working directory of the session $sftp to $path.

Examples

import module namespace sftp = 'http://basex.org/modules/sftp';

let $sftp := sftp:connect('sftp.example.org', 'user', 'password')
return (
  sftp:cd($sftp, '/home/user'),
  sftp:disconnect($sftp)
)

Changes into a remote directory.

`sftp:list`

Signature

Signature	sftp:list( $sftp as item(), $path as xs:string ) as xs:string*
Summary	Returns the file names contained in the remote directory `$path`.
Examples	`import module namespace sftp = 'http://basex.org/modules/sftp'; let $sftp := sftp:connect('sftp.example.org', 'user', 'password') let $entries := sftp:list($sftp, '/home/user') return (sftp:disconnect($sftp), $entries)` Lists the contents of a remote directory.

sftp:list(
  $sftp  as item(),
  $path  as xs:string
) as xs:string*

Summary Returns the file names contained in the remote directory $path.

Examples

import module namespace sftp = 'http://basex.org/modules/sftp';

let $sftp := sftp:connect('sftp.example.org', 'user', 'password')
let $entries := sftp:list($sftp, '/home/user')
return (sftp:disconnect($sftp), $entries)

Lists the contents of a remote directory.

`sftp:attributes`

Signature

sftp:attributes(
  $sftp  as item(),
  $path  as xs:string
) as map(*)

Summary

Returns a map describing the remote file at $path. The map contains the following entries:

Key	Type	Description
`last-modified`	`xs:dateTime`	Modification time.
`size`	`xs:integer`	File size in bytes.
`dir`	`xs:boolean`	`true` if the entry is a directory.

Examples

import module namespace sftp = 'http://basex.org/modules/sftp';

let $sftp := sftp:connect('sftp.example.org', 'user', 'password')
let $attr := sftp:attributes($sftp, '/home/user/readme.txt')
return (sftp:disconnect($sftp), $attr)

Reads the attributes of a remote file.

`sftp:move`

Signature

Signature	sftp:move( $sftp as item(), $old-path as xs:string, $new-path as xs:string ) as empty-sequence()
Summary	Moves a remote file from `$old-path` to `$new-path`.
Examples	`import module namespace sftp = 'http://basex.org/modules/sftp'; let $sftp := sftp:connect('sftp.example.org', 'user', 'password') return ( sftp:move($sftp, '/home/user/old.txt', '/home/user/new.txt'), sftp:disconnect($sftp) )` Renames a remote file.

sftp:move(
  $sftp      as item(),
  $old-path  as xs:string,
  $new-path  as xs:string
) as empty-sequence()

Summary Moves a remote file from $old-path to $new-path.

Examples

import module namespace sftp = 'http://basex.org/modules/sftp';

let $sftp := sftp:connect('sftp.example.org', 'user', 'password')
return (
  sftp:move($sftp, '/home/user/old.txt', '/home/user/new.txt'),
  sftp:disconnect($sftp)
)

Renames a remote file.

`sftp:delete`

Signature

Signature	sftp:delete( $sftp as item(), $path as xs:string ) as empty-sequence()
Summary	Removes the remote file at `$path`.
Examples	`import module namespace sftp = 'http://basex.org/modules/sftp'; let $sftp := sftp:connect('sftp.example.org', 'user', 'password') return ( sftp:delete($sftp, '/home/user/obsolete.txt'), sftp:disconnect($sftp) )` Removes a remote file.

sftp:delete(
  $sftp  as item(),
  $path  as xs:string
) as empty-sequence()

Summary Removes the remote file at $path.

Examples

import module namespace sftp = 'http://basex.org/modules/sftp';

let $sftp := sftp:connect('sftp.example.org', 'user', 'password')
return (
  sftp:delete($sftp, '/home/user/obsolete.txt'),
  sftp:disconnect($sftp)
)

Removes a remote file.

`sftp:delete-dir`

Signature

Signature	sftp:delete-dir( $sftp as item(), $path as xs:string ) as empty-sequence()
Summary	Removes the remote directory at `$path`.
Examples	`import module namespace sftp = 'http://basex.org/modules/sftp'; let $sftp := sftp:connect('sftp.example.org', 'user', 'password') return ( sftp:delete-dir($sftp, '/home/user/old-folder'), sftp:disconnect($sftp) )` Removes a remote directory.

sftp:delete-dir(
  $sftp  as item(),
  $path  as xs:string
) as empty-sequence()

Summary Removes the remote directory at $path.

Examples

import module namespace sftp = 'http://basex.org/modules/sftp';

let $sftp := sftp:connect('sftp.example.org', 'user', 'password')
return (
  sftp:delete-dir($sftp, '/home/user/old-folder'),
  sftp:disconnect($sftp)
)

Removes a remote directory.

File Transfer

`sftp:get-text`

Signature

Signature	sftp:get-text( $sftp as item(), $path as xs:string ) as xs:string
Summary	Retrieves the contents of the remote file at `$path` as a string.
Examples	`import module namespace sftp = 'http://basex.org/modules/sftp'; let $sftp := sftp:connect('sftp.example.org', 'user', 'password') let $text := sftp:get-text($sftp, '/home/user/readme.txt') return (sftp:disconnect($sftp), $text)` Downloads a remote text file into a string.

sftp:get-text(
  $sftp  as item(),
  $path  as xs:string
) as xs:string

Summary Retrieves the contents of the remote file at $path as a string.

Examples

import module namespace sftp = 'http://basex.org/modules/sftp';

let $sftp := sftp:connect('sftp.example.org', 'user', 'password')
let $text := sftp:get-text($sftp, '/home/user/readme.txt')
return (sftp:disconnect($sftp), $text)

Downloads a remote text file into a string.

`sftp:get-binary`

Signature

Signature	sftp:get-binary( $sftp as item(), $path as xs:string ) as xs:base64Binary
Summary	Retrieves the contents of the remote file at `$path` as a binary value.
Examples	`import module namespace sftp = 'http://basex.org/modules/sftp'; let $sftp := sftp:connect('sftp.example.org', 'user', 'password') let $data := sftp:get-binary($sftp, '/home/user/image.png') return (sftp:disconnect($sftp), $data)` Downloads a remote binary file.

sftp:get-binary(
  $sftp  as item(),
  $path  as xs:string
) as xs:base64Binary

Summary Retrieves the contents of the remote file at $path as a binary value.

Examples

import module namespace sftp = 'http://basex.org/modules/sftp';

let $sftp := sftp:connect('sftp.example.org', 'user', 'password')
let $data := sftp:get-binary($sftp, '/home/user/image.png')
return (sftp:disconnect($sftp), $data)

Downloads a remote binary file.

`sftp:get-file`

Signature

Signature	sftp:get-file( $sftp as item(), $path as xs:string, $local as xs:string ) as empty-sequence()
Summary	Downloads the remote file at `$path` to the local filesystem at `$local`.
Examples	`import module namespace sftp = 'http://basex.org/modules/sftp'; let $sftp := sftp:connect('sftp.example.org', 'user', 'password') return ( sftp:get-file($sftp, '/home/user/data.zip', '/tmp/data.zip'), sftp:disconnect($sftp) )` Downloads a remote file to local disk.

sftp:get-file(
  $sftp   as item(),
  $path   as xs:string,
  $local  as xs:string
) as empty-sequence()

Summary Downloads the remote file at $path to the local filesystem at $local.

Examples

import module namespace sftp = 'http://basex.org/modules/sftp';

let $sftp := sftp:connect('sftp.example.org', 'user', 'password')
return (
  sftp:get-file($sftp, '/home/user/data.zip', '/tmp/data.zip'),
  sftp:disconnect($sftp)
)

Downloads a remote file to local disk.

`sftp:put-text`

Signature

Signature	sftp:put-text( $sftp as item(), $string as xs:string, $path as xs:string ) as empty-sequence()
Summary	Uploads `$string` to the remote file at `$path`.
Examples	`import module namespace sftp = 'http://basex.org/modules/sftp'; let $sftp := sftp:connect('sftp.example.org', 'user', 'password') return ( sftp:put-text($sftp, 'hello world', '/home/user/greeting.txt'), sftp:disconnect($sftp) )` Uploads a string as a remote text file.

sftp:put-text(
  $sftp    as item(),
  $string  as xs:string,
  $path    as xs:string
) as empty-sequence()

Summary Uploads $string to the remote file at $path.

Examples

import module namespace sftp = 'http://basex.org/modules/sftp';

let $sftp := sftp:connect('sftp.example.org', 'user', 'password')
return (
  sftp:put-text($sftp, 'hello world', '/home/user/greeting.txt'),
  sftp:disconnect($sftp)
)

Uploads a string as a remote text file.

`sftp:put-binary`

Signature

Signature	sftp:put-binary( $sftp as item(), $item as xs:base64Binary, $path as xs:string ) as empty-sequence()
Summary	Uploads the binary value `$item` to the remote file at `$path`.
Examples	`import module namespace sftp = 'http://basex.org/modules/sftp'; let $sftp := sftp:connect('sftp.example.org', 'user', 'password') let $bytes := xs:base64Binary('SGVsbG8=') return ( sftp:put-binary($sftp, $bytes, '/home/user/hello.bin'), sftp:disconnect($sftp) )` Uploads a binary value as a remote file.

sftp:put-binary(
  $sftp  as item(),
  $item  as xs:base64Binary,
  $path  as xs:string
) as empty-sequence()

Summary Uploads the binary value $item to the remote file at $path.

Examples

import module namespace sftp = 'http://basex.org/modules/sftp';

let $sftp := sftp:connect('sftp.example.org', 'user', 'password')
let $bytes := xs:base64Binary('SGVsbG8=')
return (
  sftp:put-binary($sftp, $bytes, '/home/user/hello.bin'),
  sftp:disconnect($sftp)
)

Uploads a binary value as a remote file.

`sftp:put-file`

Signature

Signature	sftp:put-file( $sftp as item(), $local as xs:string, $path as xs:string ) as empty-sequence()
Summary	Uploads the local file at `$local` to the remote file at `$path`.
Examples	`import module namespace sftp = 'http://basex.org/modules/sftp'; let $sftp := sftp:connect('sftp.example.org', 'user', 'password') return ( sftp:put-file($sftp, '/tmp/data.zip', '/home/user/data.zip'), sftp:disconnect($sftp) )` Uploads a local file to the remote server.

sftp:put-file(
  $sftp   as item(),
  $local  as xs:string,
  $path   as xs:string
) as empty-sequence()

Summary Uploads the local file at $local to the remote file at $path.

Examples

import module namespace sftp = 'http://basex.org/modules/sftp';

let $sftp := sftp:connect('sftp.example.org', 'user', 'password')
return (
  sftp:put-file($sftp, '/tmp/data.zip', '/home/user/data.zip'),
  sftp:disconnect($sftp)
)

Uploads a local file to the remote server.

Logging

`sftp:logs`

Signature

Signature	sftp:logs() as xs:string*
Summary	Returns the JSch log messages accumulated since the last call, then resets the internal log buffer. Each entry has the form `<level>: <message>`.
Examples	`import module namespace sftp = 'http://basex.org/modules/sftp'; let $sftp := sftp:connect('sftp.example.org', 'user', 'password') let $entries := sftp:list($sftp, '/home/user') return ( sftp:disconnect($sftp), sftp:logs() )` Retrieves and clears the JSch log buffer after a session.

sftp:logs() as xs:string*

Summary Returns the JSch log messages accumulated since the last call, then resets the internal log buffer. Each entry has the form <level>: <message>.

Examples

import module namespace sftp = 'http://basex.org/modules/sftp';

let $sftp := sftp:connect('sftp.example.org', 'user', 'password')
let $entries := sftp:list($sftp, '/home/user')
return (
  sftp:disconnect($sftp),
  sftp:logs()
)

Retrieves and clears the JSch log buffer after a session.

⚡Generated with XQuery