Merge remote-tracking branch 'origin/v2' into v3

This commit is contained in:
Lucas Nogueira committed 2026-09-26 18:40:12 -03:00
commit 8caf15bc38
293 files changed
+18770 -1486

No files matched your search

+6
View File
@@ -8,6 +8,12 @@
- [`363438b5`](https://github.com/tauri-apps/plugins-workspace/commit/363438b50a09162379d57c7c7bfc132520c1e5d4) Update to tauri 3.0 alpha.
## [2.5.0]
- [`ae3c808e`](https://github.com/tauri-apps/plugins-workspace/commit/ae3c808eb60086f32b1d67bb8ccc525b95333e77) ([#3602](https://github.com/tauri-apps/plugins-workspace/pull/3602)) The plugin's global API script (used with `app.withGlobalTauri`) now resolves the core API from `window.__TAURI__` instead of bundling its own copy of `@tauri-apps/api`. Values created with the core API are now accepted by plugin APIs in global mode (e.g. an `Image` from `window.__TAURI__.image` passed to `clipboardManager.writeImage`, which previously failed the `instanceof` check against the plugin's private copy), and the script is considerably smaller.
- [`9b29b601`](https://github.com/tauri-apps/plugins-workspace/commit/9b29b601f387ded1f4adb4386623a3c035a5598c) Update MSRV to 1.90 to match tauri.
- [`a87a3c7d`](https://github.com/tauri-apps/plugins-workspace/commit/a87a3c7d4491bf25589a0b24c285fcd5df3d6337) Update documentation.
## [2.4.1]
- [`f8053e65`](https://github.com/tauri-apps/plugins-workspace/commit/f8053e659e4ccd85c1f52833411ff8417cbc5e69) ([#3527](https://github.com/tauri-apps/plugins-workspace/pull/3527) by [@Legend-Master](https://github.com/tauri-apps/plugins-workspace/../../Legend-Master)) Documented Cargo feature flags in each plugin's crate-level documentation.
+65 -7
View File
@@ -2,8 +2,19 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-License-Identifier: MIT
/**
* Interface with SQL databases through [sqlx](https://github.com/launchbadge/sqlx).
* Which database engines can be used depends on the drivers enabled on the Rust
* side of the plugin: SQLite, MySQL and PostgreSQL.
*
* @module
*/
import { invoke } from '@tauri-apps/api/core'
/**
* The outcome of a statement run through {@link Database.execute}.
*/
export interface QueryResult {
/** The number of rows affected by the query. */
rowsAffected: number
@@ -23,9 +34,30 @@ export interface QueryResult {
*
* The `Database` class serves as the primary interface for
* communicating with the rust side of the sql plugin.
*
* @since 2.0.0
*/
export default class Database {
/**
* The connection string identifying the database on the Rust side,
* for instance `sqlite:test.db`, `mysql://user:pass@host/database`
* or `postgres://user:pass@host/database`.
*/
path: string
/**
* Creates a `Database` instance for the given connection string without
* opening a connection to it. Use {@link Database.load} to connect to the
* database, or {@link Database.get} for a database that is already loaded.
*
* @param path The database connection string, such as `sqlite:test.db`.
*
* @example
* ```typescript
* import Database from '@tauri-apps/plugin-sql'
* const db = new Database('sqlite:test.db')
* ```
*/
constructor(path: string) {
this.path = path
}
@@ -41,9 +73,13 @@ export default class Database {
* The path is relative to `tauri::path::BaseDirectory::App` and must start with `sqlite:`.
*
* @example
* ```ts
* const db = await Database.load("sqlite:test.db");
* ```typescript
* import Database from '@tauri-apps/plugin-sql'
* const db = await Database.load('sqlite:test.db')
* ```
*
* @param path The database connection string, such as `sqlite:test.db`. The database is created if it does not exist yet, and any migration registered for it on the Rust side is run.
* @returns A promise resolving to a `Database` instance connected to the given database.
*/
static async load(path: string): Promise<Database> {
const _path = await invoke<string>('plugin:sql|load', {
@@ -65,9 +101,13 @@ export default class Database {
* The path is relative to `tauri::path::BaseDirectory::App` and must start with `sqlite:`.
*
* @example
* ```ts
* const db = Database.get("sqlite:test.db");
* ```typescript
* import Database from '@tauri-apps/plugin-sql'
* const db = Database.get('sqlite:test.db')
* ```
*
* @param path The database connection string, such as `sqlite:test.db`.
* @returns A `Database` instance bound to the given connection string.
*/
static get(path: string): Database {
return new Database(path)
@@ -79,7 +119,10 @@ export default class Database {
* Passes a SQL expression to the database for execution.
*
* @example
* ```ts
* ```typescript
* import Database from '@tauri-apps/plugin-sql'
* const db = await Database.load('sqlite:test.db')
*
* // for sqlite & postgres
* // INSERT example
* const result = await db.execute(
@@ -104,6 +147,10 @@ export default class Database {
* [ todos.title, todos.status, todos.id ]
* );
* ```
*
* @param query The SQL statement to run, using `$1`, `$2`, ... placeholders on SQLite and PostgreSQL and `?` placeholders on MySQL.
* @param bindValues The values bound to the query placeholders, in the order they appear in the statement. Defaults to no values.
* @returns A promise resolving to the number of rows affected by the statement and the last inserted id.
*/
async execute(query: string, bindValues?: unknown[]): Promise<QueryResult> {
const [rowsAffected, lastInsertId] = await invoke<[number, number]>(
@@ -126,7 +173,10 @@ export default class Database {
* Passes in a SELECT query to the database for execution.
*
* @example
* ```ts
* ```typescript
* import Database from '@tauri-apps/plugin-sql'
* const db = await Database.load('sqlite:test.db')
*
* // for sqlite & postgres
* const result = await db.select(
* "SELECT * from todos WHERE id = $1", [ id ]
@@ -137,6 +187,10 @@ export default class Database {
* "SELECT * from todos WHERE id = ?", [ id ]
* );
* ```
*
* @param query The SQL query to run, using `$1`, `$2`, ... placeholders on SQLite and PostgreSQL and `?` placeholders on MySQL.
* @param bindValues The values bound to the query placeholders, in the order they appear in the query. Defaults to no values.
* @returns A promise resolving to the selected rows, each row being an object keyed by column name.
*/
async select<T>(query: string, bindValues?: unknown[]): Promise<T> {
const result = await invoke<T>('plugin:sql|select', {
@@ -154,10 +208,14 @@ export default class Database {
* Closes the database connection pool.
*
* @example
* ```ts
* ```typescript
* import Database from '@tauri-apps/plugin-sql'
* const db = await Database.load('sqlite:test.db')
* const success = await db.close()
* ```
*
* @param db - Optionally state the name of a database if you are managing more than one. Otherwise, all database pools will be in scope.
* @returns A promise resolving to `true` once the matching connection pools have been closed.
*/
async close(db?: string): Promise<boolean> {
const success = await invoke<boolean>('plugin:sql|close', {
+1 -1
View File
@@ -5,7 +5,7 @@
use indexmap::IndexMap;
use serde_json::Value as JsonValue;
use sqlx::migrate::Migrator;
use tauri::{command, AppHandle, Runtime, State};
use tauri::{AppHandle, Runtime, State, command};
use crate::{DbInstances, DbPool, Error, LastInsertId, Migrations};
+1 -1
View File
@@ -3,7 +3,7 @@
// SPDX-License-Identifier: MIT
use serde_json::Value as JsonValue;
use sqlx::{mysql::MySqlValueRef, TypeInfo, Value, ValueRef};
use sqlx::{TypeInfo, Value, ValueRef, mysql::MySqlValueRef};
use time::{Date, OffsetDateTime, PrimitiveDateTime, Time};
use crate::Error;
+1 -1
View File
@@ -4,7 +4,7 @@
use rust_decimal::prelude::ToPrimitive;
use serde_json::Value as JsonValue;
use sqlx::{postgres::PgValueRef, TypeInfo, Value, ValueRef};
use sqlx::{TypeInfo, Value, ValueRef, postgres::PgValueRef};
use time::{Date, OffsetDateTime, PrimitiveDateTime, Time};
use uuid::Uuid;
+1 -1
View File
@@ -3,7 +3,7 @@
// SPDX-License-Identifier: MIT
use serde_json::Value as JsonValue;
use sqlx::{sqlite::SqliteValueRef, TypeInfo, Value, ValueRef};
use sqlx::{TypeInfo, Value, ValueRef, sqlite::SqliteValueRef};
use time::{Date, PrimitiveDateTime, Time};
use crate::Error;
+14
View File
@@ -4,16 +4,30 @@
use serde::{Serialize, Serializer};
/// Errors that can happen while connecting to a database, running migrations
/// or executing a query.
///
/// Serializes to its [`std::fmt::Display`] representation, which is what the
/// frontend receives when a command fails.
#[derive(Debug, thiserror::Error)]
pub enum Error {
/// An error reported by [`sqlx`], such as a failed connection or a query the database rejected.
#[error(transparent)]
Sql(#[from] sqlx::Error),
/// A migration registered with [`crate::Builder::add_migrations`] could not be resolved or applied.
#[error(transparent)]
Migration(#[from] sqlx::migrate::MigrateError),
/// The connection string is missing its `scheme:` prefix, or the scheme does not
/// match any of the enabled database drivers. Contains the offending connection string.
#[error("invalid connection url: {0}")]
InvalidDbUrl(String),
/// The requested database has not been connected to with the `load` command
/// and is not listed in the plugin's `preload` configuration.
/// Contains the connection string of the database.
#[error("database {0} not loaded")]
DatabaseNotLoaded(String),
/// A value selected from the database has a SQL type that cannot be converted
/// to JSON. Contains the name of that SQL type.
#[error("unsupported datatype: {0}")]
UnsupportedDatatype(String),
}
+60 -2
View File
@@ -33,13 +33,18 @@ use sqlx::{
migrate::{Migration as SqlxMigration, MigrationSource, MigrationType, Migrator},
};
use tauri::{
plugin::{Builder as PluginBuilder, TauriPlugin},
Manager, RunEvent, Runtime,
plugin::{Builder as PluginBuilder, TauriPlugin},
};
use tokio::sync::{Mutex, RwLock};
use std::collections::HashMap;
/// The connection pools the plugin currently holds, keyed by the connection
/// string the database was loaded with.
///
/// It is managed as Tauri state, so Rust code can reach the pools with
/// [`tauri::Manager::state`] and run its own queries.
#[derive(Default)]
pub struct DbInstances(pub RwLock<HashMap<String, DbPool>>);
@@ -58,15 +63,22 @@ pub(crate) enum LastInsertId {
struct Migrations(Mutex<HashMap<String, MigrationList>>);
/// The `plugins > sql` section of the Tauri configuration file.
#[derive(Default, Clone, Deserialize)]
pub struct PluginConfig {
/// Connection strings of the databases to connect to when the application
/// starts. Empty by default.
#[serde(default)]
preload: Vec<String>,
}
/// The direction of a [`Migration`].
#[derive(Debug)]
pub enum MigrationKind {
/// Moves the schema forward. Only migrations of this kind are executed by the plugin.
Up,
/// Reverts an [`Up`](Self::Up) migration. Migrations of this kind are currently
/// never executed by the plugin.
Down,
}
@@ -80,11 +92,23 @@ impl From<MigrationKind> for MigrationType {
}
/// A migration definition.
///
/// Migrations are attached to a database with [`Builder::add_migrations`] and run
/// the first time that database is connected to - on startup for the databases
/// listed in the `preload` configuration, otherwise when the frontend loads it.
/// Only [`MigrationKind::Up`] migrations are executed, in ascending
/// [`version`](Self::version) order, and sqlx keeps track of the versions that
/// already ran so each one is applied at most once per database.
#[derive(Debug)]
pub struct Migration {
/// The version of this migration. Determines the order in which migrations
/// run and identifies the migration in the database.
pub version: i64,
/// A human readable description of what the migration does.
pub description: &'static str,
/// The SQL executed when the migration runs.
pub sql: &'static str,
/// Whether this migration moves the schema forward or reverts it.
pub kind: MigrationKind,
}
@@ -127,9 +151,16 @@ pub struct Builder {
}
impl Builder {
/// Creates a new builder with no migrations registered.
///
/// Prints a message to stderr when none of the `sqlite`, `mysql` and
/// `postgres` Cargo features is enabled, since no database can be
/// connected to in that case.
pub fn new() -> Self {
#[cfg(not(any(feature = "sqlite", feature = "mysql", feature = "postgres")))]
eprintln!("No sql driver enabled. Please set at least one of the \"sqlite\", \"mysql\", \"postgres\" feature flags.");
eprintln!(
"No sql driver enabled. Please set at least one of the \"sqlite\", \"mysql\", \"postgres\" feature flags."
);
Self::default()
}
@@ -143,6 +174,33 @@ impl Builder {
self
}
/// Builds the SQL plugin.
///
/// On setup the plugin connects to every database listed in the `preload`
/// array of its [configuration](PluginConfig), running the migrations
/// registered for them, and it closes all connection pools when the
/// application exits.
///
/// # Examples
///
/// ```
/// use tauri_plugin_sql::{Builder, Migration, MigrationKind};
///
/// fn sql_plugin<R: tauri::Runtime>(
/// ) -> tauri::plugin::TauriPlugin<R, Option<tauri_plugin_sql::PluginConfig>> {
/// Builder::new()
/// .add_migrations(
/// "sqlite:mydatabase.db",
/// vec![Migration {
/// version: 1,
/// description: "create todos table",
/// sql: "CREATE TABLE todos (id INTEGER PRIMARY KEY, title TEXT);",
/// kind: MigrationKind::Up,
/// }],
/// )
/// .build()
/// }
/// ```
pub fn build<R: Runtime>(mut self) -> TauriPlugin<R, Option<PluginConfig>> {
PluginBuilder::<R, Option<PluginConfig>>::new("sql")
.invoke_handler(tauri::generate_handler![
+11 -1
View File
@@ -8,7 +8,7 @@ use std::fs::create_dir_all;
use indexmap::IndexMap;
use serde_json::Value as JsonValue;
#[cfg(any(feature = "sqlite", feature = "mysql", feature = "postgres"))]
use sqlx::{migrate::MigrateDatabase, Column, Executor, Pool, Row};
use sqlx::{Column, Executor, Pool, Row, migrate::MigrateDatabase};
#[cfg(any(feature = "sqlite", feature = "mysql", feature = "postgres"))]
use tauri::Manager;
use tauri::{AppHandle, Runtime};
@@ -22,13 +22,23 @@ use sqlx::Sqlite;
use crate::LastInsertId;
/// A connection pool for one of the supported database drivers.
///
/// The variant is picked from the scheme of the connection string
/// (`sqlite:`, `mysql:` or `postgres:`) and only the variants whose Cargo
/// feature is enabled exist.
pub enum DbPool {
/// A SQLite connection pool. Only available with the `sqlite` Cargo feature.
#[cfg(feature = "sqlite")]
Sqlite(Pool<Sqlite>),
/// A MySQL connection pool. Only available with the `mysql` Cargo feature.
#[cfg(feature = "mysql")]
MySql(Pool<MySql>),
/// A PostgreSQL connection pool. Only available with the `postgres` Cargo feature.
#[cfg(feature = "postgres")]
Postgres(Pool<Postgres>),
/// Placeholder used when none of the `sqlite`, `mysql` and `postgres` Cargo
/// features is enabled. Connecting always fails and every other operation is a no-op.
#[cfg(not(any(feature = "sqlite", feature = "mysql", feature = "postgres")))]
None,
}