Skip to content

Support running an SQL file on init (1.3)#275

Merged
staticlibs merged 1 commit intoduckdb:v1.3-ossivalisfrom
staticlibs:session_init_file_13
Jun 16, 2025
Merged

Support running an SQL file on init (1.3)#275
staticlibs merged 1 commit intoduckdb:v1.3-ossivalisfrom
staticlibs:session_init_file_13

Conversation

@staticlibs
Copy link
Collaborator

This is a backport of the PR #252 to v1.3-ossivalis stable branch.

This change adds support for session_init_sql_file connection option, that allows to speficy the path to an SQL file in local file system, that will be read by the driver and executed in a newly created connection before passing it to user.

By default the file is initalized only once per database, on the first connection established to this DB.

For :memory: connection-private DBs it effectively executed once per connection.

In addition to the DB init, it supports executing a part of the SQL file for every connection. It looks for the specific marker:

/* DUCKDB_CONNECTION_INIT_BELOW_MARKER */

in the SQL file. If this marker is present - everything before the marker is executed on DB init, and everything after this marker - on connection init.

DB init is not re-run when the DB is closed and re-opened after the last connection to it was closed and then new one created. If such re-init is necessary - jdbc_pin_db option is supposed to be used instead.

It is understood, that this feature can be security sensitive (it effectively implements an RCE entry) in contexts, where other applications/processes/users can control the appending to user-specified connection string or re-writing the specified file in local file system. The following security measures are taken to mitigate that:

  • session_init_sql_file option can only be specified in the connection string itself, it is not accepted as part of connection Properties
  • session_init_sql_file option must be specified as the first option in the connection string, for example: 'jdbc:duckdb:;session_init_sql_file=/path/to/init.sql'
  • session_init_sql_file_sha256=<sha56sum_of_sql_file> option can be specified, the file contents SHA-256 sum is checked againts this value
  • session_init_sql_file_sha256 option can only be specified in the connection string itself
  • session_init_sql_file and session_init_sql_file_sha256 options cannot be specified multiple times
  • content of the SQL file are available to the running code using DuckDBConnection#getSessionInitSQL() method

Testing: new tests added in a separate file.

This is a backport of the PR duckdb#252 to `v1.3-ossivalis` stable branch.

This change adds support for `session_init_sql_file` connection option,
that allows to speficy the path to an SQL file in local file system,
that will be read by the driver and executed in a newly created
connection before passing it to user.

By default the file is initalized only once per database, on the first
connection established to this DB.

For `:memory:` connection-private DBs it effectively executed once per
connection.

In addition to the DB init, it supports executing a part of the SQL
file for every connection. It looks for the specific marker:

```
/* DUCKDB_CONNECTION_INIT_BELOW_MARKER */
```

in the SQL file. If this marker is present - everything before the
marker is executed on DB init, and everything after this marker - on
connection init.

DB init is not re-run when the DB is closed and re-opened after the last
connection to it was closed and then new one created. If such re-init is
necessary - `jdbc_pin_db` option is supposed to be used instead.

It is understood, that this feature can be security sensitive (it
effectively implements an RCE entry) in contexts, where other
applications/processes/users can control the appending to user-specified
connection string or re-writing the specified file in local file system.
The following security measures are taken to mitigate that:

 - `session_init_sql_file` option can only be specified in the
   connection string itself, it is not accepted as part of connection
   `Properties`
 - `session_init_sql_file` option must be specified as the first option
   in the connection string, for example:
   'jdbc:duckdb:;session_init_sql_file=/path/to/init.sql'
 - `session_init_sql_file_sha256=<sha56sum_of_sql_file>` option can be
   specified, the file contents SHA-256 sum is checked againts this
   value
 - `session_init_sql_file_sha256` option can only be specified in the
   connection string itself
 - `session_init_sql_file` and `session_init_sql_file_sha256` options
   cannot be specified multiple times
 - content of the SQL file are available to the running code using
   `DuckDBConnection#getSessionInitSQL()` method

Testing: new tests added in a separate file.
@staticlibs staticlibs merged commit 89e93bc into duckdb:v1.3-ossivalis Jun 16, 2025
@staticlibs staticlibs deleted the session_init_file_13 branch June 16, 2025 00:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant