From d8bac653a1229153fadf59914101f11dcb8a30e3 Mon Sep 17 00:00:00 2001 From: leorossi Date: Wed, 13 Sep 2023 13:23:10 +0000 Subject: [PATCH] [automated commit] Bump docs to version 0.41.1 --- .../version-0.35.4/reference/db/dashboard.md | 58 ------- .../reference/runtime/programmatic.md | 46 ------ .../reference/start/programmatic.md | 110 -------------- .../contributing/contributing.md | 0 .../contributing/documentation-style-guide.md | 0 .../getting-started/architecture.md | 0 .../movie-quotes-app-tutorial.md | 2 +- .../new-api-project-instructions.md | 0 .../platformatic-architecture.png | Bin .../platformatid-db-architecture.excalidraw | 0 .../getting-started/quick-start-guide.md | 2 +- .../extend-graphql.md | 0 .../add-custom-functionality/extend-rest.md | 0 .../add-custom-functionality/introduction.md | 0 .../add-custom-functionality/prerequisites.md | 0 .../add-custom-functionality/raw-sql.md | 36 +++++ .../compiling-typescript-for-deployment.md | 0 .../guides/debug-platformatic-db.md | 0 .../guides/deploying-on-lambda.md | 0 .../deployment/advanced-fly-io-deployment.md | 0 .../deploy-to-fly-io-with-sqlite.md | 0 .../guides/deployment/deployment.md | 0 .../guides/dockerize-platformatic-app.md | 99 ++++++++++++ ...d-code-to-consume-platformatic-rest-api.md | 10 ++ .../guides/images/frontend-screenshot-1.jpg | Bin .../guides/images/frontend-screenshot-2.jpg | Bin .../guides/images/frontend-screenshot-3.jpg | Bin .../guides/images/frontend-screenshot-4.jpg | Bin .../guides/jwt-auth0.md | 0 ...ing-express-app-to-platformatic-service.md | 0 ...ing-fastify-app-to-platformatic-service.md | 0 .../guides/monitoring.md | 0 .../packaging-an-application-as-a-module.md | 129 ++++++++++++++++ .../guides/prisma.md | 34 ++--- .../guides/securing-platformatic-db.md | 0 .../guides/seed-a-database.md | 0 .../telemetry-images/compose-openapi.png | Bin .../guides/telemetry-images/jaeger-1.png | Bin .../guides/telemetry-images/jaeger-2.png | Bin .../guides/telemetry-images/jaeger-3.png | Bin .../guides/telemetry.md | 0 .../deploy-database-neon.md | 77 +++------- .../app-workspace-static-deployed.png | Bin .../button-continue-with-github.png | Bin .../quick-start-guide/cloud-apps-empty.png | Bin .../github-pr-deploy-comment.png | Bin .../github-pr-deploy-in-progress.png | Bin .../quick-start-guide/hello-json-response.png | Bin .../platformatic-db-swagger-ui.png | Bin .../workspace-create-dynamic.png | Bin .../platformatic-cloud/pricing.md | 0 .../platformatic-cloud/quick-start-guide.md | 4 +- .../reference/cli.md | 15 +- .../reference/client/frontend.md | 143 ++++++++++++++++++ .../reference/client/introduction.md | 0 .../reference/client/programmatic.md | 0 .../reference/composer/api-modification.md | 0 .../reference/composer/configuration.md | 6 +- .../reference/composer/introduction.md | 0 .../reference/composer/plugin.md | 0 .../reference/composer/programmatic.md | 0 .../db/authorization/images/http.png | Bin .../reference/db/authorization/images/jwt.png | Bin .../images/sources/http.excalidraw | 0 .../images/sources/jwt.excalidraw | 0 .../images/sources/webhook.excalidraw | 0 .../db/authorization/images/webhook.png | Bin .../db/authorization/introduction.md | 0 .../reference/db/authorization/rules.md | 0 .../reference/db/authorization/strategies.md | 0 .../db/authorization/user-roles-metadata.md | 0 .../reference/db/configuration.md | 33 ++-- .../reference/db/introduction.md | 0 .../reference/db/logging.md | 0 .../reference/db/migrations.md | 0 .../reference/db/plugin.md | 3 +- .../reference/db/programmatic.md | 0 .../reference/db/schema-support.md | 0 .../reference/runtime/configuration.md | 6 +- .../reference/runtime/introduction.md | 0 .../reference/runtime/programmatic.md | 98 ++++++++++++ .../reference/service/configuration.md | 6 +- .../reference/service/introduction.md | 0 .../reference/service/plugin.md | 0 .../reference/service/programmatic.md | 42 +++-- .../reference/sql-events/fastify-plugin.md | 0 .../reference/sql-events/introduction.md | 0 .../sql-graphql/examples/deleteEntity.js | 0 .../sql-graphql/examples/insertEntity.js | 0 .../reference/sql-graphql/examples/query.js | 0 .../sql-graphql/examples/saveEntity.js | 0 .../reference/sql-graphql/ignore.md | 0 .../reference/sql-graphql/introduction.md | 0 .../reference/sql-graphql/many-to-many.md | 0 .../reference/sql-graphql/mutations.md | 0 .../reference/sql-graphql/queries.md | 0 .../reference/sql-graphql/subscriptions.md | 0 .../reference/sql-mapper/entities/api.md | 0 .../reference/sql-mapper/entities/example.md | 0 .../reference/sql-mapper/entities/fields.md | 0 .../reference/sql-mapper/entities/hooks.md | 0 .../sql-mapper/entities/introduction.md | 0 .../sql-mapper/entities/relations.md | 0 .../sql-mapper/entities/timestamps.md | 0 .../sql-mapper/entities/transactions.md | 0 .../reference/sql-mapper/examples/count.js | 0 .../reference/sql-mapper/examples/delete.js | 0 .../sql-mapper/examples/fastify-plugin.js | 0 .../reference/sql-mapper/examples/fields.js | 0 .../reference/sql-mapper/examples/find.js | 0 .../reference/sql-mapper/examples/hooks.js | 0 .../reference/sql-mapper/examples/insert.js | 0 .../sql-mapper/examples/relations.js | 0 .../reference/sql-mapper/examples/save.js | 0 .../reference/sql-mapper/fastify-plugin.md | 2 +- .../sql-mapper/images/plt-db-hooks.svg | 0 .../reference/sql-mapper/introduction.md | 39 ++++- .../reference/sql-openapi/api.md | 0 .../reference/sql-openapi/ignore.md | 0 .../reference/sql-openapi/introduction.md | 0 ...bars.json => version-0.41.1-sidebars.json} | 20 +-- versions.json | 4 +- 122 files changed, 668 insertions(+), 356 deletions(-) delete mode 100644 versioned_docs/version-0.35.4/reference/db/dashboard.md delete mode 100644 versioned_docs/version-0.35.4/reference/runtime/programmatic.md delete mode 100644 versioned_docs/version-0.35.4/reference/start/programmatic.md rename versioned_docs/{version-0.35.4 => version-0.41.1}/contributing/contributing.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/contributing/documentation-style-guide.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/getting-started/architecture.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/getting-started/movie-quotes-app-tutorial.md (99%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/getting-started/new-api-project-instructions.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/getting-started/platformatic-architecture.png (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/getting-started/platformatid-db-architecture.excalidraw (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/getting-started/quick-start-guide.md (99%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/add-custom-functionality/extend-graphql.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/add-custom-functionality/extend-rest.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/add-custom-functionality/introduction.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/add-custom-functionality/prerequisites.md (100%) create mode 100644 versioned_docs/version-0.41.1/guides/add-custom-functionality/raw-sql.md rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/compiling-typescript-for-deployment.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/debug-platformatic-db.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/deploying-on-lambda.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/deployment/advanced-fly-io-deployment.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/deployment/deploy-to-fly-io-with-sqlite.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/deployment/deployment.md (100%) create mode 100644 versioned_docs/version-0.41.1/guides/dockerize-platformatic-app.md rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/generate-frontend-code-to-consume-platformatic-rest-api.md (97%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/images/frontend-screenshot-1.jpg (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/images/frontend-screenshot-2.jpg (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/images/frontend-screenshot-3.jpg (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/images/frontend-screenshot-4.jpg (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/jwt-auth0.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/migrating-express-app-to-platformatic-service.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/migrating-fastify-app-to-platformatic-service.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/monitoring.md (100%) create mode 100644 versioned_docs/version-0.41.1/guides/packaging-an-application-as-a-module.md rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/prisma.md (97%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/securing-platformatic-db.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/seed-a-database.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/telemetry-images/compose-openapi.png (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/telemetry-images/jaeger-1.png (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/telemetry-images/jaeger-2.png (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/telemetry-images/jaeger-3.png (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/guides/telemetry.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/platformatic-cloud/deploy-database-neon.md (71%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/platformatic-cloud/images/quick-start-guide/app-workspace-static-deployed.png (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/platformatic-cloud/images/quick-start-guide/button-continue-with-github.png (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/platformatic-cloud/images/quick-start-guide/cloud-apps-empty.png (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/platformatic-cloud/images/quick-start-guide/github-pr-deploy-comment.png (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/platformatic-cloud/images/quick-start-guide/github-pr-deploy-in-progress.png (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/platformatic-cloud/images/quick-start-guide/hello-json-response.png (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/platformatic-cloud/images/quick-start-guide/platformatic-db-swagger-ui.png (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/platformatic-cloud/images/quick-start-guide/workspace-create-dynamic.png (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/platformatic-cloud/pricing.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/platformatic-cloud/quick-start-guide.md (98%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/cli.md (97%) create mode 100644 versioned_docs/version-0.41.1/reference/client/frontend.md rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/client/introduction.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/client/programmatic.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/composer/api-modification.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/composer/configuration.md (96%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/composer/introduction.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/composer/plugin.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/composer/programmatic.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/db/authorization/images/http.png (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/db/authorization/images/jwt.png (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/db/authorization/images/sources/http.excalidraw (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/db/authorization/images/sources/jwt.excalidraw (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/db/authorization/images/sources/webhook.excalidraw (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/db/authorization/images/webhook.png (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/db/authorization/introduction.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/db/authorization/rules.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/db/authorization/strategies.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/db/authorization/user-roles-metadata.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/db/configuration.md (95%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/db/introduction.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/db/logging.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/db/migrations.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/db/plugin.md (96%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/db/programmatic.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/db/schema-support.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/runtime/configuration.md (94%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/runtime/introduction.md (100%) create mode 100644 versioned_docs/version-0.41.1/reference/runtime/programmatic.md rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/service/configuration.md (96%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/service/introduction.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/service/plugin.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/service/programmatic.md (58%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-events/fastify-plugin.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-events/introduction.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-graphql/examples/deleteEntity.js (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-graphql/examples/insertEntity.js (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-graphql/examples/query.js (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-graphql/examples/saveEntity.js (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-graphql/ignore.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-graphql/introduction.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-graphql/many-to-many.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-graphql/mutations.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-graphql/queries.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-graphql/subscriptions.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/entities/api.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/entities/example.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/entities/fields.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/entities/hooks.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/entities/introduction.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/entities/relations.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/entities/timestamps.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/entities/transactions.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/examples/count.js (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/examples/delete.js (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/examples/fastify-plugin.js (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/examples/fields.js (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/examples/find.js (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/examples/hooks.js (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/examples/insert.js (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/examples/relations.js (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/examples/save.js (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/fastify-plugin.md (98%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/images/plt-db-hooks.svg (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-mapper/introduction.md (61%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-openapi/api.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-openapi/ignore.md (100%) rename versioned_docs/{version-0.35.4 => version-0.41.1}/reference/sql-openapi/introduction.md (100%) rename versioned_sidebars/{version-0.35.4-sidebars.json => version-0.41.1-sidebars.json} (94%) diff --git a/versioned_docs/version-0.35.4/reference/db/dashboard.md b/versioned_docs/version-0.35.4/reference/db/dashboard.md deleted file mode 100644 index dbe2aaa8d3..0000000000 --- a/versioned_docs/version-0.35.4/reference/db/dashboard.md +++ /dev/null @@ -1,58 +0,0 @@ -# Platformatic DB Dashboard - -The Platformatic DB has a dashboard used to do several actions like see the current configuration and access documentation for your generated API. - -:::info - -Be sure to set `dashboard: true` on your `platformatic.db.json`, as mentioned on the [config docs](/docs/reference/db/configuration/#dashboard). - -::: - -It also integrates GraphiQL, to run queries and mutations against Platformatic DB Server. - -:::tip - -As mentioned on the [config docs](/docs/reference/db/configuration#metrics), adding `metrics: true` will allow to add also the Platformatic metrics to the dashboard. - -::: - -## Development Server - -If you want to contribute on the dashboard, it needs to know where is Platformatic DB Server. - -Create a `./packages/db-dashboard/.env` file with the following content -``` -VITE_SERVER_URL=http://localhost:3042 -``` - -If you set up Platformatic DB with a custom path for dashboard (found in `dashboard.path` config value), you have to add -``` -VITE_DASHBOARD_PATH=/your-custom-endpoint -``` - -Note that this value is configured automatically by the script in `scripts/fix-dashboard-env.js` that is executed before `dashboard:build`. - -Or whatever port you are running platformatic DB server on. - -:::note - -Please double check the host too: if platformatic is running on `127.0.0.1` and you set `localhost` as `VITE_SERVER_URL`, you'll get CORS errors. - -::: - -Then run -```sh -pnpm run dashboard:start -``` - -You'll get vite's development server up and running. - -## Build - -Just run -```sh -pnpm run dashboard:build -``` - -And `vite` will create a production ready bundle that will be served by Platformatic DB. - diff --git a/versioned_docs/version-0.35.4/reference/runtime/programmatic.md b/versioned_docs/version-0.35.4/reference/runtime/programmatic.md deleted file mode 100644 index d04bf6e02c..0000000000 --- a/versioned_docs/version-0.35.4/reference/runtime/programmatic.md +++ /dev/null @@ -1,46 +0,0 @@ -# Programmatic API - -In many cases it's useful to start Platformatic Runtime using an API instead of -command line, e.g. in tests we want to start and stop our server. - -The `buildServer` function allows that: - -```js -import { buildServer } from '@platformatic/runtime' - -const app = await buildServer('path/to/platformatic.runtime.json') -const entrypointUrl = await app.start() - -// Make a request to the entrypoint. -const res = await fetch(entrypointUrl) -console.log(await res.json()) - -// Do other interesting things. - -await app.close() -``` - -It is also possible to customize the configuration: - -```js -import { buildServer } from '@platformatic/runtime' - -const app = await buildServer({ - $schema: 'https://platformatic.dev/schemas/v0.26.0/runtime', - entrypoint: 'entrypointApp', - autoload: { - path: './packages', - exclude: ['docs'] - } -}) - -const entrypointUrl = await app.start() - -// Make a request to the entrypoint. -const res = await fetch(entrypointUrl) -console.log(await res.json()) - -// Do other interesting things. - -await app.close() -``` diff --git a/versioned_docs/version-0.35.4/reference/start/programmatic.md b/versioned_docs/version-0.35.4/reference/start/programmatic.md deleted file mode 100644 index 9291c2ae85..0000000000 --- a/versioned_docs/version-0.35.4/reference/start/programmatic.md +++ /dev/null @@ -1,110 +0,0 @@ -# Programmatic API - -In many cases it's useful to start Platformatic applications using an API -instead of the command line. The `@platformatic/start` API makes it simple to -work with different application types (e.g. `service`, `db`) without needing to -know the application type a priori. - -## `buildServer()` - -The `buildServer` function creates a server from a provided configuration -object or configuration filename. - -```js -import { buildServer } from '@platformatic/start' - -// This config can also be a config filename or obtained via loadConfig(). -const config = { - server: { - hostname: '127.0.0.1', - port: 0 - } -} -const app = await buildServer(config) - -await app.start() -``` - -## `getConfigType()` - -The `getConfigType` function takes an array of command line arguments and a -directory, and returns a string indicating the application type. - -```js -import { getConfigType } from '@platformatic/start' - -// Get the type from command line arguments. -const type = await getConfigType(['-c', '/path/to/platformatic.config.json']) - -// Search a directory for a config file and get the type from that file. -const type = await getConfigType(undefined, '/directory/of/project') - -// Search a the current working directory for a config file and get the type -// from that file. -const type = await getConfigType() -``` - -## `getCurrentSchema()` - -The `getCurrentSchema` function takes a Platformatic application type as input, -and returns the corresponding configuration file schema for the current version. -If the input is not a recognized application type, an exception will be thrown. - -```js -import { getCurrentSchema } from '@platformatic/start' - -// Get the type from command line arguments. -const type = await getCurrentSchema('service') -``` - -## `loadConfig()` - -The `loadConfig` function is used to read and parse a configuration file for -an arbitrary Platformatic application. - -```js -import { loadConfig } from '@platformatic/start' - -// Read the config based on command line arguments. loadConfig() will detect -// the application type. -const config = await loadConfig({}, ['-c', '/path/to/platformatic.config.json']) - -// Read the config based on command line arguments. The application type can -// be provided explicitly. -const config = await loadConfig( - {}, - ['-c', '/path/to/platformatic.config.json'], - undefined, - 'service' -) - -// Default config can be specified. -const config = await loadConfig( - {}, - ['-c', '/path/to/platformatic.config.json'], - { key: 'value' } -) -``` - -## `start()` - -The `start` function loads a configuration, builds a server, and starts the -server. However, the server is not returned. - -```js -import { start } from '@platformatic/start' - -await start(['-c', '/path/to/platformatic.config.json]) -``` - -## `startCommand()` - -The `startCommand` function is similar to `start`. However, if an exception -occurs, `startCommand` logs the error and exits the process. This is different -from `start`, which throws the exception. - -```js -import { start } from '@platformatic/start' - -await startCommand(['-c', '/path/to/platformatic.config.json]) -``` diff --git a/versioned_docs/version-0.35.4/contributing/contributing.md b/versioned_docs/version-0.41.1/contributing/contributing.md similarity index 100% rename from versioned_docs/version-0.35.4/contributing/contributing.md rename to versioned_docs/version-0.41.1/contributing/contributing.md diff --git a/versioned_docs/version-0.35.4/contributing/documentation-style-guide.md b/versioned_docs/version-0.41.1/contributing/documentation-style-guide.md similarity index 100% rename from versioned_docs/version-0.35.4/contributing/documentation-style-guide.md rename to versioned_docs/version-0.41.1/contributing/documentation-style-guide.md diff --git a/versioned_docs/version-0.35.4/getting-started/architecture.md b/versioned_docs/version-0.41.1/getting-started/architecture.md similarity index 100% rename from versioned_docs/version-0.35.4/getting-started/architecture.md rename to versioned_docs/version-0.41.1/getting-started/architecture.md diff --git a/versioned_docs/version-0.35.4/getting-started/movie-quotes-app-tutorial.md b/versioned_docs/version-0.41.1/getting-started/movie-quotes-app-tutorial.md similarity index 99% rename from versioned_docs/version-0.35.4/getting-started/movie-quotes-app-tutorial.md rename to versioned_docs/version-0.41.1/getting-started/movie-quotes-app-tutorial.md index b3e7f5cd35..eac609d91d 100644 --- a/versioned_docs/version-0.35.4/getting-started/movie-quotes-app-tutorial.md +++ b/versioned_docs/version-0.41.1/getting-started/movie-quotes-app-tutorial.md @@ -34,7 +34,7 @@ In this tutorial we'll learn how to: To follow along with this tutorial you'll need to have these things installed: -- [Node.js](https://nodejs.org/) >= v18.8.0 or >= v19.0.0 +- [Node.js](https://nodejs.org/) >= v18.8.0 or >= v20.6.0 - [npm](https://docs.npmjs.com/cli/) v7 or later - A code editor, for example [Visual Studio Code](https://code.visualstudio.com/) diff --git a/versioned_docs/version-0.35.4/getting-started/new-api-project-instructions.md b/versioned_docs/version-0.41.1/getting-started/new-api-project-instructions.md similarity index 100% rename from versioned_docs/version-0.35.4/getting-started/new-api-project-instructions.md rename to versioned_docs/version-0.41.1/getting-started/new-api-project-instructions.md diff --git a/versioned_docs/version-0.35.4/getting-started/platformatic-architecture.png b/versioned_docs/version-0.41.1/getting-started/platformatic-architecture.png similarity index 100% rename from versioned_docs/version-0.35.4/getting-started/platformatic-architecture.png rename to versioned_docs/version-0.41.1/getting-started/platformatic-architecture.png diff --git a/versioned_docs/version-0.35.4/getting-started/platformatid-db-architecture.excalidraw b/versioned_docs/version-0.41.1/getting-started/platformatid-db-architecture.excalidraw similarity index 100% rename from versioned_docs/version-0.35.4/getting-started/platformatid-db-architecture.excalidraw rename to versioned_docs/version-0.41.1/getting-started/platformatid-db-architecture.excalidraw diff --git a/versioned_docs/version-0.35.4/getting-started/quick-start-guide.md b/versioned_docs/version-0.41.1/getting-started/quick-start-guide.md similarity index 99% rename from versioned_docs/version-0.35.4/getting-started/quick-start-guide.md rename to versioned_docs/version-0.41.1/getting-started/quick-start-guide.md index ee3b1ad3fb..15a29342d8 100644 --- a/versioned_docs/version-0.35.4/getting-started/quick-start-guide.md +++ b/versioned_docs/version-0.41.1/getting-started/quick-start-guide.md @@ -22,7 +22,7 @@ Platformatic supports macOS, Linux and Windows ([WSL](https://docs.microsoft.com To follow along with this guide you'll need to have these things installed: -- [Node.js](https://nodejs.org/) >= v18.8.0 or >= v19.0.0 +- [Node.js](https://nodejs.org/) >= v18.8.0 or >= v20.6.0 - [npm](https://docs.npmjs.com/cli/) v7 or later - A code editor, for example [Visual Studio Code](https://code.visualstudio.com/) diff --git a/versioned_docs/version-0.35.4/guides/add-custom-functionality/extend-graphql.md b/versioned_docs/version-0.41.1/guides/add-custom-functionality/extend-graphql.md similarity index 100% rename from versioned_docs/version-0.35.4/guides/add-custom-functionality/extend-graphql.md rename to versioned_docs/version-0.41.1/guides/add-custom-functionality/extend-graphql.md diff --git a/versioned_docs/version-0.35.4/guides/add-custom-functionality/extend-rest.md b/versioned_docs/version-0.41.1/guides/add-custom-functionality/extend-rest.md similarity index 100% rename from versioned_docs/version-0.35.4/guides/add-custom-functionality/extend-rest.md rename to versioned_docs/version-0.41.1/guides/add-custom-functionality/extend-rest.md diff --git a/versioned_docs/version-0.35.4/guides/add-custom-functionality/introduction.md b/versioned_docs/version-0.41.1/guides/add-custom-functionality/introduction.md similarity index 100% rename from versioned_docs/version-0.35.4/guides/add-custom-functionality/introduction.md rename to versioned_docs/version-0.41.1/guides/add-custom-functionality/introduction.md diff --git a/versioned_docs/version-0.35.4/guides/add-custom-functionality/prerequisites.md b/versioned_docs/version-0.41.1/guides/add-custom-functionality/prerequisites.md similarity index 100% rename from versioned_docs/version-0.35.4/guides/add-custom-functionality/prerequisites.md rename to versioned_docs/version-0.41.1/guides/add-custom-functionality/prerequisites.md diff --git a/versioned_docs/version-0.41.1/guides/add-custom-functionality/raw-sql.md b/versioned_docs/version-0.41.1/guides/add-custom-functionality/raw-sql.md new file mode 100644 index 0000000000..26ea10791c --- /dev/null +++ b/versioned_docs/version-0.41.1/guides/add-custom-functionality/raw-sql.md @@ -0,0 +1,36 @@ +# Raw SQL queries + +To run raw SQL queries using plugins, use `app.platformatic.db.query` method and passe to it a sql query using the `app.platformatic.sql` method. + +```js +'use strict' +module.exports = async(app, opts) => { + app.graphql.extendSchema(` + type YearlySales { + year: Int + sales: Int + } + + extend type Query { + yearlySales: [YearlySales] + } + `) + app.graphql.defineResolvers({ + Query: { + yearlySales: async(_, { title }) => { + const { db, sql } = app.platformatic; + const res = await db.query(sql(` + SELECT + YEAR(created_at) AS year, + SUM(amount) AS sales + FROM + orders + GROUP BY + YEAR(created_at) + `)) + return res + } + } + }) +} +``` diff --git a/versioned_docs/version-0.35.4/guides/compiling-typescript-for-deployment.md b/versioned_docs/version-0.41.1/guides/compiling-typescript-for-deployment.md similarity index 100% rename from versioned_docs/version-0.35.4/guides/compiling-typescript-for-deployment.md rename to versioned_docs/version-0.41.1/guides/compiling-typescript-for-deployment.md diff --git a/versioned_docs/version-0.35.4/guides/debug-platformatic-db.md b/versioned_docs/version-0.41.1/guides/debug-platformatic-db.md similarity index 100% rename from versioned_docs/version-0.35.4/guides/debug-platformatic-db.md rename to versioned_docs/version-0.41.1/guides/debug-platformatic-db.md diff --git a/versioned_docs/version-0.35.4/guides/deploying-on-lambda.md b/versioned_docs/version-0.41.1/guides/deploying-on-lambda.md similarity index 100% rename from versioned_docs/version-0.35.4/guides/deploying-on-lambda.md rename to versioned_docs/version-0.41.1/guides/deploying-on-lambda.md diff --git a/versioned_docs/version-0.35.4/guides/deployment/advanced-fly-io-deployment.md b/versioned_docs/version-0.41.1/guides/deployment/advanced-fly-io-deployment.md similarity index 100% rename from versioned_docs/version-0.35.4/guides/deployment/advanced-fly-io-deployment.md rename to versioned_docs/version-0.41.1/guides/deployment/advanced-fly-io-deployment.md diff --git a/versioned_docs/version-0.35.4/guides/deployment/deploy-to-fly-io-with-sqlite.md b/versioned_docs/version-0.41.1/guides/deployment/deploy-to-fly-io-with-sqlite.md similarity index 100% rename from versioned_docs/version-0.35.4/guides/deployment/deploy-to-fly-io-with-sqlite.md rename to versioned_docs/version-0.41.1/guides/deployment/deploy-to-fly-io-with-sqlite.md diff --git a/versioned_docs/version-0.35.4/guides/deployment/deployment.md b/versioned_docs/version-0.41.1/guides/deployment/deployment.md similarity index 100% rename from versioned_docs/version-0.35.4/guides/deployment/deployment.md rename to versioned_docs/version-0.41.1/guides/deployment/deployment.md diff --git a/versioned_docs/version-0.41.1/guides/dockerize-platformatic-app.md b/versioned_docs/version-0.41.1/guides/dockerize-platformatic-app.md new file mode 100644 index 0000000000..e3aeac4eea --- /dev/null +++ b/versioned_docs/version-0.41.1/guides/dockerize-platformatic-app.md @@ -0,0 +1,99 @@ +import NewApiProjectInstructions from '../getting-started/new-api-project-instructions.md'; + +# Dockerize a Platformatic App + +This guide explains how to create a new Platformatic DB app, which connects to a PostgreSQL database. + +We will then create a `docker-compose.yml` file that will run both services in separate containers + +## Generate a Platformatic DB App + + + +## Create Docker image for the Platformatic DB App + +In this step you are going to create some files into the root project directory + +- `.dockerignore` - This file tells Docker to ignore some files when copying the directory into the image filesystem + +``` +node_modules +.env* +``` +- `start.sh` - This is our entrypoint. We will run migrations then start platformatic +```sh +#!/bin/sh + +echo "Running migrations..." && \ +npx platformatic db migrations apply && \ +echo "Starting Platformatic App..." && \ +npm start +``` +:::info +Make sure you make this file executable with the command `chmod +x start.sh` +::: + + +- `Dockerfile` - This is the file Docker uses to create the image + +``` +FROM node:18-alpine +WORKDIR /usr/src/app +COPY . . +RUN npm install +COPY . . +EXPOSE 3042 +CMD [ "./start.sh" ] +``` + +At this point you can build your Docker image with the command +```bash +$ docker build -t platformatic-app . +``` + +## Create Docker Compose config file + +`docker-compose.yml` is the configuration file for `docker-compose` which will spin up containers for both PostgresSQL and our Platformatic App + +```yml +version: "3.3" +services: + postgresql: + ports: + - "5433:5432" + image: "postgres:15-alpine" + environment: + - POSTGRES_PASSWORD=postgres + platformatic: + ports: + - "3042:3042" + image: 'platformatic-app:latest' + depends_on: + - postgresql + links: + - postgresql + environment: + PLT_SERVER_HOSTNAME: ${PLT_SERVER_HOSTNAME} + PORT: ${PORT} + PLT_SERVER_LOGGER_LEVEL: ${PLT_SERVER_LOGGER_LEVEL} + DATABASE_URL: postgres://postgres:postgres@postgresql:5432/postgres +``` + +A couple of things to notice: +- The Platformatic app is started only once the database container is up and running (`depends_on`). +- The Platformatic app is linked with `postgresql` service. Meaning that inside its container `ping postgresql` will be resolved with the internal ip of the database container. +- The environment is taken directly from the `.env` file created by the wizard + +You can now run your containers with + +```bash +$ docker-compose up # (-d if you want to send them in the background) +``` + +Everything should start smoothly, and you can access your app pointing your browser to `http://0.0.0.0:3042` + +To stop the app you can either press `CTRL-C` if you are running them in the foreground, or, if you used the `-d` flag, run +```bash +$ docker-compose down +``` + diff --git a/versioned_docs/version-0.35.4/guides/generate-frontend-code-to-consume-platformatic-rest-api.md b/versioned_docs/version-0.41.1/guides/generate-frontend-code-to-consume-platformatic-rest-api.md similarity index 97% rename from versioned_docs/version-0.35.4/guides/generate-frontend-code-to-consume-platformatic-rest-api.md rename to versioned_docs/version-0.41.1/guides/generate-frontend-code-to-consume-platformatic-rest-api.md index 355ccd6655..d1d9418773 100644 --- a/versioned_docs/version-0.35.4/guides/generate-frontend-code-to-consume-platformatic-rest-api.md +++ b/versioned_docs/version-0.41.1/guides/generate-frontend-code-to-consume-platformatic-rest-api.md @@ -172,6 +172,16 @@ export const createMovie: Api['createMovie'] = async (request) => { ``` +You can add a `--name` option to the command line to provide a custom name for the generated files. + +```bash +cd rest-api-frontend/src +npx platformatic frontend --name foobar http://127.0.0.1:3042 ts +``` + +will generated `foobar.ts` and `foobar-types.d.ts` + + ## React and Vue.js components that read, create, and update an entity You can copy/paste the following React or Vue.js components that import the code diff --git a/versioned_docs/version-0.35.4/guides/images/frontend-screenshot-1.jpg b/versioned_docs/version-0.41.1/guides/images/frontend-screenshot-1.jpg similarity index 100% rename from versioned_docs/version-0.35.4/guides/images/frontend-screenshot-1.jpg rename to versioned_docs/version-0.41.1/guides/images/frontend-screenshot-1.jpg diff --git a/versioned_docs/version-0.35.4/guides/images/frontend-screenshot-2.jpg b/versioned_docs/version-0.41.1/guides/images/frontend-screenshot-2.jpg similarity index 100% rename from versioned_docs/version-0.35.4/guides/images/frontend-screenshot-2.jpg rename to versioned_docs/version-0.41.1/guides/images/frontend-screenshot-2.jpg diff --git a/versioned_docs/version-0.35.4/guides/images/frontend-screenshot-3.jpg b/versioned_docs/version-0.41.1/guides/images/frontend-screenshot-3.jpg similarity index 100% rename from versioned_docs/version-0.35.4/guides/images/frontend-screenshot-3.jpg rename to versioned_docs/version-0.41.1/guides/images/frontend-screenshot-3.jpg diff --git a/versioned_docs/version-0.35.4/guides/images/frontend-screenshot-4.jpg b/versioned_docs/version-0.41.1/guides/images/frontend-screenshot-4.jpg similarity index 100% rename from versioned_docs/version-0.35.4/guides/images/frontend-screenshot-4.jpg rename to versioned_docs/version-0.41.1/guides/images/frontend-screenshot-4.jpg diff --git a/versioned_docs/version-0.35.4/guides/jwt-auth0.md b/versioned_docs/version-0.41.1/guides/jwt-auth0.md similarity index 100% rename from versioned_docs/version-0.35.4/guides/jwt-auth0.md rename to versioned_docs/version-0.41.1/guides/jwt-auth0.md diff --git a/versioned_docs/version-0.35.4/guides/migrating-express-app-to-platformatic-service.md b/versioned_docs/version-0.41.1/guides/migrating-express-app-to-platformatic-service.md similarity index 100% rename from versioned_docs/version-0.35.4/guides/migrating-express-app-to-platformatic-service.md rename to versioned_docs/version-0.41.1/guides/migrating-express-app-to-platformatic-service.md diff --git a/versioned_docs/version-0.35.4/guides/migrating-fastify-app-to-platformatic-service.md b/versioned_docs/version-0.41.1/guides/migrating-fastify-app-to-platformatic-service.md similarity index 100% rename from versioned_docs/version-0.35.4/guides/migrating-fastify-app-to-platformatic-service.md rename to versioned_docs/version-0.41.1/guides/migrating-fastify-app-to-platformatic-service.md diff --git a/versioned_docs/version-0.35.4/guides/monitoring.md b/versioned_docs/version-0.41.1/guides/monitoring.md similarity index 100% rename from versioned_docs/version-0.35.4/guides/monitoring.md rename to versioned_docs/version-0.41.1/guides/monitoring.md diff --git a/versioned_docs/version-0.41.1/guides/packaging-an-application-as-a-module.md b/versioned_docs/version-0.41.1/guides/packaging-an-application-as-a-module.md new file mode 100644 index 0000000000..51314a6006 --- /dev/null +++ b/versioned_docs/version-0.41.1/guides/packaging-an-application-as-a-module.md @@ -0,0 +1,129 @@ +# Packaging a Platformatic Application as a module + +[Platformatic Service](/docs/reference/db/introduction.md) and [Platformatic DB](/docs/reference/db/introduction.md) +offer a good starting point to create new applications. However, most developers or organizations might want to +create reusable services or applications built on top of Platformatic. +This is useful to publish the application on the public npm registry (or a private one!), including building your own CLI, +or to create a specialized template for your organization to allow for centralized bugfixes and updates. + +This process is the same one we use to maintain Platformatic DB and Platformatic Composer on top of Platformatic Service. + +## Creating a custom Service + +We are creating the module `foo.js` as follows: + +```js +const { schema, platformaticService } = require('@platformatic/service') + +/** @type {import('fastify').FastifyPluginAsync<{}>} */ +async function foo (app, opts) { + const text = app.platformatic.config.foo.text + app.get('/foo', async (request, reply) => { + return text + }) + + await platformaticService(app, opts) +} + +foo.configType = 'foo' + +// break Fastify encapsulation +foo[Symbol.for('skip-override')] = true + +// The schema for our configuration file +foo.schema = { + $id: 'https://example.com/schemas/foo.json', + title: 'Foo Service', + type: 'object', + properties: { + server: schema.server, + plugins: schema.plugins, + metrics: schema.metrics, + watch: { + anyOf: [schema.watch, { + type: 'boolean' + }, { + type: 'string' + }] + }, + $schema: { + type: 'string' + }, + module: { + type: 'string' + }, + foo: { + type: 'object', + properties: { + text: { + type: 'string' + } + }, + required: ['text'] + } + }, + additionalProperties: false, + required: ['server'] +} + +// The configuration for the ConfigManager +foo.configManagerConfig = { + schema: foo.schema, + envWhitelist: ['PORT', 'HOSTNAME'], + allowToWatch: ['.env'], + schemaOptions: { + useDefaults: true, + coerceTypes: true, + allErrors: true, + strict: false + } +} + +module.exports = foo +``` + +Note that the `$id` property of the schema identifies the module in our system, +allowing us to retrieve the schema correctly. +It is recommended, but not required, that the JSON schema is actually +published in this location. Doing so allows tooling such as the VSCode +language server to provide autocompletion. + +In this example, the `schema` adds a custom top-level `foo` property +that users can use to configure this specific module. + +ESM is also supported. + +## Consuming a custom application + +Consuming `foo.js` is simple. We can create a `platformatic.json` file as follows: + +```json +{ + "$schema": "https://example.com/schemas/foo.json", + "module": "./foo", + "server": { + "port": 0, + "hostname": "127.0.0.1" + }, + "foo": { + "text": "Hello World" + } +} +``` + +Note that we __must__ specify both the `$schema` property and `module`. +Module can also be any modules published on npm and installed via your package manager. + +## Building your own CLI + +It is possible to build your own CLI with the following `cli.mjs` file: + +``` +import foo from './foo.js' +import { start } from '@platformatic/service' +import { printAndExitLoadConfigError } from '@platformatic/config' + +await start(foo, process.argv.splice(2)).catch(printConfigValidationErrors) +``` + +This will also load `platformatic.foo.json` files. diff --git a/versioned_docs/version-0.35.4/guides/prisma.md b/versioned_docs/version-0.41.1/guides/prisma.md similarity index 97% rename from versioned_docs/version-0.35.4/guides/prisma.md rename to versioned_docs/version-0.41.1/guides/prisma.md index 91b83d70a1..9ed8728717 100644 --- a/versioned_docs/version-0.35.4/guides/prisma.md +++ b/versioned_docs/version-0.41.1/guides/prisma.md @@ -4,7 +4,7 @@ Prisma can be used with JavaScript or TypeScript, and provides a level to type-safety that goes beyond the guarantees made by other ORMs in the TypeScript ecosystem. You can find an in-depth comparison of Prisma against other ORMs [here](https://www.prisma.io/docs/concepts/more/comparisons). -If you want to get a quick overview of how Prisma works, you can follow the [Quickstart](https://www.prisma.io/docs/getting-started/quickstart) or read the [Introduction](https://www.prisma.io/docs/understand-prisma/introduction) in the Prisma documentation. +If you want to get a quick overview of how Prisma works, you can follow the [Quickstart](https://www.prisma.io/docs/getting-started/quickstart) or read the [Introduction](https://www.prisma.io/docs/understand-prisma/introduction) in the Prisma documentation. ## How Prisma can improve your workflow with Platformatic DB @@ -21,7 +21,7 @@ You can learn more about why Prisma and Platformatic are a great match [this art ## Prerequisites To follow along with this guide, you will need to have the following: -- [Node.js](https://nodejs.org/) >= v16.17.0 or >= v18.8.0 +- [Node.js](https://nodejs.org/) >= v18.8.0 or >= v20.6.0 - [npm](https://docs.npmjs.com/cli/) v7 or later - A code editor, for example [Visual Studio Code](https://code.visualstudio.com/) - A Platformatic DB project @@ -45,13 +45,13 @@ This command does the following: - Creates a new directory called `prisma` which contains a file called `schema.prisma`. This file defines your database connection and the Prisma Client generator. - Creates a `.env` file at the root of your project if it doesn't exist. This defines your environment variables (used for your database connection). -You can specify your preferred database provider using the `--datasource-provider` flag, followed by the name of the provider: +You can specify your preferred database provider using the `--datasource-provider` flag, followed by the name of the provider: ```bash npx prisma init --datasource-provider postgresql # or sqlite, mysql, sqlserver, cockroachdb ``` -Prisma uses the `DATABASE_URL` environment variable to connect to your database to sync your database and Prisma schema. It also uses the variable to connect to your database to run your Prisma Client queries. +Prisma uses the `DATABASE_URL` environment variable to connect to your database to sync your database and Prisma schema. It also uses the variable to connect to your database to run your Prisma Client queries. If you're using PostgreSQL, MySQL, SQL Server, or CockroachDB, ensure that the `DATABASE_URL` used by Prisma is the same as the one used by Platformatic DB project. If you're using SQLite, refer to the [Using Prisma with SQLite](#using-prisma-with-sqlite) section. @@ -218,11 +218,11 @@ Plugins allow you to add custom functionality to your REST and GraphQL API. Refe :::danger -Prisma Client usage with Platformatic is currently only supported in Node v18 +Prisma Client usage with Platformatic is currently only supported in Node v18 ::: -You can use Prisma Client to interact with your database in your plugin. +You can use Prisma Client to interact with your database in your plugin. To get started, run the following command: @@ -241,23 +241,23 @@ npm install @sabinthedev/fastify-prisma Register the plugin and extend your REST API: ```js -// 1. +// 1. const prismaPlugin = require("@sabinthedev/fastify-prisma") module.exports = async (app) => { app.log.info('plugin loaded') - - // 2. + + // 2. app.register(prismaPlugin) - - /** + + /** * Plugin logic */ // 3. app.put('/post/:id/views', async (req, reply) => { - + const { id } = req.params - + // 4. const post = await app.prisma.post.update({ where: { @@ -269,7 +269,7 @@ module.exports = async (app) => { } } }) - + // 5. return reply.send(post) }) @@ -321,7 +321,7 @@ module.exports = async (app) => { } ``` -Start the server: +Start the server: ```bash npx platformatic db start @@ -335,7 +335,7 @@ You can also use the Prisma Client in your REST API endpoints. ### Using Prisma with SQLite -Currently, Prisma doesn't resolve the file path of a SQLite database the same way as Platformatic does. +Currently, Prisma doesn't resolve the file path of a SQLite database the same way as Platformatic does. If your database is at the root of the project, create a new environment variable that Prisma will use called `PRISMA_DATABASE_URL`: @@ -364,7 +364,7 @@ Foreign key names should use underscores, e.g. `author_id`, for Platformatic DB Table names should be mapped to use the naming convention expected by Platformatic DB e.g. `@@map("recipes")` (the Prisma convention is Recipe, which corresponds with the model name). You can use [`prisma-case-format`](https://github.com/iiian/prisma-case-format) to enforce your own database conventions, i.e., pascal, camel, and snake casing. - + ## Learn more If you would like to learn more about Prisma, be sure to check out the [Prisma docs](https://www.prisma.io/docs). diff --git a/versioned_docs/version-0.35.4/guides/securing-platformatic-db.md b/versioned_docs/version-0.41.1/guides/securing-platformatic-db.md similarity index 100% rename from versioned_docs/version-0.35.4/guides/securing-platformatic-db.md rename to versioned_docs/version-0.41.1/guides/securing-platformatic-db.md diff --git a/versioned_docs/version-0.35.4/guides/seed-a-database.md b/versioned_docs/version-0.41.1/guides/seed-a-database.md similarity index 100% rename from versioned_docs/version-0.35.4/guides/seed-a-database.md rename to versioned_docs/version-0.41.1/guides/seed-a-database.md diff --git a/versioned_docs/version-0.35.4/guides/telemetry-images/compose-openapi.png b/versioned_docs/version-0.41.1/guides/telemetry-images/compose-openapi.png similarity index 100% rename from versioned_docs/version-0.35.4/guides/telemetry-images/compose-openapi.png rename to versioned_docs/version-0.41.1/guides/telemetry-images/compose-openapi.png diff --git a/versioned_docs/version-0.35.4/guides/telemetry-images/jaeger-1.png b/versioned_docs/version-0.41.1/guides/telemetry-images/jaeger-1.png similarity index 100% rename from versioned_docs/version-0.35.4/guides/telemetry-images/jaeger-1.png rename to versioned_docs/version-0.41.1/guides/telemetry-images/jaeger-1.png diff --git a/versioned_docs/version-0.35.4/guides/telemetry-images/jaeger-2.png b/versioned_docs/version-0.41.1/guides/telemetry-images/jaeger-2.png similarity index 100% rename from versioned_docs/version-0.35.4/guides/telemetry-images/jaeger-2.png rename to versioned_docs/version-0.41.1/guides/telemetry-images/jaeger-2.png diff --git a/versioned_docs/version-0.35.4/guides/telemetry-images/jaeger-3.png b/versioned_docs/version-0.41.1/guides/telemetry-images/jaeger-3.png similarity index 100% rename from versioned_docs/version-0.35.4/guides/telemetry-images/jaeger-3.png rename to versioned_docs/version-0.41.1/guides/telemetry-images/jaeger-3.png diff --git a/versioned_docs/version-0.35.4/guides/telemetry.md b/versioned_docs/version-0.41.1/guides/telemetry.md similarity index 100% rename from versioned_docs/version-0.35.4/guides/telemetry.md rename to versioned_docs/version-0.41.1/guides/telemetry.md diff --git a/versioned_docs/version-0.35.4/platformatic-cloud/deploy-database-neon.md b/versioned_docs/version-0.41.1/platformatic-cloud/deploy-database-neon.md similarity index 71% rename from versioned_docs/version-0.35.4/platformatic-cloud/deploy-database-neon.md rename to versioned_docs/version-0.41.1/platformatic-cloud/deploy-database-neon.md index 9f11f8116e..8012da0fd0 100644 --- a/versioned_docs/version-0.35.4/platformatic-cloud/deploy-database-neon.md +++ b/versioned_docs/version-0.41.1/platformatic-cloud/deploy-database-neon.md @@ -21,8 +21,6 @@ Take note of the following configuration setting values: * The connection string for your `main` branch database, to be stored in a `NEON_DB_URL_PRODUCTION` secret * The Project ID (available under the project **Settings**), to be stored in a `NEON_PROJECT_ID` secret * Your API key (available by clicking on your user icon > **Account > Developer settings**), to be stored under `NEON_API_KEY` -* The username specified in your database connection string (available under project **Dashboard > Connection Details**), to be stored in a `DBUSER` secret -* The password specified in your database connection string (available under project **Dashboard > Connection Details**), to be stored in a `DBPASSWORD` secret You can learn more about Neon API keys in their [Manage API Keys](https://neon.tech/docs/manage/api-keys) documentation. @@ -40,8 +38,6 @@ Configure the GitHub Environments for your repository to have: * `previews` secrets available to all branches: - `NEON_PROJECT_ID` - `NEON_API_KEY` - - `DBUSER` - - `DBPASSWORD` ## Configure the main branch workflow @@ -66,7 +62,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout application project repository - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: npm install --omit=dev run: npm install --omit=dev - name: Deploy project @@ -100,7 +96,7 @@ request is merged. Replace the contents of your app's workflow for dynamic workspace deployment: ```yml title=".github/workflows/platformatic-dynamic-workspace-deploy.yml" -name: Deploy Platformatic application to the cloud +name: Deploy to Platformatic cloud on: pull_request: paths-ignore: @@ -114,48 +110,35 @@ concurrency: jobs: build_and_deploy: - environment: - name: previews - permissions: - contents: read - pull-requests: write runs-on: ubuntu-latest + environment: + name: development steps: - name: Checkout application project repository - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: npm install --omit=dev run: npm install --omit=dev - name: Get PR number id: get_pull_number run: | - pull_sha=$(jq --raw-output .pull_request.base.sha "$GITHUB_EVENT_PATH") - echo "pull_sha=${pull_sha}" >> $GITHUB_OUTPUT - echo $pull_sha - - uses: neondatabase/delete-branch-by-name-action@8260b587b411ffa0071bf68d0df2e37583aa719a - with: - project_id: ${{ secrets.NEON_PROJECT_ID }} - branch_name: ${{ steps.get_pull_number.outputs.pull_sha }} - api_key: ${{ secrets.NEON_API_KEY }} - - run: sleep 10 - - uses: neondatabase/create-branch-action@dc4ce9e0161722f64cedc66bb2aef72d556ccf7c + pull_number=$(jq --raw-output .pull_request.number "$GITHUB_EVENT_PATH") + echo "pull_number=${pull_number}" >> $GITHUB_OUTPUT + echo $pull_number + - uses: neondatabase/create-branch-action@v4 with: project_id: ${{ secrets.NEON_PROJECT_ID }} - branch_name: ${{ steps.get_pull_number.outputs.pull_sha }} + branch_name: pr-${{ steps.get_pull_number.outputs.pull_number }} api_key: ${{ secrets.NEON_API_KEY }} - username: ${{ secrets.DBUSER }} - Password: ${{ secrets.DBPASSWORD }} id: create-branch - - name: Get DATABASE_URL - run: echo DATABASE_URL=${{ steps.create-branch.outputs.db_url}}/neondb - name: Deploy project uses: platformatic/onestep@latest with: github_token: ${{ secrets.GITHUB_TOKEN }} - platformatic_workspace_id: - platformatic_workspace_key: ${{ secrets.PLATFORMATIC_DYNAMIC_WORKSPACE_API_KEY }} + platformatic_workspace_id: ${{ secrets.PLATFORMATIC_DYNAMIC_WORKSPACE_ID }} + platformatic_workspace_key: ${{ secrets.PLATFORMATIC_DYNAMIC_WORKSPACE_KEY }} platformatic_config_path: ./platformatic.db.json env: - DATABASE_URL: ${{ steps.create-branch.outputs.db_url}}/neondb + DATABASE_URL: ${{ steps.create-branch.outputs.db_url }} PLT_SERVER_LOGGER_LEVEL: info PORT: 3042 PLT_SERVER_HOSTNAME: 127.0.0.1 @@ -171,7 +154,7 @@ Create a new file, `.github/workflows/cleanup-neon-branch-db.yml`, and copy and workflow configuration: ```yml title=".github/workflows/cleanup-neon-branch-db.yml" -name: Cleanup Neon branch database +name: Cleanup Neon Database Branch on: push: branches: @@ -179,7 +162,7 @@ on: jobs: delete-branch: environment: - name: previews + name: development permissions: write-all runs-on: ubuntu-latest steps: @@ -188,36 +171,14 @@ jobs: uses: actions-ecosystem/action-get-merged-pull-request@v1.0.1 with: github_token: ${{secrets.GITHUB_TOKEN}} - - run: | echo ${{ steps.get-pr-info.outputs.number}} - - name: Get last commit SHA - id: get_sha - run: | - echo "sha=${{ github.event.before }}" >> $GITHUB_OUTPUT - - name: Search branch by name - id: get_branch_id - run: | - branch_id=$(curl --silent \ - "https://console.neon.tech/api/v2/projects/${PROJECT_ID}/branches" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --header "Authorization: Bearer ${API_KEY}" \ - | jq -r .branches \ - | jq -c '.[] | select(.name | contains("'${SHA}'")) .id' \ - | jq -r \ - ) \ - - echo "branch_id=${branch_id}" >> $GITHUB_OUTPUT - env: - PROJECT_ID: ${{ secrets.NEON_PROJECT_ID }} - API_KEY: ${{ secrets.NEON_API_KEY }} - SHA: ${{ steps.get_sha.outputs.sha }} - name: Delete Neon Branch - uses: neondatabase/delete-branch-action@v2 + if: ${{ steps.get-pr-info.outputs.number }} + uses: neondatabase/delete-branch-action@v3 with: project_id: ${{ secrets.NEON_PROJECT_ID }} - branch_id: ${{ steps.get_branch_id.outputs.branch_id }} + branch: pr-${{ steps.get-pr-info.outputs.number }} api_key: ${{ secrets.NEON_API_KEY }} ``` @@ -230,4 +191,4 @@ To deploy these changes to your app: 1. Create a Git branch locally (`git checkout -b `) 2. Commit your changes and push them to GitHub 3. Open a pull request on GitHub - a branch will automatically be created for your Neon database and a preview app will be deployed to Platformatic Cloud (in your app's dynamic workspace). -4. Merge the pull request - the Neon databsase branch will be automatically deleted and your app will be deployed to Platformatic Cloud (in your app's static workspace). \ No newline at end of file +4. Merge the pull request - the Neon databsase branch will be automatically deleted and your app will be deployed to Platformatic Cloud (in your app's static workspace). diff --git a/versioned_docs/version-0.35.4/platformatic-cloud/images/quick-start-guide/app-workspace-static-deployed.png b/versioned_docs/version-0.41.1/platformatic-cloud/images/quick-start-guide/app-workspace-static-deployed.png similarity index 100% rename from versioned_docs/version-0.35.4/platformatic-cloud/images/quick-start-guide/app-workspace-static-deployed.png rename to versioned_docs/version-0.41.1/platformatic-cloud/images/quick-start-guide/app-workspace-static-deployed.png diff --git a/versioned_docs/version-0.35.4/platformatic-cloud/images/quick-start-guide/button-continue-with-github.png b/versioned_docs/version-0.41.1/platformatic-cloud/images/quick-start-guide/button-continue-with-github.png similarity index 100% rename from versioned_docs/version-0.35.4/platformatic-cloud/images/quick-start-guide/button-continue-with-github.png rename to versioned_docs/version-0.41.1/platformatic-cloud/images/quick-start-guide/button-continue-with-github.png diff --git a/versioned_docs/version-0.35.4/platformatic-cloud/images/quick-start-guide/cloud-apps-empty.png b/versioned_docs/version-0.41.1/platformatic-cloud/images/quick-start-guide/cloud-apps-empty.png similarity index 100% rename from versioned_docs/version-0.35.4/platformatic-cloud/images/quick-start-guide/cloud-apps-empty.png rename to versioned_docs/version-0.41.1/platformatic-cloud/images/quick-start-guide/cloud-apps-empty.png diff --git a/versioned_docs/version-0.35.4/platformatic-cloud/images/quick-start-guide/github-pr-deploy-comment.png b/versioned_docs/version-0.41.1/platformatic-cloud/images/quick-start-guide/github-pr-deploy-comment.png similarity index 100% rename from versioned_docs/version-0.35.4/platformatic-cloud/images/quick-start-guide/github-pr-deploy-comment.png rename to versioned_docs/version-0.41.1/platformatic-cloud/images/quick-start-guide/github-pr-deploy-comment.png diff --git a/versioned_docs/version-0.35.4/platformatic-cloud/images/quick-start-guide/github-pr-deploy-in-progress.png b/versioned_docs/version-0.41.1/platformatic-cloud/images/quick-start-guide/github-pr-deploy-in-progress.png similarity index 100% rename from versioned_docs/version-0.35.4/platformatic-cloud/images/quick-start-guide/github-pr-deploy-in-progress.png rename to versioned_docs/version-0.41.1/platformatic-cloud/images/quick-start-guide/github-pr-deploy-in-progress.png diff --git a/versioned_docs/version-0.35.4/platformatic-cloud/images/quick-start-guide/hello-json-response.png b/versioned_docs/version-0.41.1/platformatic-cloud/images/quick-start-guide/hello-json-response.png similarity index 100% rename from versioned_docs/version-0.35.4/platformatic-cloud/images/quick-start-guide/hello-json-response.png rename to versioned_docs/version-0.41.1/platformatic-cloud/images/quick-start-guide/hello-json-response.png diff --git a/versioned_docs/version-0.35.4/platformatic-cloud/images/quick-start-guide/platformatic-db-swagger-ui.png b/versioned_docs/version-0.41.1/platformatic-cloud/images/quick-start-guide/platformatic-db-swagger-ui.png similarity index 100% rename from versioned_docs/version-0.35.4/platformatic-cloud/images/quick-start-guide/platformatic-db-swagger-ui.png rename to versioned_docs/version-0.41.1/platformatic-cloud/images/quick-start-guide/platformatic-db-swagger-ui.png diff --git a/versioned_docs/version-0.35.4/platformatic-cloud/images/quick-start-guide/workspace-create-dynamic.png b/versioned_docs/version-0.41.1/platformatic-cloud/images/quick-start-guide/workspace-create-dynamic.png similarity index 100% rename from versioned_docs/version-0.35.4/platformatic-cloud/images/quick-start-guide/workspace-create-dynamic.png rename to versioned_docs/version-0.41.1/platformatic-cloud/images/quick-start-guide/workspace-create-dynamic.png diff --git a/versioned_docs/version-0.35.4/platformatic-cloud/pricing.md b/versioned_docs/version-0.41.1/platformatic-cloud/pricing.md similarity index 100% rename from versioned_docs/version-0.35.4/platformatic-cloud/pricing.md rename to versioned_docs/version-0.41.1/platformatic-cloud/pricing.md diff --git a/versioned_docs/version-0.35.4/platformatic-cloud/quick-start-guide.md b/versioned_docs/version-0.41.1/platformatic-cloud/quick-start-guide.md similarity index 98% rename from versioned_docs/version-0.35.4/platformatic-cloud/quick-start-guide.md rename to versioned_docs/version-0.41.1/platformatic-cloud/quick-start-guide.md index a4a35ec638..7dddbe035b 100644 --- a/versioned_docs/version-0.35.4/platformatic-cloud/quick-start-guide.md +++ b/versioned_docs/version-0.41.1/platformatic-cloud/quick-start-guide.md @@ -14,7 +14,7 @@ Platformatic Cloud. To follow along with this guide you'll need to have these things installed: -- [Node.js](https://nodejs.org/) >= v18.8.0 +- [Node.js](https://nodejs.org/) >= v18.8.0 or >= v20.6.0 - [npm](https://docs.npmjs.com/cli/) v7 or later - A code editor, for example [Visual Studio Code](https://code.visualstudio.com/) @@ -241,4 +241,4 @@ Click on the **Application URL** link. If you add `/hello` on to the URL, you should receive a response from the endpoint that you just added to your application. -![Screenshot of a JSON response from an API endpoint](./images/quick-start-guide/hello-json-response.png) \ No newline at end of file +![Screenshot of a JSON response from an API endpoint](./images/quick-start-guide/hello-json-response.png) diff --git a/versioned_docs/version-0.35.4/reference/cli.md b/versioned_docs/version-0.41.1/reference/cli.md similarity index 97% rename from versioned_docs/version-0.35.4/reference/cli.md rename to versioned_docs/version-0.41.1/reference/cli.md index 5ee3dfadfe..c786d88b50 100644 --- a/versioned_docs/version-0.35.4/reference/cli.md +++ b/versioned_docs/version-0.41.1/reference/cli.md @@ -273,7 +273,11 @@ Options: * `-n, --name ` - Name of the client. * `-f, --folder ` - Name of the plugin folder, defaults to --name value. * `-t, --typescript` - Generate the client plugin in TypeScript. -* `-r, --full-response` - Client will return full response object rather than just the body. +* `--full-response` - Client will return full response object rather than just the body. +* `--full-request` - Client will be called with all parameters wrapped in `body`, `headers` and `query` properties. +* `--full` - Enables both `--full-request` and `--full-response` overriding them. +* `--optional-headers ` - Comma separated string of headers that will be marked as optional in the type file + ### composer @@ -758,6 +762,15 @@ npx platformatic frontend http://127.0.0.1:3042 ts > * `api.d.ts` - A TypeScript module that includes all the OpenAPI-related types. > * `api.ts` or `api.js` - A module that includes a function for every single REST endpoint. +If you use the `--name` option it will create custom file names. + +```bash +npx platformatic frontend http://127.0.0.1:3042 ts --name foobar +``` + +Will create `foobar.ts` and `foobar-types.d.ts` + + Refer to the [dedicated guide](https://docs.platformatic.dev/docs/guides/generate-frontend-code-to-consume-platformatic-rest-api) where the full process of generating and consuming the frontend code is described. In case of problems, please check that: diff --git a/versioned_docs/version-0.41.1/reference/client/frontend.md b/versioned_docs/version-0.41.1/reference/client/frontend.md new file mode 100644 index 0000000000..5273d3ff23 --- /dev/null +++ b/versioned_docs/version-0.41.1/reference/client/frontend.md @@ -0,0 +1,143 @@ +# Frontend client + +Create implementation and type files that exposes a client for a remote OpenAPI server, that uses `fetch` and can run in any browser. + +To create a client for a remote OpenAPI API, you can use the following command: + +```bash +$ platformatic frontend http://exmaple.com/to/schema/file --name +``` + +where `` can be either `js` or `ts`. + +This will create two files `clientname.js` (or `clientname.ts`) and `clientname-types.d.ts` for types. + +`clientname` by default is `api` + +## Usage + +The implementation generated by the tool exports all the named operation found and a factory object. + +### Named operations + +```js +import { setBaseUrl, getMovies } from './api.js' + +setBaseUrl('http://my-server-url.com') // modifies the global `baseUrl` variable + +const movies = await getMovies({}) +console.log(movies) +``` + +### Factory + +The factory object is called `build` and can be used like this + +```js +import build from './api.js' + +const client = build('http://my-server-url.com') + +const movies = await client.getMovies({}) +console.log(movies) +``` + +You can use both named operations and the factory in the same file. They can work on different hosts, so the factory does _not_ use the global `setBaseUrl` function. + +## Generated Code + +The type file will look like this + +```ts +export interface GetMoviesRequest { + 'limit'?: number; + 'offset'?: number; + // ... all other options +} + +interface GetMoviesResponseOK { + 'id': number; + 'title': string; +} +export interface Api { + setBaseUrl(newUrl: string) : void; + getMovies(req: GetMoviesRequest): Promise>; + // ... all operations listed here +} + +type PlatformaticFrontendClient = Omit +export default function build(url: string): PlatformaticFrontendClient +``` + +The *javascript* implementation will look like this + +```js +let baseUrl = '' +/** @type {import('./api-types.d.ts').Api['setBaseUrl']} */ +export const setBaseUrl = (newUrl) => { baseUrl = newUrl } + +/** @type {import('./api-types.d.ts').Api['getMovies']} */ +export const getMovies = async (request) => { + return await _getMovies(baseUrl, request) +} +async function _createMovie (url, request) { + const response = await fetch(`${url}/movies/`, { + method:'post', + body: JSON.stringify(request), + headers: { + 'Content-Type': 'application/json' + } + }) + + if (!response.ok) { + throw new Error(await response.text()) + } + + return await response.json() +} + +/** @type {import('./api-types.d.ts').Api['createMovie']} */ +export const createMovie = async (request) => { + return await _createMovie(baseUrl, request) +} +// ... + +export default function build (url) { + return { + getMovies: _getMovies.bind(url, ...arguments), + // ... + } +} +``` + +The *typescript* implementation will look like this + +```ts +import type { Api } from './api-types' +import * as Types from './api-types' + +let baseUrl = '' +export const setBaseUrl = (newUrl: string) : void => { baseUrl = newUrl } + +const _getMovies = async (url: string, request: Types.GetMoviesRequest) => { + const response = await fetch(`${url}/movies/?${new URLSearchParams(Object.entries(request || {})).toString()}`) + + if (!response.ok) { + throw new Error(await response.text()) + } + + return await response.json() +} + +export const getMovies: Api['getMovies'] = async (request: Types.GetMoviesRequest) => { + return await _getMovies(baseUrl, request) +} +// ... +export default function build (url) { + return { + getMovies: _getMovies.bind(url, ...arguments), + // ... + } +} +``` + diff --git a/versioned_docs/version-0.35.4/reference/client/introduction.md b/versioned_docs/version-0.41.1/reference/client/introduction.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/client/introduction.md rename to versioned_docs/version-0.41.1/reference/client/introduction.md diff --git a/versioned_docs/version-0.35.4/reference/client/programmatic.md b/versioned_docs/version-0.41.1/reference/client/programmatic.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/client/programmatic.md rename to versioned_docs/version-0.41.1/reference/client/programmatic.md diff --git a/versioned_docs/version-0.35.4/reference/composer/api-modification.md b/versioned_docs/version-0.41.1/reference/composer/api-modification.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/composer/api-modification.md rename to versioned_docs/version-0.41.1/reference/composer/api-modification.md diff --git a/versioned_docs/version-0.35.4/reference/composer/configuration.md b/versioned_docs/version-0.41.1/reference/composer/configuration.md similarity index 96% rename from versioned_docs/version-0.35.4/reference/composer/configuration.md rename to versioned_docs/version-0.41.1/reference/composer/configuration.md index 7fe39cb5b7..ae3ab073ed 100644 --- a/versioned_docs/version-0.35.4/reference/composer/configuration.md +++ b/versioned_docs/version-0.41.1/reference/composer/configuration.md @@ -273,8 +273,10 @@ _Examples_ - **`serviceName`** (**required**, `string`) — Name of the service as will be reported in open telemetry. - **`version`** (`string`) — Optional version (free form) -- **`skip`** (`array`). Optional list of operations to skip when exporting telemetry in the form of `${method}/${path}`. e.g.: `GET/documentation/json` -- **`exporter`** (`object`) — Exporter configuration object. If not defined, the exporter defaults to `console`. This object has the following properties: +- **`skip`** (`array`). Optional list of operations to skip when exporting telemetry defined `object` with properties: + - `method`: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE + - `path`. e.g.: `/documentation/json` +- **`exporter`** (`object` or `array`) — Exporter configuration. If not defined, the exporter defaults to `console`. If an array of objects is configured, every object must be a valid exporter object. The exporter object has the following properties: - **`type`** (`string`) — Exporter type. Supported values are `console`, `otlp`, `zipkin` and `memory` (default: `console`). `memory` is only supported for testing purposes. - **`options`** (`object`) — These options are supported: - **`url`** (`string`) — The URL to send the telemetry to. Required for `otlp` exporter. This has no effect on `console` and `memory` exporters. diff --git a/versioned_docs/version-0.35.4/reference/composer/introduction.md b/versioned_docs/version-0.41.1/reference/composer/introduction.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/composer/introduction.md rename to versioned_docs/version-0.41.1/reference/composer/introduction.md diff --git a/versioned_docs/version-0.35.4/reference/composer/plugin.md b/versioned_docs/version-0.41.1/reference/composer/plugin.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/composer/plugin.md rename to versioned_docs/version-0.41.1/reference/composer/plugin.md diff --git a/versioned_docs/version-0.35.4/reference/composer/programmatic.md b/versioned_docs/version-0.41.1/reference/composer/programmatic.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/composer/programmatic.md rename to versioned_docs/version-0.41.1/reference/composer/programmatic.md diff --git a/versioned_docs/version-0.35.4/reference/db/authorization/images/http.png b/versioned_docs/version-0.41.1/reference/db/authorization/images/http.png similarity index 100% rename from versioned_docs/version-0.35.4/reference/db/authorization/images/http.png rename to versioned_docs/version-0.41.1/reference/db/authorization/images/http.png diff --git a/versioned_docs/version-0.35.4/reference/db/authorization/images/jwt.png b/versioned_docs/version-0.41.1/reference/db/authorization/images/jwt.png similarity index 100% rename from versioned_docs/version-0.35.4/reference/db/authorization/images/jwt.png rename to versioned_docs/version-0.41.1/reference/db/authorization/images/jwt.png diff --git a/versioned_docs/version-0.35.4/reference/db/authorization/images/sources/http.excalidraw b/versioned_docs/version-0.41.1/reference/db/authorization/images/sources/http.excalidraw similarity index 100% rename from versioned_docs/version-0.35.4/reference/db/authorization/images/sources/http.excalidraw rename to versioned_docs/version-0.41.1/reference/db/authorization/images/sources/http.excalidraw diff --git a/versioned_docs/version-0.35.4/reference/db/authorization/images/sources/jwt.excalidraw b/versioned_docs/version-0.41.1/reference/db/authorization/images/sources/jwt.excalidraw similarity index 100% rename from versioned_docs/version-0.35.4/reference/db/authorization/images/sources/jwt.excalidraw rename to versioned_docs/version-0.41.1/reference/db/authorization/images/sources/jwt.excalidraw diff --git a/versioned_docs/version-0.35.4/reference/db/authorization/images/sources/webhook.excalidraw b/versioned_docs/version-0.41.1/reference/db/authorization/images/sources/webhook.excalidraw similarity index 100% rename from versioned_docs/version-0.35.4/reference/db/authorization/images/sources/webhook.excalidraw rename to versioned_docs/version-0.41.1/reference/db/authorization/images/sources/webhook.excalidraw diff --git a/versioned_docs/version-0.35.4/reference/db/authorization/images/webhook.png b/versioned_docs/version-0.41.1/reference/db/authorization/images/webhook.png similarity index 100% rename from versioned_docs/version-0.35.4/reference/db/authorization/images/webhook.png rename to versioned_docs/version-0.41.1/reference/db/authorization/images/webhook.png diff --git a/versioned_docs/version-0.35.4/reference/db/authorization/introduction.md b/versioned_docs/version-0.41.1/reference/db/authorization/introduction.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/db/authorization/introduction.md rename to versioned_docs/version-0.41.1/reference/db/authorization/introduction.md diff --git a/versioned_docs/version-0.35.4/reference/db/authorization/rules.md b/versioned_docs/version-0.41.1/reference/db/authorization/rules.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/db/authorization/rules.md rename to versioned_docs/version-0.41.1/reference/db/authorization/rules.md diff --git a/versioned_docs/version-0.35.4/reference/db/authorization/strategies.md b/versioned_docs/version-0.41.1/reference/db/authorization/strategies.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/db/authorization/strategies.md rename to versioned_docs/version-0.41.1/reference/db/authorization/strategies.md diff --git a/versioned_docs/version-0.35.4/reference/db/authorization/user-roles-metadata.md b/versioned_docs/version-0.41.1/reference/db/authorization/user-roles-metadata.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/db/authorization/user-roles-metadata.md rename to versioned_docs/version-0.41.1/reference/db/authorization/user-roles-metadata.md diff --git a/versioned_docs/version-0.35.4/reference/db/configuration.md b/versioned_docs/version-0.41.1/reference/db/configuration.md similarity index 95% rename from versioned_docs/version-0.35.4/reference/db/configuration.md rename to versioned_docs/version-0.41.1/reference/db/configuration.md index 6a57a24539..477e3bd015 100644 --- a/versioned_docs/version-0.35.4/reference/db/configuration.md +++ b/versioned_docs/version-0.41.1/reference/db/configuration.md @@ -34,7 +34,6 @@ Comments are supported by the JSON5, YAML and TOML file formats. Configuration settings are organised into the following groups: - [`db`](#db) **(required)** -- [`dashboard`](#dashboard) - [`metrics`](#metrics) - [`migrations`](#migrations) - [`plugins`](#plugins) @@ -296,20 +295,6 @@ A **required** object with the following settings: Starting Platformatic DB or running a migration will automatically create the schemalock file. -### `dashboard` - -This setting can be a `boolean` or an `object`. If set to `true` the dashboard will be served at the root path (`/`). - -Supported object properties: - -- **`path`** (`string`, default: `/`) — Make the dashboard available at the specified path. - -:::tip - -Read the [dashboard docs](/docs/reference/db/dashboard) to understand how to create a build or have the Vite's development server up and running. - -::: - ### `metrics` Configuration for a [Prometheus](https://prometheus.io/) server that will export monitoring metrics @@ -469,8 +454,7 @@ See the [fastify docs](https://www.fastify.io/docs/latest/Reference/Server) for An optional object with the following settings: -- `adminSecret` (`string`): A secret that will be required as a password to -access the Platformatic DB dashboard. This secret can also be sent in an +- `adminSecret` (`string`): A secret that should be sent in an `x-platformatic-admin-secret` HTTP header when performing GraphQL/REST API calls. Use an [environment variable placeholder](#environment-variable-placeholders) to securely provide the value for this setting. @@ -519,8 +503,10 @@ operations are allowed unless `adminSecret` is passed. - **`serviceName`** (**required**, `string`) — Name of the service as will be reported in open telemetry. - **`version`** (`string`) — Optional version (free form) -- **`skip`** (`array`). Optional list of operations to skip when exporting telemetry in the form of `${method}/${path}`. e.g.: `GET/documentation/json` -- **`exporter`** (`object`) — Exporter configuration object. If not defined, the exporter defaults to `console`. This object has the following properties: +- **`skip`** (`array`). Optional list of operations to skip when exporting telemetry defined `object` with properties: + - `method`: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE + - `path`. e.g.: `/documentation/json` +- **`exporter`** (`object` or `array`) — Exporter configuration. If not defined, the exporter defaults to `console`. If an array of objects is configured, every object must be a valid exporter object. The exporter object has the following properties: - **`type`** (`string`) — Exporter type. Supported values are `console`, `otlp`, `zipkin` and `memory` (default: `console`). `memory` is only supported for testing purposes. - **`options`** (`object`) — These options are supported: - **`url`** (`string`) — The URL to send the telemetry to. Required for `otlp` exporter. This has no effect on `console` and `memory` exporters. @@ -606,7 +592,9 @@ The default allow list can be extended by passing a `--allow-env` CLI option wit comma separated list of strings, for example: ```bash -npx platformatic db --allow-env=HOST,SERVER_LOGGER_LEVEL +npx platformatic db start --allow-env=HOST,SERVER_LOGGER_LEVEL +# OR +npx platformatic start --allow-env=HOST,SERVER_LOGGER_LEVEL ``` If `--allow-env` is passed as an option to the CLI, it will be merged with the @@ -614,7 +602,7 @@ default allow list. ## Sample Configuration -This is a bare minimum configuration for Platformatic DB. Uses a local `./db.sqlite` SQLite database, with OpenAPI and GraphQL support, and with the dashboard enabled. +This is a bare minimum configuration for Platformatic DB. Uses a local `./db.sqlite` SQLite database, with OpenAPI and GraphQL support. Server will listen to `http://127.0.0.1:3042` @@ -629,8 +617,7 @@ Server will listen to `http://127.0.0.1:3042` "graphiql": true, "openapi": true, "graphql": true - }, - "dashboard": true + } } ``` diff --git a/versioned_docs/version-0.35.4/reference/db/introduction.md b/versioned_docs/version-0.41.1/reference/db/introduction.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/db/introduction.md rename to versioned_docs/version-0.41.1/reference/db/introduction.md diff --git a/versioned_docs/version-0.35.4/reference/db/logging.md b/versioned_docs/version-0.41.1/reference/db/logging.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/db/logging.md rename to versioned_docs/version-0.41.1/reference/db/logging.md diff --git a/versioned_docs/version-0.35.4/reference/db/migrations.md b/versioned_docs/version-0.41.1/reference/db/migrations.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/db/migrations.md rename to versioned_docs/version-0.41.1/reference/db/migrations.md diff --git a/versioned_docs/version-0.35.4/reference/db/plugin.md b/versioned_docs/version-0.41.1/reference/db/plugin.md similarity index 96% rename from versioned_docs/version-0.35.4/reference/db/plugin.md rename to versioned_docs/version-0.41.1/reference/db/plugin.md index 6eec0ad615..3006f5114e 100644 --- a/versioned_docs/version-0.35.4/reference/db/plugin.md +++ b/versioned_docs/version-0.41.1/reference/db/plugin.md @@ -113,4 +113,5 @@ export default async function (fastify: FastifyInstance, opts: FastifyPluginOpti } ``` -Note that you need to add the `"typescript": true` configuration to your `platformatic.service.json`. +Note that you need to add the `"plugins": { "typescript": true }` configuration to your `platformatic.service.json`. + diff --git a/versioned_docs/version-0.35.4/reference/db/programmatic.md b/versioned_docs/version-0.41.1/reference/db/programmatic.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/db/programmatic.md rename to versioned_docs/version-0.41.1/reference/db/programmatic.md diff --git a/versioned_docs/version-0.35.4/reference/db/schema-support.md b/versioned_docs/version-0.41.1/reference/db/schema-support.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/db/schema-support.md rename to versioned_docs/version-0.41.1/reference/db/schema-support.md diff --git a/versioned_docs/version-0.35.4/reference/runtime/configuration.md b/versioned_docs/version-0.41.1/reference/runtime/configuration.md similarity index 94% rename from versioned_docs/version-0.35.4/reference/runtime/configuration.md rename to versioned_docs/version-0.41.1/reference/runtime/configuration.md index 7a19538ff9..9ab099991a 100644 --- a/versioned_docs/version-0.35.4/reference/runtime/configuration.md +++ b/versioned_docs/version-0.41.1/reference/runtime/configuration.md @@ -121,8 +121,10 @@ microservices are started in the order specified in the configuration file. - **`serviceName`** (**required**, `string`) — Name of the service as will be reported in open telemetry. In the `runtime` case, the name of the services as reported in traces is `${serviceName}-${serviceId}`, where `serviceId` is the id of the service in the runtime. - **`version`** (`string`) — Optional version (free form) -- **`exporter`** (`object`) — Exporter configuration object. If not defined, the exporter defaults to `console`. This object has the following properties: -- **`skip`** (`array`). Optional list of operations to skip when exporting telemetry in the form of `${method}/${path}`. e.g.: `GET/documentation/json` +- **`skip`** (`array`). Optional list of operations to skip when exporting telemetry defined `object` with properties: + - `method`: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE + - `path`. e.g.: `/documentation/json` +- **`exporter`** (`object` or `array`) — Exporter configuration. If not defined, the exporter defaults to `console`. If an array of objects is configured, every object must be a valid exporter object. The exporter object has the following properties: - **`type`** (`string`) — Exporter type. Supported values are `console`, `otlp`, `zipkin` and `memory` (default: `console`). `memory` is only supported for testing purposes. - **`options`** (`object`) — These options are supported: - **`url`** (`string`) — The URL to send the telemetry to. Required for `otlp` exporter. This has no effect on `console` and `memory` exporters. diff --git a/versioned_docs/version-0.35.4/reference/runtime/introduction.md b/versioned_docs/version-0.41.1/reference/runtime/introduction.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/runtime/introduction.md rename to versioned_docs/version-0.41.1/reference/runtime/introduction.md diff --git a/versioned_docs/version-0.41.1/reference/runtime/programmatic.md b/versioned_docs/version-0.41.1/reference/runtime/programmatic.md new file mode 100644 index 0000000000..27ef29c8fc --- /dev/null +++ b/versioned_docs/version-0.41.1/reference/runtime/programmatic.md @@ -0,0 +1,98 @@ +# Programmatic API + +In many cases it's useful to start Platformatic applications using an API +instead of the command line. The `@platformatic/runtime` API makes it simple to +work with different application types (e.g. `service`, `db`, `composer` and `runtime`) without +needing to know the application type a priori. + +## `buildServer()` + +The `buildServer` function creates a server from a provided configuration +object or configuration filename. +The config can be of either Platformatic Service, Platformatic DB, +Platformatic Composer or any other application built on top of +[Platformatic Service](/reference/service/programmatic.md). + +```js +import { buildServer } from '@platformatic/runtime' + +const app = await buildServer('path/to/platformatic.runtime.json') +const entrypointUrl = await app.start() + +// Make a request to the entrypoint. +const res = await fetch(entrypointUrl) +console.log(await res.json()) + +// Do other interesting things. + +await app.close() +``` + +It is also possible to customize the configuration: + + +```js +import { buildServer } from '@platformatic/runtime' + +const config = { + // $schema: 'https://platformatic.dev/schemas/v0.39.0/runtime', + // $schema: 'https://platformatic.dev/schemas/v0.39.0/service', + // $schema: 'https://platformatic.dev/schemas/v0.39.0/db', + // $schema: 'https://platformatic.dev/schemas/v0.39.0/composer' + ... +} +const app = await buildServer(config) + +await app.start() +``` + + +## `loadConfig()` + +The `loadConfig` function is used to read and parse a configuration file for +an arbitrary Platformatic application. + +```js +import { loadConfig } from '@platformatic/runtime' + +// Read the config based on command line arguments. loadConfig() will detect +// the application type. +const config = await loadConfig({}, ['-c', '/path/to/platformatic.config.json']) + +// Read the config based on command line arguments. The application type can +// be provided explicitly. +const config = await loadConfig( + {}, + ['-c', '/path/to/platformatic.config.json'] +) + +// Default config can be specified. +const config = await loadConfig( + {}, + ['-c', '/path/to/platformatic.config.json'], + { key: 'value' } +) +``` + +## `start()` + +The `start` function loads a configuration, builds a server, and starts the +server. However, the server is not returned. + +```js +import { start } from '@platformatic/runtime' + +await start(['-c', '/path/to/platformatic.config.json]) +``` + +## `startCommand()` + +The `startCommand` function is similar to `start`. However, if an exception +occurs, `startCommand` logs the error and exits the process. This is different +from `start`, which throws the exception. + +```js +import { startCommand } from '@platformatic/runtime' + +await startCommand(['-c', '/path/to/platformatic.config.json]) +``` diff --git a/versioned_docs/version-0.35.4/reference/service/configuration.md b/versioned_docs/version-0.41.1/reference/service/configuration.md similarity index 96% rename from versioned_docs/version-0.35.4/reference/service/configuration.md rename to versioned_docs/version-0.41.1/reference/service/configuration.md index 8e418e077b..6f5357f466 100644 --- a/versioned_docs/version-0.35.4/reference/service/configuration.md +++ b/versioned_docs/version-0.41.1/reference/service/configuration.md @@ -242,8 +242,10 @@ Configure `@platformatic/service` specific settings such as `graphql` or `openap - **`serviceName`** (**required**, `string`) — Name of the service as will be reported in open telemetry. - **`version`** (`string`) — Optional version (free form) -- **`exporter`** (`object`) — Exporter configuration object. If not defined, the exporter defaults to `console`. This object has the following properties: -- **`skip`** (`array`). Optional list of operations to skip when exporting telemetry in the form of `${method}/${path}`. e.g.: `GET/documentation/json` +- **`skip`** (`array`). Optional list of operations to skip when exporting telemetry defined `object` with properties: + - `method`: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE + - `path`. e.g.: `/documentation/json` +- **`exporter`** (`object` or `array`) — Exporter configuration. If not defined, the exporter defaults to `console`. If an array of objects is configured, every object must be a valid exporter object. The exporter object has the following properties: - **`type`** (`string`) — Exporter type. Supported values are `console`, `otlp`, `zipkin` and `memory` (default: `console`). `memory` is only supported for testing purposes. - **`options`** (`object`) — These options are supported: - **`url`** (`string`) — The URL to send the telemetry to. Required for `otlp` exporter. This has no effect on `console` and `memory` exporters. diff --git a/versioned_docs/version-0.35.4/reference/service/introduction.md b/versioned_docs/version-0.41.1/reference/service/introduction.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/service/introduction.md rename to versioned_docs/version-0.41.1/reference/service/introduction.md diff --git a/versioned_docs/version-0.35.4/reference/service/plugin.md b/versioned_docs/version-0.41.1/reference/service/plugin.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/service/plugin.md rename to versioned_docs/version-0.41.1/reference/service/plugin.md diff --git a/versioned_docs/version-0.35.4/reference/service/programmatic.md b/versioned_docs/version-0.41.1/reference/service/programmatic.md similarity index 58% rename from versioned_docs/version-0.35.4/reference/service/programmatic.md rename to versioned_docs/version-0.41.1/reference/service/programmatic.md index 69ee2c0700..f1e0d56df4 100644 --- a/versioned_docs/version-0.35.4/reference/service/programmatic.md +++ b/versioned_docs/version-0.41.1/reference/service/programmatic.md @@ -48,14 +48,7 @@ await app.close() If you want to build a similar kind of tool, follow this example: ```js -import { buildServer, ConfigManager, platformaticService } from '@platformatic/service' - -class MyConfigManager { - _transformConfig () { - // Edit this.current at will, it's the current configuration - console.log(this.current) - } -} +import { buildServer, schema } from '@platformatic/service' async function myPlugin (app, opts) { // app.platformatic.configManager contains an instance of the ConfigManager @@ -66,12 +59,39 @@ async function myPlugin (app, opts) { // break Fastify encapsulation myPlugin[Symbol.for('skip-override')] = true +myPlugin.configType = 'myPlugin' + +// This is the schema for this reusable application configuration file, +// customize at will but retain the base properties of the schema from +// @platformatic/service +myPlugin.schema = schema + +// The configuration of the ConfigManager +myPlugin.configManagerConfig = { + schema: foo.schema, + envWhitelist: ['PORT', 'HOSTNAME'], + allowToWatch: ['.env'], + schemaOptions: { + useDefaults: true, + coerceTypes: true, + allErrors: true, + strict: false + }, + async transformConfig () { + console.log(this.current) // this is the current config + + // In this method you can alter the configuration before the application + // is started. It's useful to apply some defaults that cannot be derived + // inside the schema, such as resolving paths. + } +} + -const service = await buildServer('path/to/config.json', myPlugin, MyConfigManager) +const server = await buildServer('path/to/config.json', myPlugin) -await service.start() +await server.start() -const res = await fetch(service.url) +const res = await fetch(server.listeningOrigin) console.log(await res.json()) // do something diff --git a/versioned_docs/version-0.35.4/reference/sql-events/fastify-plugin.md b/versioned_docs/version-0.41.1/reference/sql-events/fastify-plugin.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-events/fastify-plugin.md rename to versioned_docs/version-0.41.1/reference/sql-events/fastify-plugin.md diff --git a/versioned_docs/version-0.35.4/reference/sql-events/introduction.md b/versioned_docs/version-0.41.1/reference/sql-events/introduction.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-events/introduction.md rename to versioned_docs/version-0.41.1/reference/sql-events/introduction.md diff --git a/versioned_docs/version-0.35.4/reference/sql-graphql/examples/deleteEntity.js b/versioned_docs/version-0.41.1/reference/sql-graphql/examples/deleteEntity.js similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-graphql/examples/deleteEntity.js rename to versioned_docs/version-0.41.1/reference/sql-graphql/examples/deleteEntity.js diff --git a/versioned_docs/version-0.35.4/reference/sql-graphql/examples/insertEntity.js b/versioned_docs/version-0.41.1/reference/sql-graphql/examples/insertEntity.js similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-graphql/examples/insertEntity.js rename to versioned_docs/version-0.41.1/reference/sql-graphql/examples/insertEntity.js diff --git a/versioned_docs/version-0.35.4/reference/sql-graphql/examples/query.js b/versioned_docs/version-0.41.1/reference/sql-graphql/examples/query.js similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-graphql/examples/query.js rename to versioned_docs/version-0.41.1/reference/sql-graphql/examples/query.js diff --git a/versioned_docs/version-0.35.4/reference/sql-graphql/examples/saveEntity.js b/versioned_docs/version-0.41.1/reference/sql-graphql/examples/saveEntity.js similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-graphql/examples/saveEntity.js rename to versioned_docs/version-0.41.1/reference/sql-graphql/examples/saveEntity.js diff --git a/versioned_docs/version-0.35.4/reference/sql-graphql/ignore.md b/versioned_docs/version-0.41.1/reference/sql-graphql/ignore.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-graphql/ignore.md rename to versioned_docs/version-0.41.1/reference/sql-graphql/ignore.md diff --git a/versioned_docs/version-0.35.4/reference/sql-graphql/introduction.md b/versioned_docs/version-0.41.1/reference/sql-graphql/introduction.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-graphql/introduction.md rename to versioned_docs/version-0.41.1/reference/sql-graphql/introduction.md diff --git a/versioned_docs/version-0.35.4/reference/sql-graphql/many-to-many.md b/versioned_docs/version-0.41.1/reference/sql-graphql/many-to-many.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-graphql/many-to-many.md rename to versioned_docs/version-0.41.1/reference/sql-graphql/many-to-many.md diff --git a/versioned_docs/version-0.35.4/reference/sql-graphql/mutations.md b/versioned_docs/version-0.41.1/reference/sql-graphql/mutations.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-graphql/mutations.md rename to versioned_docs/version-0.41.1/reference/sql-graphql/mutations.md diff --git a/versioned_docs/version-0.35.4/reference/sql-graphql/queries.md b/versioned_docs/version-0.41.1/reference/sql-graphql/queries.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-graphql/queries.md rename to versioned_docs/version-0.41.1/reference/sql-graphql/queries.md diff --git a/versioned_docs/version-0.35.4/reference/sql-graphql/subscriptions.md b/versioned_docs/version-0.41.1/reference/sql-graphql/subscriptions.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-graphql/subscriptions.md rename to versioned_docs/version-0.41.1/reference/sql-graphql/subscriptions.md diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/entities/api.md b/versioned_docs/version-0.41.1/reference/sql-mapper/entities/api.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/entities/api.md rename to versioned_docs/version-0.41.1/reference/sql-mapper/entities/api.md diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/entities/example.md b/versioned_docs/version-0.41.1/reference/sql-mapper/entities/example.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/entities/example.md rename to versioned_docs/version-0.41.1/reference/sql-mapper/entities/example.md diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/entities/fields.md b/versioned_docs/version-0.41.1/reference/sql-mapper/entities/fields.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/entities/fields.md rename to versioned_docs/version-0.41.1/reference/sql-mapper/entities/fields.md diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/entities/hooks.md b/versioned_docs/version-0.41.1/reference/sql-mapper/entities/hooks.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/entities/hooks.md rename to versioned_docs/version-0.41.1/reference/sql-mapper/entities/hooks.md diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/entities/introduction.md b/versioned_docs/version-0.41.1/reference/sql-mapper/entities/introduction.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/entities/introduction.md rename to versioned_docs/version-0.41.1/reference/sql-mapper/entities/introduction.md diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/entities/relations.md b/versioned_docs/version-0.41.1/reference/sql-mapper/entities/relations.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/entities/relations.md rename to versioned_docs/version-0.41.1/reference/sql-mapper/entities/relations.md diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/entities/timestamps.md b/versioned_docs/version-0.41.1/reference/sql-mapper/entities/timestamps.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/entities/timestamps.md rename to versioned_docs/version-0.41.1/reference/sql-mapper/entities/timestamps.md diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/entities/transactions.md b/versioned_docs/version-0.41.1/reference/sql-mapper/entities/transactions.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/entities/transactions.md rename to versioned_docs/version-0.41.1/reference/sql-mapper/entities/transactions.md diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/examples/count.js b/versioned_docs/version-0.41.1/reference/sql-mapper/examples/count.js similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/examples/count.js rename to versioned_docs/version-0.41.1/reference/sql-mapper/examples/count.js diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/examples/delete.js b/versioned_docs/version-0.41.1/reference/sql-mapper/examples/delete.js similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/examples/delete.js rename to versioned_docs/version-0.41.1/reference/sql-mapper/examples/delete.js diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/examples/fastify-plugin.js b/versioned_docs/version-0.41.1/reference/sql-mapper/examples/fastify-plugin.js similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/examples/fastify-plugin.js rename to versioned_docs/version-0.41.1/reference/sql-mapper/examples/fastify-plugin.js diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/examples/fields.js b/versioned_docs/version-0.41.1/reference/sql-mapper/examples/fields.js similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/examples/fields.js rename to versioned_docs/version-0.41.1/reference/sql-mapper/examples/fields.js diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/examples/find.js b/versioned_docs/version-0.41.1/reference/sql-mapper/examples/find.js similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/examples/find.js rename to versioned_docs/version-0.41.1/reference/sql-mapper/examples/find.js diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/examples/hooks.js b/versioned_docs/version-0.41.1/reference/sql-mapper/examples/hooks.js similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/examples/hooks.js rename to versioned_docs/version-0.41.1/reference/sql-mapper/examples/hooks.js diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/examples/insert.js b/versioned_docs/version-0.41.1/reference/sql-mapper/examples/insert.js similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/examples/insert.js rename to versioned_docs/version-0.41.1/reference/sql-mapper/examples/insert.js diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/examples/relations.js b/versioned_docs/version-0.41.1/reference/sql-mapper/examples/relations.js similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/examples/relations.js rename to versioned_docs/version-0.41.1/reference/sql-mapper/examples/relations.js diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/examples/save.js b/versioned_docs/version-0.41.1/reference/sql-mapper/examples/save.js similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/examples/save.js rename to versioned_docs/version-0.41.1/reference/sql-mapper/examples/save.js diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/fastify-plugin.md b/versioned_docs/version-0.41.1/reference/sql-mapper/fastify-plugin.md similarity index 98% rename from versioned_docs/version-0.35.4/reference/sql-mapper/fastify-plugin.md rename to versioned_docs/version-0.41.1/reference/sql-mapper/fastify-plugin.md index 6717d8a108..5761ba88bf 100644 --- a/versioned_docs/version-0.35.4/reference/sql-mapper/fastify-plugin.md +++ b/versioned_docs/version-0.41.1/reference/sql-mapper/fastify-plugin.md @@ -1,4 +1,4 @@ -# Fastify Plugin +# sql-mapper Fastify Plugin The `@platformatic/sql-mapper` package exports a [Fastify](https://fastify.io) plugin that can be used out-of the box in a server application. diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/images/plt-db-hooks.svg b/versioned_docs/version-0.41.1/reference/sql-mapper/images/plt-db-hooks.svg similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-mapper/images/plt-db-hooks.svg rename to versioned_docs/version-0.41.1/reference/sql-mapper/images/plt-db-hooks.svg diff --git a/versioned_docs/version-0.35.4/reference/sql-mapper/introduction.md b/versioned_docs/version-0.41.1/reference/sql-mapper/introduction.md similarity index 61% rename from versioned_docs/version-0.35.4/reference/sql-mapper/introduction.md rename to versioned_docs/version-0.41.1/reference/sql-mapper/introduction.md index 6852535f95..9a1b48e875 100644 --- a/versioned_docs/version-0.35.4/reference/sql-mapper/introduction.md +++ b/versioned_docs/version-0.41.1/reference/sql-mapper/introduction.md @@ -1,12 +1,29 @@ -# Introduction to the Platformatic DB Mapper +# Introduction to @platformatic/sql-mapper + +`@platformatic/sql-mapper` is the underlining utility that Platformatic DB uses to create useful utilities to +manipulate your SQL database using JavaScript. + +This module is bundled with [Platformatic DB](/reference/db/introduction.md) via [a fastify plugin](./fastify-plugin.md) +The rest of this guide shows how to use this module directly. + +## Install + +``` +npm i @platformatic/sql-mapper +``` + +## API + +### `connect(opts) : Promise` + +It will inspect a database schema and return an object containing: -The Platformatic DB Mapper will inspect a database schema and return an object containing: - `db` — A database abstraction layer from [`@databases`](https://www.atdatabases.org/) - `sql` — The SQL builder from [`@databases`](https://www.atdatabases.org/) - `entities` — An object containing a key for each table found in the schema, with basic CRUD operations. See [Entity Reference](./entities/introduction.md) for details. -It exports a function that accepts an object with the following properties: +The valid options are: - `connectionString` — The Database connection string - `poolSize` - Maximum number of connections in the connection pool. Defaults to `10`. @@ -16,6 +33,22 @@ It exports a function that accepts an object with the following properties: - `autoTimestamp` — Generate timestamp automatically when inserting/updating records. - `hooks` — For each entity name (like `Page`) you can customize any of the entity API function. Your custom function will receive the original function as first parameter, and then all the other parameters passed to it. +### `createConnectionPool(opts) : Promise` + +It will inspect a database schema and return an object containing: + + +- `db` — A database abstraction layer from [`@databases`](https://www.atdatabases.org/) +- `sql` — The SQL builder from [`@databases`](https://www.atdatabases.org/) + +The valid options are: + +- `connectionString` — The Database connection string +- `poolSize` - Maximum number of connections in the connection pool. Defaults to `10`. +- `log` — A logger object (like [Pino](https://getpino.io)) + +This utility is useful if you just need to connect to the db without generating any entity. + ## Code samples ```javascript diff --git a/versioned_docs/version-0.35.4/reference/sql-openapi/api.md b/versioned_docs/version-0.41.1/reference/sql-openapi/api.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-openapi/api.md rename to versioned_docs/version-0.41.1/reference/sql-openapi/api.md diff --git a/versioned_docs/version-0.35.4/reference/sql-openapi/ignore.md b/versioned_docs/version-0.41.1/reference/sql-openapi/ignore.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-openapi/ignore.md rename to versioned_docs/version-0.41.1/reference/sql-openapi/ignore.md diff --git a/versioned_docs/version-0.35.4/reference/sql-openapi/introduction.md b/versioned_docs/version-0.41.1/reference/sql-openapi/introduction.md similarity index 100% rename from versioned_docs/version-0.35.4/reference/sql-openapi/introduction.md rename to versioned_docs/version-0.41.1/reference/sql-openapi/introduction.md diff --git a/versioned_sidebars/version-0.35.4-sidebars.json b/versioned_sidebars/version-0.41.1-sidebars.json similarity index 94% rename from versioned_sidebars/version-0.35.4-sidebars.json rename to versioned_sidebars/version-0.41.1-sidebars.json index 98a02235e0..0436695ca3 100644 --- a/versioned_sidebars/version-0.35.4-sidebars.json +++ b/versioned_sidebars/version-0.41.1-sidebars.json @@ -57,7 +57,9 @@ "guides/generate-frontend-code-to-consume-platformatic-rest-api", "guides/migrating-fastify-app-to-platformatic-service", "guides/migrating-express-app-to-platformatic-service", - "guides/telemetry" + "guides/packaging-an-application-as-a-module", + "guides/telemetry", + "guides/dockerize-platformatic-app" ] }, { @@ -111,7 +113,6 @@ "reference/db/plugin", "reference/db/logging", "reference/db/programmatic", - "reference/db/dashboard", "reference/db/schema-support" ] }, @@ -160,7 +161,8 @@ "collapsed": true, "items": [ "reference/client/introduction", - "reference/client/programmatic" + "reference/client/programmatic", + "reference/client/frontend" ] }, { @@ -231,18 +233,6 @@ "items": [ "reference/sql-events/fastify-plugin" ] - }, - { - "type": "category", - "label": "Start", - "link": { - "type": "doc", - "id": "reference/start/programmatic" - }, - "collapsed": true, - "items": [ - "reference/start/programmatic" - ] } ] } diff --git a/versions.json b/versions.json index c3e7688006..cfbb4178d6 100644 --- a/versions.json +++ b/versions.json @@ -1,7 +1,7 @@ [ + "0.41.1", "0.41.0", "0.38.1", "0.36.0", - "0.35.5", - "0.35.4" + "0.35.5" ] \ No newline at end of file