mirror of
https://github.com/tauri-apps/plugins-workspace.git
synced 2026-11-17 23:54:01 +01:00
Merge remote-tracking branch 'origin/v2' into v3
This commit is contained in:
293 files changed
+18770
-1486
No files matched your search
@@ -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.
|
||||
|
||||
@@ -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', {
|
||||
|
||||
@@ -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};
|
||||
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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;
|
||||
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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
@@ -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![
|
||||
|
||||
@@ -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,
|
||||
}
|
||||
|
||||
Reference in new issue
Block a user