@antelopejs/interface-database-catalog 0.0.3 → 0.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +18 -15
- package/docs/index.md +18 -14
- package/package.json +22 -7
package/README.md
CHANGED
|
@@ -1,13 +1,15 @@
|
|
|
1
|
-
#
|
|
1
|
+
# `@antelopejs/interface-database-catalog`
|
|
2
2
|
|
|
3
3
|
<div align="center">
|
|
4
|
-
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/License-Apache_2.0-000000?style=for-the-badge&labelColor=000000"></a>
|
|
5
|
-
<a href="https://discord.gg/
|
|
6
|
-
<a href="https://github.com/AntelopeJS/interface-database-catalog/tree/main/docs"><img alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
|
|
4
|
+
<a href="./LICENSE"><img data-illustration alt="License" src="https://img.shields.io/badge/License-Apache_2.0-000000?style=for-the-badge&labelColor=000000"></a>
|
|
5
|
+
<a href="https://discord.gg/g4pFt6eXqu"><img data-illustration alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
|
|
6
|
+
<a href="https://github.com/AntelopeJS/interface-database-catalog/tree/main/docs"><img data-illustration alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
|
|
7
7
|
</div>
|
|
8
8
|
|
|
9
9
|
Describes and profiles a database that an [`@antelopejs/interface-database`](https://github.com/AntelopeJS/interface-database) provider is connected to but does not own, so a generator can propose a module whose tables mirror it. It is a development tool: every function refuses outside development.
|
|
10
10
|
|
|
11
|
+
Part of [AntelopeJS](https://github.com/AntelopeJS/antelopejs). Used by [AntelopeJS DMS](https://github.com/AntelopeJS/dms), the open-source back office for your PostgreSQL, MongoDB or RethinkDB database.
|
|
12
|
+
|
|
11
13
|
## What it offers
|
|
12
14
|
|
|
13
15
|
- `Info` returns the engine, version, database and role of the connection.
|
|
@@ -15,17 +17,17 @@ Describes and profiles a database that an [`@antelopejs/interface-database`](htt
|
|
|
15
17
|
- `DescribeRelations` details columns with their native types and the `@Field` declarations they accept, indexes and foreign keys.
|
|
16
18
|
- `Profile` aggregates a relation per column and per foreign key, never returning rows.
|
|
17
19
|
- `CheckReference` measures how much of one column's values another column holds, for references the database does not declare.
|
|
18
|
-
- `SampleRows` answers a few rows of a relation, each value as text, for a person to look at
|
|
20
|
+
- `SampleRows` answers a few rows of a relation, each value as text, for a person to look at. It is the one function that returns rows, and it is never meant for a generator or a model.
|
|
19
21
|
|
|
20
|
-
The answers follow the provider's own registration rules
|
|
22
|
+
The answers follow the provider's own registration rules. A relation the catalog calls mappable registers, and the key it names is the one `_id` aliases.
|
|
21
23
|
|
|
22
24
|
## Implementations
|
|
23
25
|
|
|
24
|
-
|
|
26
|
+
`@antelopejs/postgres`, `@antelopejs/mongodb` and `@antelopejs/rethinkdb` implement this interface next to `@antelopejs/interface-database`. Each lists it under `antelopeJs.implements` in its `package.json`. Another provider of `@antelopejs/interface-database` that connects to a database it does not own can implement it as well.
|
|
25
27
|
|
|
26
28
|
## Install
|
|
27
29
|
|
|
28
|
-
|
|
30
|
+
Add the package to the module that reads the catalog:
|
|
29
31
|
|
|
30
32
|
```bash
|
|
31
33
|
pnpm add @antelopejs/interface-database-catalog
|
|
@@ -52,13 +54,15 @@ Relations are named `"schema.name"`, the form `DescribeRelations` and `Profile`
|
|
|
52
54
|
|
|
53
55
|
## Compatibility
|
|
54
56
|
|
|
55
|
-
|
|
57
|
+
The interface has one AntelopeJS peer dependency:
|
|
58
|
+
|
|
59
|
+
<!-- antelopejs-docs-compat:start -->
|
|
56
60
|
|
|
57
|
-
|
|
61
|
+
| Package | Supported | Tested with |
|
|
62
|
+
| ---------------------------- | ---------------- | ----------- |
|
|
63
|
+
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` | `0.4.0` |
|
|
58
64
|
|
|
59
|
-
|
|
60
|
-
| ---------------------------- | ---------------- |
|
|
61
|
-
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
|
|
65
|
+
<!-- antelopejs-docs-compat:end -->
|
|
62
66
|
|
|
63
67
|
## Contributing
|
|
64
68
|
|
|
@@ -66,8 +70,7 @@ Read [CONTRIBUTING.md](./CONTRIBUTING.md) before you open a pull request. The lo
|
|
|
66
70
|
|
|
67
71
|
```bash
|
|
68
72
|
pnpm install
|
|
69
|
-
pnpm
|
|
70
|
-
pnpm typecheck
|
|
73
|
+
pnpm run checks
|
|
71
74
|
```
|
|
72
75
|
|
|
73
76
|
## License
|
package/docs/index.md
CHANGED
|
@@ -1,10 +1,14 @@
|
|
|
1
|
-
|
|
1
|
+
---
|
|
2
|
+
title: Inspect an existing database
|
|
3
|
+
description: Discover, describe and profile the relations of a database that an interface-database provider is connected to but does not own.
|
|
4
|
+
mode: how-to
|
|
5
|
+
---
|
|
2
6
|
|
|
3
|
-
Use `@antelopejs/interface-database-catalog` to discover relations, inspect their structure, and profile aggregate characteristics before mapping an existing database into an application. The catalog describes a provider's connection
|
|
7
|
+
Use `@antelopejs/interface-database-catalog` to discover relations, inspect their structure, and profile aggregate characteristics before mapping an existing database into an application. The catalog describes a provider's connection. It does not open a new connection or register tables. It returns no raw records, except through `SampleRows`, which answers a few rows for a person to look at.
|
|
4
8
|
|
|
5
9
|
## Before you begin
|
|
6
10
|
|
|
7
|
-
Run inside an AntelopeJS module in development, connected to a provider that implements this catalog and does not own its tables. Every catalog function refuses outside development or on an instance that owns its tables. These are safety boundaries
|
|
11
|
+
Run inside an AntelopeJS module in development, connected to a provider that implements this catalog and does not own its tables. Every catalog function refuses outside development or on an instance that owns its tables. These refusals are safety boundaries. Do not work around them in production.
|
|
8
12
|
|
|
9
13
|
## Explore in increasing detail
|
|
10
14
|
|
|
@@ -16,11 +20,11 @@ Run inside an AntelopeJS module in development, connected to a provider that imp
|
|
|
16
20
|
| 4. Measure only what you need | `Profile({ relation, columns })` | Inspect aggregates and traits for selected columns. |
|
|
17
21
|
| 5. Investigate an undeclared relationship | `CheckReference({ from, to })` | Measure value containment without declaring a foreign key. |
|
|
18
22
|
|
|
19
|
-
|
|
23
|
+
Read the metadata before you request a profile. Name relations with their schema, such as `"public.orders"`. A profile without `columns` covers every column of the relation.
|
|
20
24
|
|
|
21
25
|
## Inspect one relation
|
|
22
26
|
|
|
23
|
-
This example uses the consuming module's default catalog binding. First inspect the relation list, then pass a name it returned to `inspectRelation`, such as `"public.orders"`. It reads metadata only
|
|
27
|
+
This example uses the consuming module's default catalog binding. First inspect the relation list, then pass a name it returned to `inspectRelation`, such as `"public.orders"`. It reads metadata only. A profile is a separate step, and it can cost more.
|
|
24
28
|
|
|
25
29
|
```ts docs-check
|
|
26
30
|
import {
|
|
@@ -45,13 +49,13 @@ export async function inspectRelation(relation: string) {
|
|
|
45
49
|
}
|
|
46
50
|
```
|
|
47
51
|
|
|
48
|
-
|
|
52
|
+
Before you generate table declarations, review `unmappable`, each column's `accepts` and `lossy` notes, and the write permissions. A relation without a key is not refused for that reason alone. It registers without `_id`. Reading the catalog grants no permission and adds no constraint.
|
|
49
53
|
|
|
50
54
|
## Advanced: select a named provider
|
|
51
55
|
|
|
52
56
|
A module that implements `@antelopejs/interface-database` over a database it does not own may also implement this interface. Each consumer reaches it through a connection declared on its own module entry in the project configuration, one per database. Two consumers of the same database give their connections the same id:
|
|
53
57
|
|
|
54
|
-
```ts
|
|
58
|
+
```ts fragment
|
|
55
59
|
"dms-builder": {
|
|
56
60
|
importOverrides: [
|
|
57
61
|
{ interface: "@antelopejs/interface-database-catalog", source: "postgres-erp", id: "erp" },
|
|
@@ -64,7 +68,7 @@ A module that implements `@antelopejs/interface-database` over a database it doe
|
|
|
64
68
|
},
|
|
65
69
|
```
|
|
66
70
|
|
|
67
|
-
`GetInterfaceInstances(interfaceID)` lists connections visible to the calling module. `GetInterfaceInstance(interfaceID, connectionID)` returns connection metadata, including
|
|
71
|
+
`GetInterfaceInstances(interfaceID)` lists connections visible to the calling module. `GetInterfaceInstance(interfaceID, connectionID)` returns the connection's metadata, including the `path` to load, or `undefined`. It does not return the catalog exports. Look the connection up by package name, then `require` its `path`:
|
|
68
72
|
|
|
69
73
|
```ts docs-check
|
|
70
74
|
import { GetInterfaceInstance } from "@antelopejs/interface-core";
|
|
@@ -83,7 +87,7 @@ export async function inspectErp() {
|
|
|
83
87
|
}
|
|
84
88
|
```
|
|
85
89
|
|
|
86
|
-
Run this inside the consuming AntelopeJS module, with the provider loaded and the connection configured. A plain package import uses
|
|
90
|
+
Run this inside the consuming AntelopeJS module, with the provider loaded and the connection configured. `require` returns an untyped value, and the annotation states its shape without checking it. It holds because `connection.path` resolves to this interface package, bound to the connection's provider. A plain package import uses the module's default binding, and loading `connection.path` selects the named binding. These calls do not open database connections.
|
|
87
91
|
|
|
88
92
|
## Functions
|
|
89
93
|
|
|
@@ -112,26 +116,26 @@ Values appear only as enum labels and as **categories**: the most frequent value
|
|
|
112
116
|
|
|
113
117
|
### Interpret incomplete measurements
|
|
114
118
|
|
|
115
|
-
Every measure has its own time bound.
|
|
119
|
+
Every measure has its own time bound. Check its status before you read a value. A failed measure leaves the rest of the profile standing.
|
|
116
120
|
|
|
117
121
|
| Status | Available data | Interpretation |
|
|
118
122
|
| ----------- | -------------- | ----------------------------------------------------------------------------------- |
|
|
119
123
|
| `"ok"` | `value` | The measure completed. Check sampling and exactness before treating it as a census. |
|
|
120
|
-
| `"timeout"` | No value | The time bound expired
|
|
124
|
+
| `"timeout"` | No value | The time bound expired. This is not a zero count. |
|
|
121
125
|
| `"error"` | `code` | The database refused the measure; only its error code is exposed. |
|
|
122
126
|
|
|
123
|
-
A large relation is sampled, and `sample` reports the percentage and row count. A distinct count from a sample is a lower bound. Row counts also carry an `exact` flag. `CheckReference` reports containment and whether the target is a key
|
|
127
|
+
A large relation is sampled, and `sample` reports the percentage and the row count. A distinct count from a sample is a lower bound. Row counts also carry an `exact` flag. `CheckReference` answers a `Measure` too. Its value reports containment and whether the target is a key. It does not prove that the database enforces a foreign key.
|
|
124
128
|
|
|
125
129
|
## What a sample answers
|
|
126
130
|
|
|
127
|
-
`SampleRows` is the one function that answers row values. It is meant for a person
|
|
131
|
+
`SampleRows` is the one function that answers row values. It is meant for a person who decides what a relation's columns hold, never for a generator or a model:
|
|
128
132
|
|
|
129
133
|
- at most `SAMPLE_ROWS_LIMIT` (20) rows;
|
|
130
134
|
- every value as text, cut at `SAMPLE_TEXT_LENGTH` (200) characters, and `truncated` when it was;
|
|
131
135
|
- a binary value as its length only;
|
|
132
136
|
- a large relation is sampled as a profile is, and `sample` says so.
|
|
133
137
|
|
|
134
|
-
|
|
138
|
+
The interface does not fix how the provider reads the rows. `@antelopejs/postgres` reads them in one read-only transaction under the time bound of a measure, and throws when the read does not finish.
|
|
135
139
|
|
|
136
140
|
## Refusals
|
|
137
141
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-database-catalog",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.4",
|
|
4
4
|
"description": "AntelopeJS interface for describing and profiling a connected database",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
@@ -32,22 +32,32 @@
|
|
|
32
32
|
"provenance": true
|
|
33
33
|
},
|
|
34
34
|
"scripts": {
|
|
35
|
-
"build": "rimraf dist && tsc",
|
|
35
|
+
"build": "rimraf dist && tsc --skipLibCheck",
|
|
36
36
|
"typecheck": "tsc --noEmit",
|
|
37
|
+
"test": "pnpm run build",
|
|
37
38
|
"format": "oxfmt .",
|
|
38
39
|
"lint:fix": "oxlint --fix",
|
|
39
40
|
"lint": "oxlint",
|
|
40
41
|
"prepack": "pnpm run build",
|
|
41
|
-
"release": "pnpm run lint && pnpm run prepack && release-it",
|
|
42
|
+
"release": "pnpm run lint && pnpm run typecheck && pnpm run prepack && release-it",
|
|
42
43
|
"format:check": "oxfmt --check .",
|
|
43
|
-
"knip": "knip"
|
|
44
|
+
"knip": "knip",
|
|
45
|
+
"prepare": "if [ -e .git ] && command -v git >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1 && GIT_DIR=.git GIT_WORK_TREE=. git rev-parse --git-dir >/dev/null 2>&1; then GIT_DIR=.git GIT_WORK_TREE=. lefthook install; fi",
|
|
46
|
+
"checks": "antelopejs-checks",
|
|
47
|
+
"size": "antelopejs-check-size",
|
|
48
|
+
"sync": "antelopejs-sync",
|
|
49
|
+
"sync:check": "antelopejs-sync --check",
|
|
50
|
+
"suppressions": "antelopejs-suppressions",
|
|
51
|
+
"suppressions:update": "antelopejs-suppressions --update"
|
|
44
52
|
},
|
|
45
53
|
"devDependencies": {
|
|
54
|
+
"@antelopejs/core": "^1.21.0",
|
|
46
55
|
"@antelopejs/interface-core": ">=0.2.4 <1.0.0",
|
|
47
|
-
"@antelopejs/tooling-configs": "^0.
|
|
56
|
+
"@antelopejs/tooling-configs": "^0.5.1",
|
|
48
57
|
"@types/node": "^22.19.15",
|
|
49
58
|
"knip": "^6.34.0",
|
|
50
|
-
"
|
|
59
|
+
"lefthook": "^2.2.2",
|
|
60
|
+
"oxfmt": "^0.77.0",
|
|
51
61
|
"oxlint": "1.81.0",
|
|
52
62
|
"oxlint-tsgolint": "^7.0.2001",
|
|
53
63
|
"release-it": "^19.2.4",
|
|
@@ -58,5 +68,10 @@
|
|
|
58
68
|
"peerDependencies": {
|
|
59
69
|
"@antelopejs/interface-core": ">=0.2.4 <1.0.0"
|
|
60
70
|
},
|
|
61
|
-
"packageManager": "pnpm@10.6.5"
|
|
71
|
+
"packageManager": "pnpm@10.6.5",
|
|
72
|
+
"antelopeJs": {
|
|
73
|
+
"docs": {
|
|
74
|
+
"standard": true
|
|
75
|
+
}
|
|
76
|
+
}
|
|
62
77
|
}
|