From 4a0b786446429f8e629790a0e6b0c5e2a9cd1a6b Mon Sep 17 00:00:00 2001 From: Naman Garg Date: Tue, 5 Mar 2024 05:10:06 +0530 Subject: [PATCH 1/5] Add install Core plugin --- src/content/docs/features/sql.mdx | 34 ++++++++++++++++++++++++++----- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/src/content/docs/features/sql.mdx b/src/content/docs/features/sql.mdx index d6a0ac823d..dbbc84844b 100644 --- a/src/content/docs/features/sql.mdx +++ b/src/content/docs/features/sql.mdx @@ -1,13 +1,37 @@ --- title: SQL -description: Interface with SQL databases. +description: Tauri Plugin providing an interface for the frontend to communicate with SQL databases through sqlx. --- -import Stub from '@components/Stub.astro'; import PluginLinks from '@components/PluginLinks.astro'; +import { Tabs, TabItem } from '@astrojs/starlight/components'; +import CommandTabs from '@components/CommandTabs.astro'; - - Based on https://github.com/tauri-apps/plugins-workspace/tree/v2/plugins/sql - +Plugin providing an interface for the frontend to communicate with SQL databases through [sqlx](https://github.com/launchbadge/sqlx). It supports the SQLite, MySQL and PostgreSQL drivers, enabled by a Cargo feature. + +## Install + +_This plugin requires a Rust version of at least **1.75**_ + +Firstly, you have to install Core plugin by adding the following to your `Cargo.toml` file: + + + +```toml title="src-tauri/Cargo.toml" +[dependencies.tauri-plugin-sql] +features = ["sqlite"] # or "postgres", or "mysql" +version = "2.0.0-beta" +``` + + + +```toml title="src-tauri/Cargo.toml" +[dependencies.tauri-plugin-sql] +features = ["sqlite"] # or "postgres", or "mysql" +git = "https://github.com/tauri-apps/plugins-workspace" +branch = "v2" +``` + + From f565f4c21d1d7372fa51f4e2d631171a2adee600 Mon Sep 17 00:00:00 2001 From: Naman Garg Date: Tue, 5 Mar 2024 21:36:13 +0530 Subject: [PATCH 2/5] Add Usage Section --- src/content/docs/features/sql.mdx | 89 +++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/src/content/docs/features/sql.mdx b/src/content/docs/features/sql.mdx index dbbc84844b..87cd31adb9 100644 --- a/src/content/docs/features/sql.mdx +++ b/src/content/docs/features/sql.mdx @@ -35,3 +35,92 @@ branch = "v2" ``` + +Then, you have to add JavaScript Guest bindings using your preferred JavaScript package manager. + + + + + + ```shell + pnpm add @tauri-apps/plugin-sql + ``` + + + ```shell + npm add @tauri-apps/plugin-sql + ``` + + + ```shell + yarn add @tauri-apps/plugin-sql + ``` + + + + + + + + ```shell + pnpm add https://github.com/tauri-apps/tauri-plugin-sql#v2 + ``` + + + ```shell + npm add https://github.com/tauri-apps/tauri-plugin-sql#v2 + ``` + + + ```shell + yarn add https://github.com/tauri-apps/tauri-plugin-sql#v2 + ``` + + + + + +## Usage + +First you need to register the core plugin with Tauri: + +```rust title="src-tauri/Cargo.toml" ins={3} +fn main() { + tauri::Builder::default() + .plugin(tauri_plugin_sql::Builder::default().build()) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); +} +``` + +Afterwards all the plugin's APIs are available through the JavaScript guest bindings: + + + +```javascript + +import Database from "@tauri-apps/plugin-sql"; +const db = await Database.load("sqlite:test.db"); +await db.execute("INSERT INTO ..."); + +``` + + +```javascript + +import Database from "@tauri-apps/plugin-sql"; +const db = await Database.load("mysql://user:pass@host/database"); +await db.execute("INSERT INTO ..."); + +``` + + +```javascript + +import Database from "@tauri-apps/plugin-sql"; +const db = await Database.load("postgres://postgres:password@localhost/test"); +await db.execute("INSERT INTO ..."); + +``` + + From 71d3194ba9933c292b5a2bd14cc0c2771b6c463d Mon Sep 17 00:00:00 2001 From: Naman Garg Date: Wed, 6 Mar 2024 03:40:40 +0530 Subject: [PATCH 3/5] Finalise SQL doc --- src/content/docs/features/sql.mdx | 114 +++++++++++++++++++++++++++++- 1 file changed, 113 insertions(+), 1 deletion(-) diff --git a/src/content/docs/features/sql.mdx b/src/content/docs/features/sql.mdx index 87cd31adb9..a64081f9dd 100644 --- a/src/content/docs/features/sql.mdx +++ b/src/content/docs/features/sql.mdx @@ -84,7 +84,7 @@ Then, you have to add JavaScript Guest bindings using your preferred JavaScript First you need to register the core plugin with Tauri: -```rust title="src-tauri/Cargo.toml" ins={3} +```rust title="src-tauri/src/main.rs" ins={3} fn main() { tauri::Builder::default() .plugin(tauri_plugin_sql::Builder::default().build()) @@ -97,6 +97,8 @@ Afterwards all the plugin's APIs are available through the JavaScript guest bind + +The path is relative to `tauri::api::path::BaseDirectory::App` ```javascript import Database from "@tauri-apps/plugin-sql"; @@ -124,3 +126,113 @@ await db.execute("INSERT INTO ..."); ``` + +## Syntax + +We use [sqlx](https://docs.rs/sqlx/latest/sqlx/) as the underlying library and adopt their query syntax. + + + +Use the "$#" syntax when substituting query data +```javascript +const result = await db.execute( + "INSERT into todos (id, title, status) VALUES ($1, $2, $3)", + [todos.id, todos.title, todos.status], +); + +const result = await db.execute( + "UPDATE todos SET title = $1, completed = $2 WHERE id = $3", + [todos.title, todos.status, todos.id], +); +``` + + +Use "?" when substituting query data +```javascript +const result = await db.execute( + "INSERT into todos (id, title, status) VALUES (?, ?, ?)", + [todos.id, todos.title, todos.status], +); + +const result = await db.execute( + "UPDATE todos SET title = ?, completed = ? WHERE id = ?", + [todos.title, todos.status, todos.id], +); +``` + + +Use the "$#" syntax when substituting query data +```javascript +const result = await db.execute( + "INSERT into todos (id, title, status) VALUES ($1, $2, $3)", + [todos.id, todos.title, todos.status], +); + +const result = await db.execute( + "UPDATE todos SET title = $1, completed = $2 WHERE id = $3", + [todos.title, todos.status, todos.id], +); +``` + + + +## Migrations + +This plugin supports database migrations, allowing you to manage database schema evolution over time. + +### Defining Migrations + +Migrations are defined in Rust using the [`Migration`](https://docs.rs/tauri-plugin-sql/latest/tauri_plugin_sql/struct.Migration.html) struct. Each migration should include a unique version number, a description, the SQL to be executed, and the type of migration (Up or Down). + +Example of a migration: + +```rust +use tauri_plugin_sql::{Migration, MigrationKind}; + +let migration = Migration { + version: 1, + description: "create_initial_tables", + sql: "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);", + kind: MigrationKind::Up, +}; +``` + +### Adding Migrations to the Plugin Builder + +Migrations are registered with the [`Builder`](https://docs.rs/tauri-plugin-sql/latest/tauri_plugin_sql/struct.Builder.html) struct provided by the plugin. Use the `add_migrations` method to add your migrations to the plugin for a specific database connection. + +Example of adding migrations: + +```rust title="src-tauri/src/main.rs" {1} {6-11} {17} +use tauri_plugin_sql::{Builder, Migration, MigrationKind}; + +fn main() { + let migrations = vec![ + // Define your migrations here + Migration { + version: 1, + description: "create_initial_tables", + sql: "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);", + kind: MigrationKind::Up, + } + ]; + + tauri::Builder::default() + .plugin( + tauri_plugin_sql::Builder::default() + .add_migrations("sqlite:mydatabase.db", migrations) + .build(), + ) + ... +} +``` + +### Applying Migrations + +Migrations are applied automatically when the plugin is initialized. The plugin runs these migrations against the database specified by the connection string. Ensure that the migrations are defined in the correct order and are idempotent (safe to run multiple times). + +### Migration Management + +- **Version Control**: Each migration must have a unique version number. This is crucial for ensuring the migrations are applied in the correct order. +- **Idempotency**: Write migrations in a way that they can be safely re-run without causing errors or unintended consequences. +- **Testing**: Thoroughly test migrations to ensure they work as expected and do not compromise the integrity of your database. From b5d45939267ab29b6ed4d74eef9203be2e662292 Mon Sep 17 00:00:00 2001 From: Naman Garg Date: Wed, 6 Mar 2024 04:13:40 +0530 Subject: [PATCH 4/5] Replace Tabs with CommandTabs --- src/content/docs/features/sql.mdx | 45 +++++++------------------------ 1 file changed, 10 insertions(+), 35 deletions(-) diff --git a/src/content/docs/features/sql.mdx b/src/content/docs/features/sql.mdx index a64081f9dd..538fba5fac 100644 --- a/src/content/docs/features/sql.mdx +++ b/src/content/docs/features/sql.mdx @@ -40,43 +40,18 @@ Then, you have to add JavaScript Guest bindings using your preferred JavaScript - - - ```shell - pnpm add @tauri-apps/plugin-sql - ``` - - - ```shell - npm add @tauri-apps/plugin-sql - ``` - - - ```shell - yarn add @tauri-apps/plugin-sql - ``` - - - + - - - ```shell - pnpm add https://github.com/tauri-apps/tauri-plugin-sql#v2 - ``` - - - ```shell - npm add https://github.com/tauri-apps/tauri-plugin-sql#v2 - ``` - - - ```shell - yarn add https://github.com/tauri-apps/tauri-plugin-sql#v2 - ``` - - + From 9337fbbb74ec5ef8b086b53c88c4d561ff1316f9 Mon Sep 17 00:00:00 2001 From: Lucas Fernandes Nogueira Date: Thu, 7 Mar 2024 09:21:57 -0300 Subject: [PATCH 5/5] Apply suggestions from code review --- src/content/docs/features/sql.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/features/sql.mdx b/src/content/docs/features/sql.mdx index 538fba5fac..c4d410109f 100644 --- a/src/content/docs/features/sql.mdx +++ b/src/content/docs/features/sql.mdx @@ -116,7 +116,7 @@ const result = await db.execute( ); const result = await db.execute( - "UPDATE todos SET title = $1, completed = $2 WHERE id = $3", + "UPDATE todos SET title = $1, status = $2 WHERE id = $3", [todos.title, todos.status, todos.id], ); ``` @@ -130,7 +130,7 @@ const result = await db.execute( ); const result = await db.execute( - "UPDATE todos SET title = ?, completed = ? WHERE id = ?", + "UPDATE todos SET title = ?, status = ? WHERE id = ?", [todos.title, todos.status, todos.id], ); ``` @@ -144,7 +144,7 @@ const result = await db.execute( ); const result = await db.execute( - "UPDATE todos SET title = $1, completed = $2 WHERE id = $3", + "UPDATE todos SET title = $1, status = $2 WHERE id = $3", [todos.title, todos.status, todos.id], ); ```