slackerdb

    # make sure you have JDK17 and maven 3.6+ ready.
    # Download source code
    git clone ...
    # compile it
    cd slackerdb
    mvn clean compile package

    # All compiled results will be placed in the dist directory.
    #    compiled Jar packages,
    #    default configuration files.

    java -jar dbserver/target/slackerdb-dbserver-0.1.8-standalone.jar start

    java -jar dbserver/target/slackerdb-dbserver-0.1.8-standalone.jar stop

    java -jar dbserver/target/slackerdb-dbserver-0.1.8-standalone.jar status

    java -jar dbproxy/target/slackerdb-dbproxy-0.1.8-standalone.jar start

    java -jar dbproxy/target/slackerdb-dbproxy-0.1.8-standalone.jar stop

    java -jar dbproxy/target/slackerdb-dbproxy-0.1.8-standalone.jar status

# Database name, default is none.
data=

# Path where data files are saved
# ":memory:" indicates in-memory mode (data will be lost after restart)
data_dir=:memory:

# Temporary files directory during operations
# Disk mode:   Defaults to data_dir if not specified
# Memory mode: Defaults to system temp directory if not specified
# Recommended: Use high-performance storage for temp_dir
temp_dir=

# Directory for extension plugins
# Default: $HOME/.duckdb/extensions
extension_dir=

# Run as background daemon (true/false)
daemon=

# PID file location
# - Locks exclusively during server operation
# - Startup aborts if file is locked by another process
# - No file created if not configured, and no lock.
pid=

# Log output destinations (comma-separated)
# "CONSOLE" for stdout, file paths for file logging
log=CONSOLE,logs/slackerdb.log

# Log verbosity level
log_level=INFO

# Main service port
# 0 = random port assignment
# -1 = disable network interface
# Default: 0 (disabled)
port=

# Data service API port
# 0 = random port assignment
# -1 = disable interface (default)
port_x=

# Network binding address
bind=0.0.0.0

# Client connection idle timeout (seconds)
client_timeout=600

# External remote listener registry endpoint
# Format: IP:PORT
# Default: none (disabled)
remote_listener=

# Database opening mode.
# Default: READ_WRITE
access_mode=READ_WRITE

# Maximum concurrent connections
# Default: 256
max_connections=

# Maximum worker threads
# Default: CPU core count
max_workers=

# Database engine threads
# Default: 50% of CPU cores
# Recommendation: 5-10GB RAM per thread
threads=

# Memory usage limit (K/M/G suffix)
# Default: 60% of available memory
# -1 = unlimited (memory mode only)
memory_limit=

# Database template file
template=

# Initialization script(s)
# Executes only on first launch
# Accepts: .sql file or directory
init_script=

# Startup script(s)
# Executes on every launch
# Accepts: .sql file or directory
startup_script=

# System locale
# Default: OS setting
locale=

# SQL command history
# ON = enable tracking
# OFF = disable (default)
sql_history=OFF

# Minimum idle connections in pool
connection_pool_minimum_idle=3

# Maximum idle connections in pool
connection_pool_maximum_idle=10

# Connection lifetime (milliseconds)
connection_pool_maximum_lifecycle_time=900000

# Query result cache configuration (in bytes)
# - Only caches API request results (JDBC queries unaffected)
# - Default: 1GB (1073741824 bytes)
# - Set to 0 to disable caching
query_result_cache_size=

# Data service schema initialization
# - Accepts:
#   * JSON file path (single schema)
#   * Directory path (loads all *.service files)
# - Schema files should contain service definitions in JSON format
data_service_schema=

# PID file location
# - Locks exclusively during server operation
# - Startup aborts if file is locked by another process
# - No file created if not configured, and no lock.
pid=

# Log output destinations (comma-separated)
# "CONSOLE" for stdout, file paths for file logging
log=CONSOLE,logs/slackerdb-proxy.log

# Log level
log_level=INFO

# Run as background daemon (true/false)
daemon=

# Main service port
# 0 = random port assignment
# -1 = disable network interface
# Default: 0 (disabled)
port=0

# Data service API port
# 0 = random port assignment
# -1 = disable interface (default)
port_x=0

# Network binding address
bind=0.0.0.0

# Client connection idle timeout (seconds)
client_timeout=600

# Maximum worker threads
# Default: CPU core count
max_workers=

# System locale
# Default: OS setting
locale=

User login (note: this is optional). After success, a token will be provided.
Context operations or SQL access that requires context variables will require token.
If your program does not involve context feature, you can ignore this login.
Put it simplify, the token is currently used as the user ID.

Response example:

User logout

headers:

The token information here is obtained when call /login in earlier

Response example:

set context

headers:

The token information here is obtained when call /login in earlier

request body:

You can set one or more key-value pairs at once, or you can set multiple key-value pairs by calling setContext multiple times.

Response example:

remove context

headers:

The token information here is obtained when call /login in earlier

request body:

You can remove one or more key-value pairs at once, or you can remove multiple key-value pairs by calling removeContext multiple times.

Response example:

register a service

request body:

snapshotLimit format: 3 hours / 30 minutes / 45 seconds

Request example:

Response example:

unregister a service

request body:

Request example:

Response example:

list all service

Response example:

API query

headers:

The token information here is obtained when call /login.
The token is optional, if you use context in your sql statement, you must set it.
snapshotLimit format: 3 hours / 30 minutes / 45 seconds

GET Request example:

POST Request example:

Response example:

Connect to the WebSocket endpoint:

Once connected, you can send JSON messages with the following general format:

The server will respond with a JSON message that mirrors the request id and includes a retCode (0 for success, non‑zero for error) and relevant data.

A session is created by sending a start message. The server returns a sessionId that must be included in subsequent messages for the same session.

Start message:

Response:

All further messages for this session must include "sessionId": "session-123" in their data field.

Submits a SQL statement for asynchronous execution. Returns a task ID that can be used to fetch results later.

Message:

Response:

If the SQL execution fails immediately (e.g., syntax error), the response will contain retCode != 0 and an error message.

Retrieves a page of results for a given task ID. The endpoint returns a fixed number of rows (up to maxRows specified in execute) and indicates whether more rows are available.

Message:

Response:

If the task is still running (status = “running”), dataset may be empty and hasMore will be true. If the task has completed and all rows have been fetched, status becomes “completed” and hasMore false. If an error occurs during execution, status becomes “error” and retMsg contains the error details.

You can send multiple fetch messages until hasMore becomes false. Each call returns the next page of rows.

Cancels an ongoing SQL task. If no taskId is provided, cancels the current session’s active task.

Message:

Response:

Closes the session and releases all associated resources (including any pending tasks).

Message:

Response:

After closing, the session ID is no longer valid.

1. Connect to WebSocket endpoint:

   const WebSocket = require('ws');
   const ws = new WebSocket('ws://localhost:8080/sql/ws');

2. Create a session:

   ws.send(JSON.stringify({
     id: "1",
     type: "start",
     data: {}
   }));

3. Execute a long query:

   ws.send(JSON.stringify({
     id: "2",
     type: "exec",
     data: {
       sessionId: "session-123",
       sql: "SELECT * FROM huge_table",
       maxRows: 500
     }
   }));

4. Fetch first page:

   ws.send(JSON.stringify({
     id: "3",
     type: "fetch",
     data: {
       sessionId: "session-123",
       taskId: "abc123",
       maxRows: 100
     }
   }));

5. Fetch subsequent pages until hasMore becomes false.

6. Optionally cancel if needed:

   ws.send(JSON.stringify({
     id: "4",
     type: "cancel",
     data: {
       sessionId: "session-123",
       taskId: "abc123"
     }
   }));

7. Close the session when done:

   ws.send(JSON.stringify({
     id: "5",
     type: "close",
     data: {
       sessionId: "session-123"
     }
   }));

Note: The examples above assume you handle incoming messages asynchronously. In a real client you would match responses by their id.

Performs a database backup. The backup file is saved in the backup/ directory with the naming pattern {database}_{backupTag}.db.

Downloads a file from the server’s working directory.

• filename (required) – relative path to the file.

The endpoint supports Range requests for partial downloads.

Uploads a file to the server’s working directory.

• filename (required) – target file path.

• file (required) – the file to upload.

Retrieves the last N lines of a log file.

• filename (required) – path to the log file.

• lines (optional) – number of lines to return (default 100, max 10000).

Returns comprehensive server status information, including server details, database metrics, configuration parameters, usage statistics, installed extensions, and active sessions.

  // create configuration,  and update as your need
  ServerConfiguration serverConfiguration = new ServerConfiguration();
  serverConfiguration1.setPort(4309);
  serverConfiguration1.setData("data1");

  // init database
  DBInstance dbInstance= new DBInstance(serverConfiguration1);

  // startup database
  dbInstance1.start();

  // shutdown database
  dbInstance.stop();

  // We currently supports starting multiple instances running at the same time.
  // But each instance must have his own port and instance name.

    ServerConfiguration proxyConfiguration = new ServerConfiguration();
    proxyConfiguration.setPort(dbPort);
    ProxyInstance proxyInstance = new ProxyInstance(proxyConfiguration);
    proxyInstance.start();

    // Waiting for server ready
    while (!proxyInstance.instanceState.equalsIgnoreCase("RUNNING")) {
        Sleeper.sleep(1000);
    }

    // "db1" is your database name in your configuration file.
    // 3175  is your database port in your configuration file.
    // If you are connecting for the first time, there will be no other users except the default main
    String  connectURL = "jdbc:postgresql://127.0.0.1:3175/db1";
    Connection pgConn = DriverManager.getConnection(connectURL, "main", "");
    pgConn.setAutoCommit(false);

    // .... Now you can execute your business logic.

    // "db1" is your database name in your configuration file.
    // 3175  is your database port in your configuration file.
    // If you are connecting for the first time, there will be no other users except the default main
    String  connectURL = "jdbc:slackerdb://127.0.0.1:3175/db1";
    Connection pgConn = DriverManager.getConnection(connectURL, "main", "");
    pgConn.setAutoCommit(false);

    // .... Now you can execute your business logic.

    It also supports ODBC and Python connection.