├── .github └── workflows │ └── main.yml ├── README.md ├── example-world.md ├── test └── README.md └── wit ├── deps └── example-dep │ └── example-api.wit ├── example.wit └── world.wit /.github/workflows/main.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | on: 3 | push: 4 | branches: [main] 5 | pull_request: 6 | branches: [main] 7 | 8 | jobs: 9 | abi-up-to-date: 10 | name: Check ABI files are up-to-date 11 | runs-on: ubuntu-latest 12 | steps: 13 | - uses: actions/checkout@v2 14 | - uses: WebAssembly/wit-abi-up-to-date@v12 15 | with: 16 | wit-abi-tag: wit-abi-0.10.0 17 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # WASI SQL Embedding 2 | 3 | A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API. 4 | 5 | ### Current Phase 6 | 7 | WASI SQL Embedding is currently in [Phase 1](https://github.com/WebAssembly/WASI/blob/main/Proposals.md#phase-1---feature-proposal-cg). 8 | 9 | ### Champions 10 | 11 | - Robin Brown 12 | 13 | ### Phase 4 Advancement Criteria 14 | 15 | TODO before entering Phase 2. 16 | 17 | ## Table of Contents [if the explainer is longer than one printed page] 18 | 19 | - [Introduction](#introduction) 20 | - [Goals [or Motivating Use Cases, or Scenarios]](#goals-or-motivating-use-cases-or-scenarios) 21 | - [Non-goals](#non-goals) 22 | - [API walk-through](#api-walk-through) 23 | - [Use case 1](#use-case-1) 24 | - [Use case 2](#use-case-2) 25 | - [Detailed design discussion](#detailed-design-discussion) 26 | - [[Tricky design choice 1]](#tricky-design-choice-1) 27 | - [[Tricky design choice 2]](#tricky-design-choice-2) 28 | - [Considered alternatives](#considered-alternatives) 29 | - [[Alternative 1]](#alternative-1) 30 | - [[Alternative 2]](#alternative-2) 31 | - [Stakeholder Interest & Feedback](#stakeholder-interest--feedback) 32 | - [References & acknowledgements](#references--acknowledgements) 33 | 34 | ### Introduction 35 | 36 | WASI SQL Embedding defines a way for WASM components to be embedded in SQL databases as extensions. 37 | It defines the interfaces for various user objects (like User-Defined Functions a.k.a. UDFs) that can be exported by extensions and called from the database, the way component value types and SQL column types are mapped, and the facilities user objects are allowed to access/use. 38 | 39 | WASI SQL Embedding abstracts over different SQL dialects and their types. 40 | Extensions may either explicitly call out the SQL types of their arguments and results or allow them to be inferred. 41 | If an Extension refers to a SQL type that is not supported by a given dialect, the embedder may decide to infer a type that they do support. 42 | 43 | WASI SQL Embedding extension components will have some limited access to capabilities like random number generation, 44 | but not any capabilities that access the file system or network. 45 | Code that relies on the network or file-system should satisfy those requirements using virtualizations. 46 | 47 | ### Goals 48 | 49 | The primary goal of WASI SQL Embedding is to enable users to define Wasm-based SQL Extensions in a standard way. 50 | 51 | ### Non-goals 52 | 53 | [If there are "adjacent" goals which may appear to be in scope but aren't, enumerate them here. This section may be fleshed out as your design progresses and you encounter necessary technical and other trade-offs.] 54 | 55 | ### API walk-through 56 | 57 | The full API documentation can be found [here](wasi-proposal-template.md). 58 | 59 | [Walk through of how someone would use this API.] 60 | 61 | #### Unicode Functionality 62 | 63 | If a user wanted to perform unicode normalization on some text in a database, 64 | it would be convenient if they could write a simple extension that takes advantage of existing libraries. 65 | 66 | e.g. 67 | ```rust 68 | use unicode_normalization::UnicodeNormalization; 69 | 70 | fn normalize(input: String) -> String { 71 | input.nfc().collect::() 72 | } 73 | ``` 74 | > **Note** 75 | > Bindings-related code and configuration is omitted 76 | 77 | After compiling this using WIT-based tooling, they would end up with a fully self-describing database extension. 78 | 79 | They could load this into a database and normalize user names like so. 80 | ```sql 81 | CREATE EXTENSION unicode FROM "https://..."; 82 | ... 83 | SELECT unicode_normalize(name) FROM users; 84 | ``` 85 | 86 | #### [Use case 2] 87 | 88 | [etc.] 89 | 90 | ### Detailed design discussion 91 | 92 | [This section should mostly refer to the .wit.md file that specifies the API. This section is for any discussion of the choices made in the API which don't make sense to document in the spec file itself.] 93 | 94 | #### [Tricky design choice #1] 95 | 96 | [Talk through the tradeoffs in coming to the specific design point you want to make.] 97 | 98 | ``` 99 | // Illustrated with example code. 100 | ``` 101 | 102 | [This may be an open question, in which case you should link to any active discussion threads.] 103 | 104 | #### [Tricky design choice 2] 105 | 106 | [etc.] 107 | 108 | ### Considered alternatives 109 | 110 | [This section is not required if you already covered considered alternatives in the design discussion above.] 111 | 112 | #### [Alternative 1] 113 | 114 | [Describe an alternative which was considered, and why you decided against it.] 115 | 116 | #### [Alternative 2] 117 | 118 | [etc.] 119 | 120 | ### Stakeholder Interest & Feedback 121 | 122 | TODO before entering Phase 3. 123 | 124 | [This should include a list of implementers who have expressed interest in implementing the proposal] 125 | 126 | ### References & acknowledgements 127 | 128 | Many thanks for valuable feedback and advice from: 129 | 130 | - [Person 1] 131 | - [Person 2] 132 | - [etc.] 133 | -------------------------------------------------------------------------------- /example-world.md: -------------------------------------------------------------------------------- 1 |

World example-world

2 | 10 |

Import interface example-dep-interface

11 |
12 |

Types

13 |

type example-dep-type

14 |

u32

15 |

16 | ## Import interface example-interface 17 |

Short interface description.

18 |

Explanation for developers using the interface API. It should include an 19 | overview of the API as a whole as well as call out notable items in it, 20 | for example example-api-type and example-api-function.

21 |
22 |

Types

23 |

type example-dep-type

24 |

example-dep-type

25 |

26 | #### `record example-api-type` 27 |

Short type description

28 |

Explanation for developers using this type. It may be useful to give 29 | some examples of places in the API where the type is used, such as in 30 | the arguments and return type of example-api-function.

31 |
32 | Detailed specification 33 | More rigorous specification details for implementers go here, if needed. 34 | The intention is to keep the developer-oriented docs focused on things that 35 | most developers will need to be aware of, while putting bulkier descriptions 36 | of precise behavior here. 37 |
38 |
Record Fields
39 | 49 |
50 |

Functions

51 |

example-api-function: func

52 |

Short function description

53 |

Explanation for developers using the API. This should describe the 54 | arguments which in this function are arg0, arg1, and arg2, and the 55 | return value.

56 |
57 | Detailed specification 58 | Similar to the details section above, this is meant for more rigorous 59 | specification details for implementors. This may explain what a compliant 60 | implementation MUST do, such as never returning an earlier result from a 61 | later call, for example. 62 |
63 |
Params
64 | 69 |
Return values
70 | 73 | -------------------------------------------------------------------------------- /test/README.md: -------------------------------------------------------------------------------- 1 | # Testing guidelines 2 | 3 | TK fill in testing guidelines 4 | 5 | ## Installing the tools 6 | 7 | TK fill in instructions 8 | 9 | ## Running the tests 10 | 11 | TK fill in instructions 12 | -------------------------------------------------------------------------------- /wit/deps/example-dep/example-api.wit: -------------------------------------------------------------------------------- 1 | // An example dependency, showing how these look. Actual proposals should 2 | // delete this file and add their actual dependencies in the `deps` directory. 3 | 4 | interface example-dep-interface { 5 | type example-dep-type = u32 6 | } 7 | -------------------------------------------------------------------------------- /wit/example.wit: -------------------------------------------------------------------------------- 1 | // Instructions for filling in this file: 2 | // 3 | // - Delete all these `//` comments, up to the first `///` comment. 4 | // 5 | // - Replace the remaining contents below with [Wit] code describing 6 | // `interface`s and/or `world`s, using the same formatting style. 7 | // 8 | // If you want to include examples of the API in use, these should be in the 9 | // README.md at the root of the repository and linked to from this file. 10 | // 11 | // [Wit]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md 12 | 13 | /// Short interface description. 14 | /// 15 | /// Explanation for developers using the interface API. It should include an 16 | /// overview of the API as a whole as well as call out notable items in it, 17 | /// for example `example-api-type` and `example-api-function`. 18 | default interface example-interface { 19 | use example-dep.example-api.example-dep-interface.{example-dep-type} 20 | 21 | /// Short type description 22 | /// 23 | /// Explanation for developers using this type. It may be useful to give 24 | /// some examples of places in the API where the type is used, such as in 25 | /// the arguments and return type of `example-api-function`. 26 | /// 27 | ///
28 | /// Detailed specification 29 | /// More rigorous specification details for implementers go here, if needed. 30 | /// The intention is to keep the developer-oriented docs focused on things that 31 | /// most developers will need to be aware of, while putting bulkier descriptions 32 | /// of precise behavior here. 33 | ///
34 | record example-api-type { 35 | /// A description of a field. 36 | field0: u64, 37 | /// A description of another field. 38 | field1: string, 39 | } 40 | 41 | /// Short function description 42 | /// 43 | /// Explanation for developers using the API. This should describe the 44 | /// arguments which in this function are `arg0`, `arg1`, and `arg2`, and the 45 | /// return value. 46 | /// 47 | ///
48 | /// Detailed specification 49 | /// Similar to the details section above, this is meant for more rigorous 50 | /// specification details for implementors. This may explain what a compliant 51 | /// implementation MUST do, such as never returning an earlier result from a 52 | /// later call, for example. 53 | ///
54 | example-api-function: func( 55 | arg0: example-api-type, 56 | arg1: string, 57 | arg2: example-dep-type, 58 | ) -> result 59 | } 60 | -------------------------------------------------------------------------------- /wit/world.wit: -------------------------------------------------------------------------------- 1 | // If the repository defines `interface`s, this file can define a minimal world 2 | // which contains those interfaces, to allow documentation to be generated for 3 | // them. 4 | // 5 | // Proposals should remove these `//` commments, and edit the `world` name and 6 | // imports below to pull in their own `interface`s. 7 | 8 | default world example-world { 9 | import example-interface: pkg.example.example-interface 10 | } 11 | --------------------------------------------------------------------------------