npgsqlrest 2.25.0 → 2.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/config-copy.js +17 -17
  2. package/package.json +31 -31
  3. package/postinstall.js +68 -68
  4. package/readme.md +364 -116
  5. package/uninstall.js +21 -21
package/config-copy.js CHANGED
@@ -1,18 +1,18 @@
1
- #!/usr/bin/env node
2
-
3
- const fs = require('fs');
4
- const path = require('path');
5
-
6
- // Get the destination directory from the command line arguments, or use the current directory
7
- const destDir = process.argv[2] || process.cwd();
8
-
9
- // Path to the source file
10
- const srcFile = path.join(__dirname, "appsettings.json");
11
-
12
- // Path to the destination file
13
- const destFile = path.join(destDir, "appsettings.json");
14
-
15
- // Copy the file
16
- fs.copyFileSync(srcFile, destFile);
17
-
1
+ #!/usr/bin/env node
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+
6
+ // Get the destination directory from the command line arguments, or use the current directory
7
+ const destDir = process.argv[2] || process.cwd();
8
+
9
+ // Path to the source file
10
+ const srcFile = path.join(__dirname, "appsettings.json");
11
+
12
+ // Path to the destination file
13
+ const destFile = path.join(destDir, "appsettings.json");
14
+
15
+ // Copy the file
16
+ fs.copyFileSync(srcFile, destFile);
17
+
18
18
  console.log(`Copied appsettings.json to ${destFile}`);
package/package.json CHANGED
@@ -1,31 +1,31 @@
1
- {
2
- "name": "npgsqlrest",
3
- "version": "2.25.0",
4
- "description": "Automatic REST API for PostgreSQL Databases Client Build",
5
- "scripts": {
6
- "postinstall": "node postinstall.js",
7
- "uninstall": "node uninstall.js",
8
- "start": "npx npgsqlrest ./appsettings.json ./npgsqlrest.json"
9
- },
10
- "bin": {
11
- "npgsqlrest": "node_modules/.bin/npgsqlrest",
12
- "npgsqlrest-config-copy": "./config-copy.js"
13
- },
14
- "repository": {
15
- "type": "git",
16
- "url": "git+https://github.com/vb-consulting/NpgsqlRest.git"
17
- },
18
- "keywords": [
19
- "postgresql",
20
- "server",
21
- "rest",
22
- "api",
23
- "automatic"
24
- ],
25
- "author": "vb-consulting",
26
- "license": "MIT",
27
- "bugs": {
28
- "url": "https://github.com/vb-consulting/NpgsqlRest/issues"
29
- },
30
- "homepage": "https://github.com/vb-consulting/NpgsqlRest/blob/master/npm/readme.md"
31
- }
1
+ {
2
+ "name": "npgsqlrest",
3
+ "version": "2.26.0",
4
+ "description": "Automatic REST API for PostgreSQL Databases Client Build",
5
+ "scripts": {
6
+ "postinstall": "node postinstall.js",
7
+ "uninstall": "node uninstall.js",
8
+ "start": "npx npgsqlrest ./appsettings.json ./npgsqlrest.json"
9
+ },
10
+ "bin": {
11
+ "npgsqlrest": "node_modules/.bin/npgsqlrest",
12
+ "npgsqlrest-config-copy": "./config-copy.js"
13
+ },
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "git+https://github.com/vb-consulting/NpgsqlRest.git"
17
+ },
18
+ "keywords": [
19
+ "postgresql",
20
+ "server",
21
+ "rest",
22
+ "api",
23
+ "automatic"
24
+ ],
25
+ "author": "vb-consulting",
26
+ "license": "MIT",
27
+ "bugs": {
28
+ "url": "https://github.com/vb-consulting/NpgsqlRest/issues"
29
+ },
30
+ "homepage": "https://github.com/vb-consulting/NpgsqlRest/blob/master/npm/readme.md"
31
+ }
package/postinstall.js CHANGED
@@ -1,68 +1,68 @@
1
- #!/usr/bin/env node
2
-
3
- const fs = require("fs");
4
- const path = require("path");
5
- const os = require("os");
6
- const https = require("https");
7
-
8
- const downloadDir = "../.bin/";
9
- const downloadFrom = "https://github.com/vb-consulting/NpgsqlRest/releases/download/v2.30.0-client-v2.25.0/";
10
-
11
- function download(url, to, done) {
12
- https.get(url, (response) => {
13
- if (response.statusCode == 200) {
14
- const file = fs.createWriteStream(to, { mode: 0o755 });
15
- response.pipe(file);
16
- file.on("finish", () => {
17
- file.close();
18
- console.info(`${to} ...`,);
19
- if (done) {
20
- done();
21
- }
22
- });
23
- } else if (response.statusCode == 302) {
24
- download(response.headers.location, to);
25
- } else {
26
- console.error("Error downloading file:", to, response.statusCode, response.statusMessage);
27
- }
28
- }).on("error", (err) => {
29
- fs.unlink(to, () => {
30
- console.error("Error downloading file:", to, err);
31
- });
32
- });
33
- }
34
-
35
- const osType = os.type();
36
- var downloadFileUrl;
37
- var downloadTo;
38
-
39
- if (osType === "Windows_NT") {
40
- downloadFileUrl = `${downloadFrom}npgsqlrest-win64.exe`;
41
- downloadTo = `${downloadDir}npgsqlrest.exe`;
42
- } else if (osType === "Linux") {
43
- downloadFileUrl = `${downloadFrom}npgsqlrest-linux64`;
44
- downloadTo = `${downloadDir}npgsqlrest`;
45
- } else if (osType === "Darwin") {
46
- downloadFileUrl = `${downloadFrom}npgsqlrest-osx64`;
47
- downloadTo = `${downloadDir}npgsqlrest`;
48
- } else {
49
- console.error("Unsupported OS detected:", osType);
50
- process.exit(1);
51
- }
52
-
53
- if (!fs.existsSync(path.dirname(downloadTo))) {
54
- fs.mkdirSync(path.dirname(downloadTo), { recursive: true });
55
- }
56
-
57
- if (fs.existsSync(downloadTo)) {
58
- fs.unlinkSync(downloadTo);
59
- }
60
- download(downloadFileUrl, downloadTo);
61
-
62
-
63
- downloadFileUrl = `${downloadFrom}appsettings.json`;
64
- downloadTo = "./appsettings.json";
65
- if (fs.existsSync(downloadFileUrl)) {
66
- fs.unlinkSync(downloadFileUrl, downloadTo);
67
- }
68
- download(downloadFileUrl, downloadTo);
1
+ #!/usr/bin/env node
2
+
3
+ const fs = require("fs");
4
+ const path = require("path");
5
+ const os = require("os");
6
+ const https = require("https");
7
+
8
+ const downloadDir = "../.bin/";
9
+ const downloadFrom = "https://github.com/NpgsqlRest/NpgsqlRest/releases/download/v2.31.0-client-v2.26.0/";
10
+
11
+ function download(url, to, done) {
12
+ https.get(url, (response) => {
13
+ if (response.statusCode == 200) {
14
+ const file = fs.createWriteStream(to, { mode: 0o755 });
15
+ response.pipe(file);
16
+ file.on("finish", () => {
17
+ file.close();
18
+ console.info(`${to} ...`,);
19
+ if (done) {
20
+ done();
21
+ }
22
+ });
23
+ } else if (response.statusCode == 302) {
24
+ download(response.headers.location, to);
25
+ } else {
26
+ console.error("Error downloading file:", to, response.statusCode, response.statusMessage);
27
+ }
28
+ }).on("error", (err) => {
29
+ fs.unlink(to, () => {
30
+ console.error("Error downloading file:", to, err);
31
+ });
32
+ });
33
+ }
34
+
35
+ const osType = os.type();
36
+ var downloadFileUrl;
37
+ var downloadTo;
38
+
39
+ if (osType === "Windows_NT") {
40
+ downloadFileUrl = `${downloadFrom}npgsqlrest-win64.exe`;
41
+ downloadTo = `${downloadDir}npgsqlrest.exe`;
42
+ } else if (osType === "Linux") {
43
+ downloadFileUrl = `${downloadFrom}npgsqlrest-linux64`;
44
+ downloadTo = `${downloadDir}npgsqlrest`;
45
+ } else if (osType === "Darwin") {
46
+ downloadFileUrl = `${downloadFrom}npgsqlrest-osx-arm64`;
47
+ downloadTo = `${downloadDir}npgsqlrest`;
48
+ } else {
49
+ console.error("Unsupported OS detected:", osType);
50
+ process.exit(1);
51
+ }
52
+
53
+ if (!fs.existsSync(path.dirname(downloadTo))) {
54
+ fs.mkdirSync(path.dirname(downloadTo), { recursive: true });
55
+ }
56
+
57
+ if (fs.existsSync(downloadTo)) {
58
+ fs.unlinkSync(downloadTo);
59
+ }
60
+ download(downloadFileUrl, downloadTo);
61
+
62
+
63
+ downloadFileUrl = `${downloadFrom}appsettings.json`;
64
+ downloadTo = "./appsettings.json";
65
+ if (fs.existsSync(downloadFileUrl)) {
66
+ fs.unlinkSync(downloadFileUrl, downloadTo);
67
+ }
68
+ download(downloadFileUrl, downloadTo);
package/readme.md CHANGED
@@ -1,116 +1,364 @@
1
- # npgsqlrest
2
-
3
- ![npm version](https://badge.fury.io/js/npgsqlrest.svg)
4
- ![build-test-publish](https://github.com/vb-consulting/NpgsqlRest/workflows/build-test-publish/badge.svg)
5
- ![License](https://img.shields.io/badge/license-MIT-green)
6
- ![GitHub Stars](https://img.shields.io/github/stars/vb-consulting/NpgsqlRest?style=social)
7
- ![GitHub Forks](https://img.shields.io/github/forks/vb-consulting/NpgsqlRest?style=social)
8
-
9
- ## Description
10
-
11
- The `npgsqlrest` is an NPM distribution of the self-contained ahead-of-time (AOT) compiled to native code executables of the [NpgsqlRest Client Web App](https://github.com/vb-consulting/NpgsqlRest/tree/master/NpgsqlRestClient).
12
-
13
- NpgsqlRest is an Automatic REST API for PostgreSQL Database as the .NET8 Middleware. See the [GitHub Readme](https://github.com/vb-consulting/NpgsqlRest) for more info.
14
-
15
- NpgsqlRest Client Web App is a command line utility that runs as a configurable Kestrel web server that can:
16
-
17
- - Create an Automatic REST API for the PostgreSQL Databases.
18
- - Generate TypeScript Code and HTTP files for testing.
19
- - Configure security for use the of either encrypted cookies or JWT Bearer tokens or both.
20
- - Expose REST API endpoints for the PostgreSQL Databases as Login/Logout.
21
- - Use external authentication providers such as Google, LinkedIn or GitHub.
22
- - Server static content.
23
- - Use and configure built-in Serilog structured logging.
24
- - Configure Cross-origin resource sharing (CORS) access, SSL, Server Certificates and more, everything needed for modern Web development.
25
-
26
- See the [default configuration file](https://vb-consulting.github.io/npgsqlrest/config/) with descriptions for more information.
27
-
28
- ## Notes Before Installation
29
-
30
- This package will download an executable file for the target OS on installation (see the postinstall.js script) from the [GitHub release page](https://github.com/vb-consulting/NpgsqlRest/releases/).
31
-
32
- Currently, only the Windows-64 and Linux-64 builds are supported.
33
-
34
- The Mac OS builds are missing because I don't have a Mac machine. If someone could help me out with this I'd be grateful.
35
-
36
- If you try to install this package on MacOS, or any other unsupported OS, installation will report: `Unsupported OS detected: [OS Type]`.
37
-
38
- To see how you can create your own custom build follow these instructions:
39
-
40
- Steps:
41
-
42
- 1) Make sure that you have .NET8 SDK installed and ready.
43
- 2) Clone [NpgsqlRest repository](https://github.com/vb-consulting/NpgsqlRest/tree/master/NpgsqlRest)
44
- 3) Navigate to the [`NpgsqlRestClient` project directory](https://github.com/vb-consulting/NpgsqlRest/tree/master/NpgsqlRestClient/).
45
- 4) Make your desired customizations (or not).
46
- 5) Run publish command, for example, `dotnet publish -r win-x64 -c Release --output [target dir]`
47
-
48
- Notes: `win-x64` is the designated target OS for the build. Adjust this parameter appropriately for the target OS. See [https://learn.microsoft.com/en-us/dotnet/core/rid-catalog#known-rids](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog#known-rids). The project is already configured for the AOT builds, but you will need to run the publish command from the same flavor OS as the build target OS (Windows for Windows builds, Linux for Linux builds, etc).
49
-
50
- ## Installation
51
-
52
- Install `npgsqlrest` using npm:
53
-
54
- ```console
55
- npm install npgsqlrest --save-dev
56
- ```
57
-
58
- ## Usage
59
-
60
- ```console
61
- $ npx npgsqlrest --help
62
- Usage:
63
- npgsqlrest Run with the optional default configuration files: appsettings.json and
64
- appsettings.Development.json. If these file are not found, default
65
- configuration setting is used (see
66
- https://vb-consulting.github.io/npgsqlrest/config/).
67
- npgsqlrest [files...] Run with the custom configuration files. All configuration files are required.
68
- Any configuration values will override default values in order of appearance.
69
- npgsqlrest [file1 -o file2...] Use the -o switch to mark the next configuration file as optional. The first
70
- file after the -o switch is optional.
71
- npgsqlrest [file1 --optional file2...] Use --optional switch to mark the next configuration file as optional. The
72
- first file after the --optional switch is optional.
73
- Note: Values in the later file will override the values in the previous one.
74
-
75
- npgsqlrest [--key=value] Override the configuration with this key with a new value (case insensitive,
76
- use : to separate sections).
77
-
78
- npgsqlrest -v, --version Show version information.
79
- npgsqlrest -h, --help Show command line help.
80
-
81
-
82
- Examples:
83
- Example: use two config files npgsqlrest appsettings.json appsettings.Development.json
84
- Example: second config file optional npgsqlrest appsettings.json -o appsettings.Development.json
85
- Example: override ApplicationName config npgsqlrest --applicationname=Test
86
- Example: override Auth:CookieName config npgsqlrest --auth:cookiename=Test
87
-
88
- ```
89
-
90
- - Use the `npgsqlrest-config-copy` command to copy the default config to the current directory (or, optionally, directory from the first argument).
91
-
92
- ```console
93
- $ npx npgsqlrest-config-copy
94
- Copied appsettings.json to /home/vbilopav/npgsqlrest-npm-test/appsettings.json
95
- ```
96
-
97
- - Running with supplied configuration:
98
-
99
- ```console
100
- $ npx npgsqlrest appsettings.json project-config.json
101
- [11:29:06.551 INF] ----> Starting with configuration(s): ["EnvironmentVariablesConfigurationProvider", "JsonConfigurationProvider for 'appsettings.json' (Required)", "JsonConfigurationProvider for 'project-config.json' (Required)"] [Program]
102
- [11:29:06.552 INF] Using connection: Host=127.0.0.1;Port=5432;Database=test;Username=postgres;Application Name=MyProject [Program]
103
- [11:29:06.553 INF] Using Cookie Authentication with scheme Cookies. Cookie expires in 14 days. [Program]
104
- [11:29:06.553 INF] Using Bearer Token Authentication with scheme BearerToken. Token expires in 1 hours and refresh token expires in 14 days. [Program]
105
- [11:29:06.560 INF] Serving static files from /home/vbilopav/npgsqlrest-npm-test/wwwroot [Program]
106
- [11:29:07.083 INF] Created endpoint POST /api/case-return-long-table1 [NpgsqlRest]
107
- [11:29:07.083 INF] Created HTTP file: /home/vbilopav/npgsqlrest-npm-test/test_public.http [NpgsqlRest.HttpFiles]
108
- [11:29:07.100 INF] Started in 00:00:00.5527040 [Program]
109
- [11:29:07.100 INF] Listening on ["http://localhost:5001"] [Program]
110
- ```
111
-
112
- ## Changelog
113
-
114
- See the detailed change log:
115
- - [NpgsqlRest Changelog](https://vb-consulting.github.io/npgsqlrest/changelog/)
116
- - [NpgsqlRest Client Changelog](https://vb-consulting.github.io/npgsqlrest/client/#changelog)
1
+ # NpgsqlRest
2
+
3
+ ![npm version](https://badge.fury.io/js/npgsqlrest.svg)
4
+ ![build-test-publish](https://github.com/vb-consulting/NpgsqlRest/workflows/build-test-publish/badge.svg)
5
+ ![License](https://img.shields.io/badge/license-MIT-green)
6
+ ![GitHub Stars](https://img.shields.io/github/stars/vb-consulting/NpgsqlRest?style=social)
7
+ ![GitHub Forks](https://img.shields.io/github/forks/vb-consulting/NpgsqlRest?style=social)
8
+
9
+ **Automatic PostgreSQL Web Server**
10
+
11
+ >
12
+ > Transform your PostgreSQL database into a **production-ready, blazing-fast REST API Standalone Web Server**.
13
+ >
14
+ > Generate code, build entire applications and more.
15
+ >
16
+
17
+ ## Enterprise-Grade PostgreSQL REST API Server
18
+
19
+ NpgsqlRest is the superior alternative to existing automatic PostgreSQL REST API solutions, offering unmatched performance and advanced enterprise features.
20
+
21
+ **Download, configure, and run** - your REST API server is live in seconds with comprehensive enterprise features built-in.
22
+
23
+ ## Core Features
24
+
25
+ ### Endpoints & Configuration
26
+ - **Instant API Generation**. Automatically creates REST endpoints from PostgreSQL functions, procedures, tables, and views.
27
+ - **Minimal Configuration**. Works out-of-the-box with any PostgreSQL database with minimal configuration file. You only need connection info to get started.
28
+ - **Comment Annotations**. Control and configure endpoint behavior from your database using **declarative comment annotations system.**
29
+ - **Declarative Configuration**. Declare to database how your endpoint should behave. Focus on end-results of your system, not on how it will be implemented.
30
+ - **HTTP Customization**. Set methods, paths, content types, and response headers directly in your database declarations.
31
+ - **Authentication Control**. Configure authorization, roles, and security per endpoint in your database declarations.
32
+ - **Real-Time Streaming**. Enable server-sent events and fine control event scoping (user, roles, etc.) directly in your database declarations.
33
+ - **Response Formatting**. Control output formats, caching, timeouts, and raw responses in your database declarations, and more.
34
+
35
+ ### Code Generation
36
+ - **JavaScript**. Generate automatically fetch modules for all endpoints in development mode. Slash development time dramatically and reduce bugs.
37
+ - **TypeScript**. Generate type-safe interfaces and types for generated fetch modules. Bring static type checking for your PostgreSQL database.
38
+ - **HTTP Files**. Auto-generated REST client files, for all generated endpoints, for testing, development and auto-discovery.
39
+
40
+ ### Authentication & Security
41
+ - **Multiple Auth Methods**. Cookie authentication, Bearer tokens, and external OAuth providers.
42
+ - **Encrypted Tokens**. Encrypted security tokens with advanced encryption key management and storage options (file, database, etc.).
43
+ - **CORS Support**. Cross-origin resource sharing configuration for Bearer token access.
44
+ - **Built-in Password Validation**. Built-in extendable and secure password hashing and validation. PBKDF2-SHA256 with 600,000 iterations aligned with OWASP's 2023+ recommendations.
45
+ - **OAuth Integration**. Google, LinkedIn, GitHub, Microsoft and Facebook support built-in.
46
+ - **Claims-based security**. User assertions cached in encrypted security token.
47
+ - **Role-Based Authorization**. Fine-grained access control with PostgreSQL role integration.
48
+ - **Claim or Role Parameter Mapping**. Automatically map user claims or roles to parameters.
49
+ - **Claim or Role Context Mapping**. Automatically map user claims or roles to PostgreSQL connection context.
50
+ - **CSRF Protection**. Antiforgery token support for secure uploads and form submissions.
51
+ - **SSL/TLS**. Full HTTPS support with certificate management.
52
+ - **PostgreSQL Security and Encryption**. Database connection security features courtesy of [Npgsql](https://www.npgsql.org/doc/connection-string-parameters.html#security-and-encryption). Includes SSL, Certificates, Kerberos and more.
53
+
54
+ ### Performance & Scalability
55
+ - **High Performance**. Blazing fast native executable. See [Performance Benchmarks](https://github.com/NpgsqlRest/pg_function_load_tests).
56
+ - **Connection Pooling**. Built-in connection pooler, courtesy of [Npgsql](https://www.npgsql.org/doc/connection-string-parameters.html#pooling).
57
+ - **KeepAlive, Auto-prepare, Buffer Size**. Other performance tweaks and settings courtesy of [Npgsql](https://www.npgsql.org/doc/connection-string-parameters.html#performance).
58
+ - **Failover, Load Balancing**. Set multiple hosts in connection string for failover and balancing.
59
+ - **Multiple Connections**. Define multiple connections and set specific connections (read-only, write-only) per endpoint in your database declarations.
60
+ - **Connection Retry**. Robust and configurable built-in connection retry mechanism.
61
+ - **Thread Pool Optimization**. Configurable thread pool settings for maximum throughput.
62
+ - **Request Optimization**. Kestrel server tuning with configurable limits.
63
+ - **Response Compression**. Brotli and Gzip compression with configurable levels.
64
+ - **HTTP Caching**. Define endpoint caching per endpoint in your database declarations.
65
+ - **Server Caching**. Define endpoint in-memory server caching per endpoint in your database declarations.
66
+
67
+ ### Real-Time & Streaming
68
+ - **Server-Sent Events**. Innovative real-time streaming with PostgreSQL `RAISE INFO` statements. No database locking.
69
+ - **Live Notifications**. Push updates to clients in real-time.
70
+ - **Event Sources**. Auto-generated client code for streaming connections.
71
+ - **Custom Scopes**. Define Server-Sent Event Scope (specific user, groups of users or roles, etc.) per endpoint or per event in your database declarations.
72
+
73
+ ### Enterprise Features
74
+ - **Native Executables**. Native executable builds, including ARM versions, have zero dependencies and extremely fast startup times.
75
+ - **Containerization**. Docker-ready hub images.
76
+ - **NPM Package**. Additional distribution channel as NPM package.
77
+ - **Environment Configuration**. Flexible environment variable and configuration management.
78
+ - **Data Protection**. Advanced encryption key management and storage options.
79
+ - **Structured Logging**. Industry standard Serilog logger for Console, rolling file or PostgreSQL database logging.
80
+ - **Excel Processing**. Upload handler for Excel files that supports Excel content processing.
81
+
82
+ ### Additional Features
83
+ - **Upload Handlers**. Multiple upload handlers implemented: File System, Large Objects, CSV/Excel, etc., with code generation. Make complex upload and processing pipelines in minutes.
84
+ - **Static Files**. Built-in serving of static content with high speed template parser for user claims and authorization features.
85
+ - **Request Tracking**. Detailed request analytics and connection monitoring.
86
+ - **Performance Metrics**. Built-in performance monitoring and diagnostics.
87
+ - **Error Handling**. Advanced PostgreSQL error code mapping to HTTP status codes.
88
+ - **Custom Headers**. Configurable request/response header management in your database declarations.
89
+ - **IP Tracking**. Client IP address parameter or PostgreSQL connection context for tracking.
90
+ - **.NET Library Integration**. Version with core features implemented as .NET Nuget library for .NET project integration.
91
+
92
+ And more!
93
+
94
+ ## Get Started in Seconds
95
+
96
+ Starting is easy:
97
+
98
+ 1. **Annotate some PostgreSQL Functions** to enable HTTP Endpoint.
99
+ 2. **Prepare Server Executable** (download, install or pull).
100
+ 3. **Configure** your PostgreSQL connection in `appsettings.json`
101
+ 4. **Run** the executable - your REST API server is live!
102
+
103
+ ## Complete Example
104
+
105
+ ### 1) Annotate PostgreSQL Function
106
+
107
+ Let's create a simple Hello World function and add a simple comment annotation:
108
+
109
+ ```sql
110
+ create function hello_world()
111
+ returns text
112
+ language sql
113
+ as $$
114
+ select 'Hello World'
115
+ $$;
116
+
117
+ comment on function hello_world() is '
118
+ HTTP GET /hello
119
+ authorize admin
120
+ ';
121
+ ```
122
+
123
+ This annotation will create an `HTTP GET /hello` endpoint that returns "Hello World" and will authorize only the admin role.
124
+
125
+ We could also add any HTTP response header, like for example `Content-Type: text/plain`, but since this function returns text, the response will be `text/plain` anyhow.
126
+
127
+ Note: Anything that is not a valid HTTP header or a comment annotation that alters behavior will be ignored and treated as a function comment.
128
+
129
+ ### 2) Prepare Server Executable
130
+
131
+ You have a choice to do the best approach that suits you. Either one of these things:
132
+
133
+ #### Download Executable
134
+
135
+ Download the appropriate executable for your target OS from [Releases](https://github.com/NpgsqlRest/NpgsqlRest/releases) page. You can use manual download, wget, or anything you want. Just remember to assign appropriate executable permissions after the download.
136
+
137
+ #### NPM Install
138
+
139
+ ```console
140
+ ~/dev
141
+ ❯ npm i npgsqlrest
142
+
143
+ added 1 package in 31s
144
+ ```
145
+
146
+ Note: NPM package will do the same thing on install automatically: Download the appropriate executable for your target OS from [Releases](https://github.com/NpgsqlRest/NpgsqlRest/releases) page.
147
+
148
+ #### Docker Pull
149
+
150
+ ```console
151
+ ~/dev
152
+ ❯ docker pull vbilopav/npgsqlrest:latest
153
+ latest: Pulling from vbilopav/npgsqlrest
154
+ Digest: sha256:70b4057343457e019657dca303acbed8a1acd5f83075ea996b8e6ea20dac4b48
155
+ Status: Image is up to date for vbilopav/npgsqlrest:latest
156
+ docker.io/vbilopav/npgsqlrest:latest
157
+
158
+ ~/dev
159
+ ```
160
+
161
+ ### 3) Add Minimal Configuration
162
+
163
+ Minimal Configuration is `appsettings.json` file with one connection string. You can do that with any editor or, using bash:
164
+
165
+ ```console
166
+ ~/dev
167
+ ❯ cat > appsettings.json << EOF
168
+ {
169
+ "ConnectionStrings": {
170
+ "Default": "Host=localhost;Port=5432;Database=my_db;Username=postgres;Password=postgres"
171
+ }
172
+ }
173
+ EOF
174
+ ```
175
+
176
+ ### 4) Run
177
+
178
+ Type executable name:
179
+
180
+ ```console
181
+ ~/dev
182
+ ❯ ./npgsqlrest
183
+ [11:33:35.440 INF] Started in 00:00:00.0940095, listening on ["http://localhost:8080"], version 2.26.0.0 [NpgsqlRest]
184
+ ```
185
+
186
+ Or, run as NPX command for NPM distributions:
187
+
188
+ ```console
189
+ ~/dev
190
+ ❯ npx npgsqlrest
191
+ [11:33:35.440 INF] Started in 00:00:00.0940095, listening on ["http://localhost:8080"], version 2.26.0.0 [NpgsqlRest]
192
+ ```
193
+
194
+ Or, run the appropriate Docker command (expose the 8080 default port and bind the default configuration):
195
+
196
+ ```bash
197
+ ~/dev
198
+ ❯ docker run -p 8080:8080 -v ./appsettings.json:/app/appsettings.json --network host vbilopav/npgsqlrest:latest
199
+ [11:33:35.440 INF] Started in 00:00:00.0940095, listening on ["http://localhost:8080"], version 2.26.0.0 [NpgsqlRest]
200
+ ```
201
+
202
+ Congratulations, your High Speed Web Server is running with `/hello` endpoint exposed.
203
+
204
+ ### Next Steps
205
+
206
+ Now that we have our server up and running, we can add some more configuration to make things interesting:
207
+
208
+ - Configure the Debug Log level for our NpgsqlRest server.
209
+ - Enable `HttpFileOptions` for the `HttpFile` plugin that generates HTTP files for testing.
210
+ - Enable `ClientCodeGen` for `TsClient` plugin that generates TypeScript code for us.
211
+
212
+ The configuration file should look like this:
213
+
214
+ ```json
215
+ {
216
+ "ConnectionStrings": {
217
+ "Default": "Host=localhost;Port=5432;Database=my_db;Username=postgres;Password=postgres"
218
+ },
219
+ "Log": {
220
+ "MinimalLevels": {
221
+ "NpgsqlRest": "Debug"
222
+ }
223
+ },
224
+ "NpgsqlRest": {
225
+ "HttpFileOptions": {
226
+ "Enabled": true,
227
+ "NamePattern": "./src/http/{0}_{1}"
228
+ },
229
+ "ClientCodeGen": {
230
+ "Enabled": true,
231
+ "FilePath": "./src/app/api/{0}Api.ts"
232
+ }
233
+ }
234
+ }
235
+ ```
236
+
237
+ After running with this configuration, we will see much more information in the console:
238
+
239
+ ```console
240
+ ~/dev
241
+ ❯ ./npgsqlrest
242
+ [12:46:05.120 DBG] ----> Starting with configuration(s): JsonConfigurationProvider for 'appsettings.json' (Optional), JsonConfigurationProvider for 'appsettings.Development.json' (Optional), CommandLineConfigurationProvider [NpgsqlRest]
243
+ [12:46:05.135 DBG] Using main connection string: Host=127.0.0.1;Database=my_db;Username=postgres;Password=******;Application Name=dev;Enlist=False;No Reset On Close=True [NpgsqlRest]
244
+ [12:46:05.149 DBG] Attempting to open PostgreSQL connection (attempt 1/7) [NpgsqlRest]
245
+ [12:46:05.194 DBG] Successfully opened PostgreSQL connection on attempt 1 [NpgsqlRest]
246
+ [12:46:05.199 DBG] Using Data Protection for application dev with default provider. Expiration in 90 days. [NpgsqlRest]
247
+ [12:46:05.214 DBG] Using RoutineSource PostgreSQL Source [NpgsqlRest]
248
+ [12:46:05.215 DBG] Using CrudSource PostgreSQL Source [NpgsqlRest]
249
+ [12:46:05.309 DBG] Function public.hello_world mapped to POST /api/hello-world has set HTTP by the comment annotation to GET /hello [NpgsqlRest]
250
+ [12:46:05.311 DBG] Created endpoint GET /hello [NpgsqlRest]
251
+ [12:46:05.332 DBG] Created HTTP file: ./src/http/todo_public.http [NpgsqlRest.HttpFiles]
252
+ [12:46:05.340 DBG] Created Typescript type file: ./src/app/api/publicApiTypes.d.ts [NpgsqlRest.TsClient]
253
+ [12:46:05.340 DBG] Created Typescript file: ./src/app/api/publicApi.ts [NpgsqlRest.TsClient]
254
+ [12:46:05.358 INF] Started in 00:00:00.2759846, listening on ["http://localhost:8080"], version 2.26.0.0 [NpgsqlRest]
255
+ ```
256
+
257
+ Also, two more files will be generated on startup:
258
+
259
+ 1) `todo_public.http`
260
+
261
+ HTTP file for testing, debugging, and development (VS Code requires rest-client plugin).
262
+
263
+ ```console
264
+ @host=http://localhost:8080
265
+
266
+ // function public.hello_world()
267
+ // returns text
268
+ //
269
+ // comment on function public.hello_world is 'HTTP GET /hello
270
+ // authorize admin';
271
+ GET {{host}}/hello
272
+
273
+ ###
274
+ ```
275
+
276
+ 2) `publicApi.ts`
277
+
278
+ TypeScript fetch module that you can import and use in your Frontend project immediately.
279
+
280
+ ```ts
281
+ // autogenerated at 2025-08-17T11:06:58.6605710+02:00
282
+ const baseUrl = "http://localhost:8080";
283
+
284
+ export const publicHelloWorldUrl = () => baseUrl + "/hello";
285
+
286
+ /**
287
+ * function public.hello_world()
288
+ * returns text
289
+ *
290
+ * @remarks
291
+ * comment on function public.hello_world is 'HTTP GET /hello
292
+ * authorize admin';
293
+ *
294
+ * @returns {{status: number, response: string}}
295
+ *
296
+ * @see FUNCTION public.hello_world
297
+ */
298
+ export async function publicHelloWorld() : Promise<{status: number, response: string}> {
299
+ const response = await fetch(publicHelloWorldUrl(), {
300
+ method: "GET",
301
+ });
302
+ return {
303
+ status: response.status,
304
+ response: await response.text()
305
+ };
306
+ }
307
+ ```
308
+ For a full list of configuration options, see the [default configuration file](https://github.com/NpgsqlRest/NpgsqlRest/blob/master/NpgsqlRestClient/appsettings.json). Any settings your configuration file will override these defaults.
309
+
310
+ Also, you can override these settings with console parameters. For example,e to enable Debug Level for NpgsqlRest run:
311
+
312
+ ```console
313
+ ~/dev
314
+ ❯ ./npgsqlrest --log:minimallevels:npgsqlrest=debug
315
+ ...
316
+ ```
317
+
318
+ And finally, to see all command line options, use `-h` or `--help`:
319
+
320
+ ```console
321
+ ~/dev
322
+ ❯ ./npgsqlrest --help
323
+ Usage:
324
+ npgsqlrest Run with the optional default configuration files: appsettings.json and appsettings.Development.json. If these file are not found, default configuration setting is used (see
325
+ https://github.com/NpgsqlRest/NpgsqlRest/blob/master/NpgsqlRestClient/appsettings.json).
326
+ npgsqlrest [files...] Run with the custom configuration files. All configuration files are required. Any configuration values will override default values in order of appearance.
327
+ npgsqlrest [file1 -o file2...] Use the -o switch to mark the next configuration file as optional. The first file after the -o switch is optional.
328
+ npgsqlrest [file1 --optional file2...] Use --optional switch to mark the next configuration file as optional. The first file after the --optional switch is optional.
329
+ Note: Values in the later file will override the values in the previous one.
330
+
331
+ npgsqlrest [--key=value] Override the configuration with this key with a new value (case insensitive, use : to separate sections).
332
+
333
+ npgsqlrest -v, --version Show version information.
334
+ npgsqlrest -h, --help Show command line help.
335
+
336
+
337
+ Examples:
338
+ Example: use two config files npgsqlrest appsettings.json appsettings.Development.json
339
+ Example: second config file optional npgsqlrest appsettings.json -o appsettings.Development.json
340
+ Example: override ApplicationName config npgsqlrest --applicationname=Test
341
+ Example: override Auth:CookieName config npgsqlrest --auth:cookiename=Test
342
+ ...
343
+ ```
344
+
345
+ ## System Requirements
346
+ - PostgreSQL >= 13
347
+ - No runtime dependencies - native executable
348
+
349
+ ## .NET Library Integration
350
+ For integrating into existing .NET applications:
351
+ ```console
352
+ dotnet add package NpgsqlRest
353
+ ```
354
+
355
+ Note: PostgreSQL 13 minimal version is required to run the initial query to get the list of functions. The source code of this query can be found [here](https://github.com/NpgsqlRest/NpgsqlRest/blob/master/NpgsqlRest/RoutineQuery.cs). For versions prior to version 13, this query can be replaced with a custom query that can run on older versions.
356
+
357
+ ## Contributing
358
+
359
+ Contributions from the community are welcome.
360
+ Please make a pull request with a description if you wish to contribute.
361
+
362
+ ## License
363
+
364
+ This project is licensed under the terms of the MIT license.
package/uninstall.js CHANGED
@@ -1,21 +1,21 @@
1
- #!/usr/bin/env node
2
-
3
- const fs = require("fs");
4
- const os = require("os");
5
-
6
- const downloadDir = "../.bin/";
7
- const osType = os.type();
8
-
9
- var downloadTo;
10
-
11
- if (osType === "Windows_NT") {
12
- downloadTo = `${downloadDir}npgsqlrest.exe`;
13
- } else {
14
- downloadTo = `${downloadDir}npgsqlrest`;
15
- }
16
-
17
- if (fs.existsSync(downloadTo)) {
18
- fs.unlinkSync(downloadTo);
19
- }
20
-
21
-
1
+ #!/usr/bin/env node
2
+
3
+ const fs = require("fs");
4
+ const os = require("os");
5
+
6
+ const downloadDir = "../.bin/";
7
+ const osType = os.type();
8
+
9
+ var downloadTo;
10
+
11
+ if (osType === "Windows_NT") {
12
+ downloadTo = `${downloadDir}npgsqlrest.exe`;
13
+ } else {
14
+ downloadTo = `${downloadDir}npgsqlrest`;
15
+ }
16
+
17
+ if (fs.existsSync(downloadTo)) {
18
+ fs.unlinkSync(downloadTo);
19
+ }
20
+
21
+