diff --git a/docs/NEXT_README.md b/docs/NEXT_README.md new file mode 100644 index 00000000..646890b1 --- /dev/null +++ b/docs/NEXT_README.md @@ -0,0 +1,76 @@ +# + +This repository is based on https://github.com/duckdb/extension-template, check it out if you want to build and ship your own DuckDB extension. + +--- + +This extension, , allow you to ... . + + +## Building +To build the extension: +```sh +make +``` +The main binaries that will be built are: +```sh +./build/release/duckdb +./build/release/test/unittest +./build/release/extension//.duckdb_extension +``` +- `duckdb` is the binary for the duckdb shell with the extension code automatically loaded. +- `unittest` is the test runner of duckdb. Again, the extension is already linked into the binary. +- `.duckdb_extension` is the loadable binary as it would be distributed. + +## Running the extension +To run the extension code, simply start the shell with `./build/release/duckdb`. + +Now we can use the features from the extension directly in DuckDB. The template contains a single scalar function `quack()` that takes a string arguments and returns a string: +``` +D select quack('Jane') as result; +┌───────────────┐ +│ result │ +│ varchar │ +├───────────────┤ +│ Quack Jane 🐥 │ +└───────────────┘ +``` + +## Running the tests +Different tests can be created for DuckDB extensions. The primary way of testing DuckDB extensions should be the SQL tests in `./test/sql`. These SQL tests can be run using: +```sh +make test +``` + +### Installing the deployed binaries +To install your extension binaries from S3, you will need to do two things. Firstly, DuckDB should be launched with the +`allow_unsigned_extensions` option set to true. How to set this will depend on the client you're using. Some examples: + +CLI: +```shell +duckdb -unsigned +``` + +Python: +```python +con = duckdb.connect(':memory:', config={'allow_unsigned_extensions' : 'true'}) +``` + +NodeJS: +```js +db = new duckdb.Database(':memory:', {"allow_unsigned_extensions": "true"}); +``` + +Secondly, you will need to set the repository endpoint in DuckDB to the HTTP url of your bucket + version of the extension +you want to install. To do this run the following SQL query in DuckDB: +```sql +SET custom_extension_repository='bucket.s3.eu-west-1.amazonaws.com//latest'; +``` +Note that the `/latest` path will allow you to install the latest extension version available for your current version of +DuckDB. To specify a specific version, you can pass the version instead. + +After running these steps, you can install and load your extension using the regular INSTALL/LOAD commands in DuckDB: +```sql +INSTALL +LOAD +``` diff --git a/README.md b/docs/README.md similarity index 95% rename from README.md rename to docs/README.md index 18fa6022..e9511cab 100644 --- a/README.md +++ b/docs/README.md @@ -1,5 +1,7 @@ # WIP Disclaimer -This template is currently work-in-progress. Feel free to play around with it and give us feedback. Note also that this template depends on a development version of DuckDB. Follow https://duckdb.org/news for more information on official launch. +This template is currently a work-in-progress. Feel free to play around with it and give us feedback. Note also that this template depends on a development version of DuckDB. + +Get in contact with fellow extension developers on https://discord.duckdb.org and follow https://duckdb.org/news for more information on official launch. # DuckDB Extension Template The main goal of this template is to allow users to easily develop, test and distribute their own DuckDB extension. diff --git a/scripts/set_extension_name.py b/scripts/set_extension_name.py index 14b6391f..397e53a1 100755 --- a/scripts/set_extension_name.py +++ b/scripts/set_extension_name.py @@ -1,13 +1,15 @@ #!/usr/bin/python3 -import sys, os +import sys, os, shutil from pathlib import Path -if (len(sys.argv) != 2): - raise Exception('usage: python3 set_extension_name.py ') +shutil.copyfile(f'docs/NEXT_README.md', f'README.md') -string_to_find = "quack" -string_to_replace = sys.argv[1] +if (len(sys.argv) != 3): + raise Exception('usage: python3 set_extension_name.py ') + +name_extension = sys.argv[1] +name_function = sys.argv[2] def replace(file_name, to_find, to_replace): with open(file_name, 'r', encoding="utf8") as file : @@ -24,16 +26,24 @@ def replace(file_name, to_find, to_replace): files_to_search.extend(Path('./src').rglob('./**/*.hpp')) files_to_search.extend(Path('./src').rglob('./**/*.cpp')) files_to_search.extend(Path('./src').rglob('./**/*.txt')) -files_to_search.extend(Path('./src').rglob('./**/*.md')) -for path in files_to_search: - replace(path, string_to_find, string_to_replace) - replace(path, string_to_find.capitalize(), string_to_replace.capitalize()) - -replace("./CMakeLists.txt", string_to_find, string_to_replace) -replace("./Makefile", string_to_find, string_to_replace) -replace("./Makefile", string_to_find.capitalize(), string_to_replace.capitalize()) -replace("./Makefile", string_to_find.upper(), string_to_replace.upper()) -replace("./README.md", string_to_find, string_to_replace) +files_to_search.extend(Path('./src').rglob('./*.md')) + +def replace_everywhere(to_find, to_replace): + for path in files_to_search: + replace(path, to_find, to_replace) + replace(path, to_find.capitalize(), to_replace.capitalize()) + + replace("./CMakeLists.txt", to_find, to_replace) + replace("./Makefile", to_find, to_replace) + replace("./Makefile", to_find.capitalize(), to_replace.capitalize()) + replace("./Makefile", to_find.upper(), to_replace.upper()) + replace("./README.md", to_find, to_replace) + +replace_everywhere("quack", name_function) +replace_everywhere("", name_extension) + +string_to_replace = name_function +string_to_find = "quack" # rename files os.rename(f'test/python/{string_to_find}_test.py', f'test/python/{string_to_replace}_test.py')