fdl-cli 0.22.0__tar.gz → 0.23.0__tar.gz
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.
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/CHANGELOG.md +35 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/PKG-INFO +8 -3
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/README.md +7 -2
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/concepts/versions-and-refs.md +14 -3
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/concepts/working-catalogs.md +6 -5
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/getting-started.md +5 -3
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/index.md +4 -3
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/internals/from-write-to-read.md +1 -1
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/internals/inside-a-repository.md +2 -2
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/concepts/versions-and-refs.md +14 -3
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/concepts/working-catalogs.md +6 -5
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/getting-started.md +5 -3
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/index.md +4 -3
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/internals/from-write-to-read.md +1 -1
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/internals/inside-a-repository.md +2 -2
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/reference/cli.md +88 -12
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/reference/python.md +24 -1
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/spec/data-files.md +2 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/spec/refs.md +2 -2
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/spec/versions.md +5 -2
- fdl_cli-0.23.0/docs/ja/spec/writing.md +115 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/reference/cli.md +87 -11
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/reference/python.md +24 -1
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/spec/data-files.md +2 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/spec/refs.md +2 -2
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/spec/versions.md +5 -2
- fdl_cli-0.23.0/docs/spec/writing.md +115 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/pyproject.toml +1 -1
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/src/fdl/catalog.py +163 -1
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/src/fdl/cli.py +403 -34
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/src/fdl/diff.py +5 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/src/fdl/layout.py +42 -0
- fdl_cli-0.23.0/src/fdl/merge.py +476 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/src/fdl/refs.py +5 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/src/fdl/repo.py +204 -30
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/src/fdl/store.py +5 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/src/fdl/stores.py +44 -13
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/src/fdl/version.py +6 -8
- fdl_cli-0.23.0/tests/test_cli.py +460 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/tests/test_http.py +67 -8
- fdl_cli-0.23.0/tests/test_merge.py +336 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/tests/test_objects.py +15 -9
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/tests/test_profiles.py +12 -8
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/tests/test_repo.py +34 -0
- fdl_cli-0.22.0/docs/ja/spec/writing.md +0 -58
- fdl_cli-0.22.0/docs/spec/writing.md +0 -58
- fdl_cli-0.22.0/tests/test_cli.py +0 -259
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/.github/workflows/docs.yml +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/.github/workflows/publish.yml +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/.github/workflows/release.yml +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/.github/workflows/test.yml +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/.gitignore +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/.node-version +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/.python-version +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/CLAUDE.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/CONTRIBUTING.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/LICENSE +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/SECURITY.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/blume.config.ts +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/concepts/meta.ts +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/concepts/repositories.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/guides/building-a-host.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/guides/meta.ts +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/guides/mirrors.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/guides/public-and-private.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/guides/reading-without-duckdb.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/guides/serving-over-http.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/guides/stores.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/internals/ducklake-formats.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/internals/meta.ts +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/concepts/meta.ts +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/concepts/repositories.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/guides/building-a-host.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/guides/meta.ts +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/guides/mirrors.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/guides/public-and-private.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/guides/reading-without-duckdb.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/guides/serving-over-http.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/guides/stores.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/internals/ducklake-formats.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/internals/meta.ts +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/reference/meta.ts +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/spec/http.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/spec/index.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/spec/layout.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/spec/meta.ts +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/spec/reading.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/ja/stability.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/reference/meta.ts +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/spec/http.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/spec/index.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/spec/layout.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/spec/meta.ts +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/spec/reading.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/docs/stability.md +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/package-lock.json +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/package.json +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/public/CNAME +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/src/fdl/__init__.py +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/src/fdl/dataset.py +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/src/fdl/lineage.py +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/src/fdl/objects.py +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/src/fdl/profiles.py +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/src/fdl/py.typed +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/tests/http_repo.py +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/tests/test_dataset.py +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/tests/test_stores.py +0 -0
- {fdl_cli-0.22.0 → fdl_cli-0.23.0}/uv.lock +0 -0
|
@@ -1,6 +1,41 @@
|
|
|
1
1
|
# CHANGELOG
|
|
2
2
|
|
|
3
3
|
|
|
4
|
+
## v0.23.0 (2026-11-11)
|
|
5
|
+
|
|
6
|
+
### Bug Fixes
|
|
7
|
+
|
|
8
|
+
- Re-ask the credential helper on 401, check IDs and paths, and specify merging
|
|
9
|
+
([#50](https://github.com/queria-io/fdl/pull/50),
|
|
10
|
+
[`74b2d9b`](https://github.com/queria-io/fdl/commit/74b2d9b88dcf77f7ff6eb1c184919ccf62f51d88))
|
|
11
|
+
|
|
12
|
+
- Restore, pending commits, status and gc after review
|
|
13
|
+
([#49](https://github.com/queria-io/fdl/pull/49),
|
|
14
|
+
[`73799be`](https://github.com/queria-io/fdl/commit/73799bedd7baedbd67054910b161e46cf5ea3883))
|
|
15
|
+
|
|
16
|
+
### Features
|
|
17
|
+
|
|
18
|
+
- Fdl merge and fdl branch ([#51](https://github.com/queria-io/fdl/pull/51),
|
|
19
|
+
[`5e88708`](https://github.com/queria-io/fdl/commit/5e88708ade5ac84131a2a69dc285886c25af2fc6))
|
|
20
|
+
|
|
21
|
+
* feat: fdl merge and fdl branch
|
|
22
|
+
|
|
23
|
+
fdl merge merges another branch into the working catalog's branch, as the spec's Merging section
|
|
24
|
+
describes: a table only one side changed comes over, rows of a table both changed are merged by
|
|
25
|
+
the primary key both declare, and anything both changed differently is a conflict that makes no
|
|
26
|
+
version. A merge whose base is ours checks out theirs, and push then moves the branch there. fdl
|
|
27
|
+
branch lists, starts and deletes branches.
|
|
28
|
+
|
|
29
|
+
A push is now accepted when the version descends from what the branch holds, through every parent,
|
|
30
|
+
and is_ancestor no longer stops at seq, which a merge does not raise past the version it merged.
|
|
31
|
+
|
|
32
|
+
* fix: merge review findings: revert by first parent, temp names, table aliases, warnings
|
|
33
|
+
|
|
34
|
+
- Fdl revert, fdl push separate from fdl commit, and fdl gc
|
|
35
|
+
([#48](https://github.com/queria-io/fdl/pull/48),
|
|
36
|
+
[`6e3ade9`](https://github.com/queria-io/fdl/commit/6e3ade956131cc9a5cd70fe1da6ebffb0aaa3bb7))
|
|
37
|
+
|
|
38
|
+
|
|
4
39
|
## v0.22.0 (2026-11-10)
|
|
5
40
|
|
|
6
41
|
### Features
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: fdl-cli
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.23.0
|
|
4
4
|
Summary: Versions of a DuckLake catalog on object storage, kept the way Git keeps commits
|
|
5
5
|
Project-URL: Homepage, https://fdl.queria.io/
|
|
6
6
|
Project-URL: Documentation, https://fdl.queria.io/
|
|
@@ -77,6 +77,7 @@ Then make a version and move `main` to it:
|
|
|
77
77
|
|
|
78
78
|
```bash
|
|
79
79
|
fdl commit work/lake.sqlite -m "First towns" --author alice
|
|
80
|
+
fdl push work/lake.sqlite
|
|
80
81
|
fdl log s3://my-bucket/towns/
|
|
81
82
|
```
|
|
82
83
|
|
|
@@ -100,18 +101,22 @@ Credentials and the endpoint come from boto3's usual places (`AWS_*` environment
|
|
|
100
101
|
| --- | --- |
|
|
101
102
|
| `fdl init <remote>` | Start a repository (`fdl.json` and `HEAD`) |
|
|
102
103
|
| `fdl checkout <remote> <working>` | Make a working catalog from the version `main` holds |
|
|
103
|
-
| `fdl commit <working> -m … --author …` | Freeze the working catalog into a version
|
|
104
|
+
| `fdl commit <working> -m … --author …` | Freeze the working catalog into a version |
|
|
105
|
+
| `fdl push <working>` | Upload the committed version and move `main` to it |
|
|
104
106
|
| `fdl log <remote>` | List versions from `main` back to the first |
|
|
105
107
|
| `fdl status <working>` | What the working catalog changed since the checkout |
|
|
106
108
|
| `fdl diff <remote> [version]` | What a version changed since its parent: tables, rows, columns, data files, descriptions |
|
|
107
109
|
| `fdl show <remote> [version]` | A version's record, its tables and its changes |
|
|
108
110
|
| `fdl url <remote> [--attach]` | Print the catalog URL of the version `main` holds, or the whole `ATTACH` statement |
|
|
109
111
|
| `fdl tag <remote> [name] [version]` | List tags, tag a version, or delete a tag (`-d`) |
|
|
112
|
+
| `fdl branch <remote> [name] [version]` | List branches, start a branch at a version, or delete a branch (`-d`) |
|
|
113
|
+
| `fdl merge <ref> <working> --author …` | Merge another branch into the working catalog's branch, rows matched by primary key |
|
|
110
114
|
| `fdl expire <remote> --keep N` | Mark older versions as past retention and delete their catalogs |
|
|
115
|
+
| `fdl gc <remote> --yes` | Delete data files no live version reaches, after the grace period |
|
|
111
116
|
| `fdl withdraw <remote> <version>…` | Remove versions that hold data that must not be published |
|
|
112
117
|
| `fdl assets <folder>` | List files for an asset column (path, sha256, bytes, media type) |
|
|
113
118
|
|
|
114
|
-
A push that is not built on what `main` holds now is refused: check out again and redo the work.
|
|
119
|
+
A push that is not built on what `main` holds now is refused: check out again and redo the work, or work on a branch and merge it.
|
|
115
120
|
|
|
116
121
|
## Python
|
|
117
122
|
|
|
@@ -57,6 +57,7 @@ Then make a version and move `main` to it:
|
|
|
57
57
|
|
|
58
58
|
```bash
|
|
59
59
|
fdl commit work/lake.sqlite -m "First towns" --author alice
|
|
60
|
+
fdl push work/lake.sqlite
|
|
60
61
|
fdl log s3://my-bucket/towns/
|
|
61
62
|
```
|
|
62
63
|
|
|
@@ -80,18 +81,22 @@ Credentials and the endpoint come from boto3's usual places (`AWS_*` environment
|
|
|
80
81
|
| --- | --- |
|
|
81
82
|
| `fdl init <remote>` | Start a repository (`fdl.json` and `HEAD`) |
|
|
82
83
|
| `fdl checkout <remote> <working>` | Make a working catalog from the version `main` holds |
|
|
83
|
-
| `fdl commit <working> -m … --author …` | Freeze the working catalog into a version
|
|
84
|
+
| `fdl commit <working> -m … --author …` | Freeze the working catalog into a version |
|
|
85
|
+
| `fdl push <working>` | Upload the committed version and move `main` to it |
|
|
84
86
|
| `fdl log <remote>` | List versions from `main` back to the first |
|
|
85
87
|
| `fdl status <working>` | What the working catalog changed since the checkout |
|
|
86
88
|
| `fdl diff <remote> [version]` | What a version changed since its parent: tables, rows, columns, data files, descriptions |
|
|
87
89
|
| `fdl show <remote> [version]` | A version's record, its tables and its changes |
|
|
88
90
|
| `fdl url <remote> [--attach]` | Print the catalog URL of the version `main` holds, or the whole `ATTACH` statement |
|
|
89
91
|
| `fdl tag <remote> [name] [version]` | List tags, tag a version, or delete a tag (`-d`) |
|
|
92
|
+
| `fdl branch <remote> [name] [version]` | List branches, start a branch at a version, or delete a branch (`-d`) |
|
|
93
|
+
| `fdl merge <ref> <working> --author …` | Merge another branch into the working catalog's branch, rows matched by primary key |
|
|
90
94
|
| `fdl expire <remote> --keep N` | Mark older versions as past retention and delete their catalogs |
|
|
95
|
+
| `fdl gc <remote> --yes` | Delete data files no live version reaches, after the grace period |
|
|
91
96
|
| `fdl withdraw <remote> <version>…` | Remove versions that hold data that must not be published |
|
|
92
97
|
| `fdl assets <folder>` | List files for an asset column (path, sha256, bytes, media type) |
|
|
93
98
|
|
|
94
|
-
A push that is not built on what `main` holds now is refused: check out again and redo the work.
|
|
99
|
+
A push that is not built on what `main` holds now is refused: check out again and redo the work, or work on a branch and merge it.
|
|
95
100
|
|
|
96
101
|
## Python
|
|
97
102
|
|
|
@@ -56,7 +56,7 @@ Refs are the only files in a repository that change. Everything else is written
|
|
|
56
56
|
|
|
57
57
|
## Moving a branch
|
|
58
58
|
|
|
59
|
-
A branch moves forward only. A new version can become `main` when
|
|
59
|
+
A branch moves forward only. A new version can become `main` when it descends from the version `main` holds now: that version is reached by following `parents`. This is a fast-forward in Git's terms.
|
|
60
60
|
|
|
61
61
|
```
|
|
62
62
|
main → A
|
|
@@ -64,9 +64,20 @@ main → A
|
|
|
64
64
|
Bob checked out A too, commits C (parent A), pushes: refused
|
|
65
65
|
```
|
|
66
66
|
|
|
67
|
-
Bob's push is refused because C is not built on B. If it were accepted, B would vanish from the history of `main` with no one deciding that. Bob checks out B and makes his change again.
|
|
67
|
+
Bob's push is refused because C is not built on B. If it were accepted, B would vanish from the history of `main` with no one deciding that. Bob checks out B and makes his change again. Redoing the change on the new version is usually a matter of running the same SQL again.
|
|
68
68
|
|
|
69
|
-
|
|
69
|
+
## Merging
|
|
70
|
+
|
|
71
|
+
Work that takes longer goes on a branch of its own, and is merged into `main` when it is ready:
|
|
72
|
+
|
|
73
|
+
```
|
|
74
|
+
main → A → B
|
|
75
|
+
\
|
|
76
|
+
feature C
|
|
77
|
+
fdl merge refs/heads/feature on main makes M (parents B, C): main → M
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
The merge compares each table in three versions: B, C and their common ancestor A. A table only one branch changed comes over as that branch holds it. When both changed the same table, the rows are matched by the `primary_key` both declare in `dataset.json`, and a row only one branch changed comes over. A row both changed differently, or a table without a primary key that both changed, is a conflict, and then no version is made. A row number added for the merge is not a primary key: it does not say which rows are the same row. See [Merging](/spec/writing#merging).
|
|
70
81
|
|
|
71
82
|
Moving a branch back, to undo a version, is allowed only when asked for explicitly. The version that was undone stays in the repository and in the history.
|
|
72
83
|
|
|
@@ -11,7 +11,8 @@ A working catalog is a DuckLake catalog in a SQLite file, on the writer's own di
|
|
|
11
11
|
| --- | --- | --- |
|
|
12
12
|
| check out | `fdl checkout` | Copy the catalog of the branch's version into SQLite, and remember that version |
|
|
13
13
|
| write | any DuckDB client | DuckLake writes Parquet into the repository and bookkeeping into SQLite |
|
|
14
|
-
| commit | `fdl commit` | Freeze the last snapshot into a new version,
|
|
14
|
+
| commit | `fdl commit` | Freeze the last snapshot into a new version, kept beside the working catalog |
|
|
15
|
+
| push | `fdl push` | Upload the version and move the branch to it |
|
|
15
16
|
|
|
16
17
|
Checking out copies DuckLake's bookkeeping tables from the frozen DuckDB file into SQLite as they are. Freezing does the reverse. Neither rewrites a Parquet file, so both are fast even for a large dataset: the catalog is small and the data stays where it is.
|
|
17
18
|
|
|
@@ -19,7 +20,7 @@ Checking out copies DuckLake's bookkeeping tables from the frozen DuckDB file in
|
|
|
19
20
|
|
|
20
21
|
A working catalog has to be written by DuckDB and kept between sessions. SQLite does both without a database server, works the same on a laptop and in a container, and copies in and out of DuckDB's format without loss.
|
|
21
22
|
|
|
22
|
-
There is one kind of working catalog. A host that writes on behalf of its users (a scheduled import, a web form) checks out, writes and
|
|
23
|
+
There is one kind of working catalog. A host that writes on behalf of its users (a scheduled import, a web form) checks out, writes, commits and pushes the same way a person does on a laptop. When two of them push at once, the conditional write on the ref settles it: one wins, and the other checks out again.
|
|
23
24
|
|
|
24
25
|
## Attaching
|
|
25
26
|
|
|
@@ -33,15 +34,15 @@ ATTACH 'ducklake:work/lake.sqlite' AS lake (
|
|
|
33
34
|
);
|
|
34
35
|
```
|
|
35
36
|
|
|
36
|
-
- `DATA_PATH` is the repository's data folder, so new Parquet files land where readers will look for them. For a repository over HTTP it is a folder beside the working catalog instead, and `fdl
|
|
37
|
+
- `DATA_PATH` is the repository's data folder, so new Parquet files land where readers will look for them. For a repository over HTTP it is a folder beside the working catalog instead, and `fdl push` uploads the new files (see [Pushing over HTTP](/spec/http#writing-to-it))
|
|
37
38
|
- `DATA_INLINING_ROW_LIMIT 0` keeps every row out of the catalog. A version must not carry inlined rows, and `fdl commit` refuses a working catalog that holds some
|
|
38
39
|
- `META_TYPE 'sqlite'` has to be stated. Left to guess from the file, DuckDB passes an option to SQLite that SQLite rejects
|
|
39
40
|
|
|
40
|
-
## Data files written before a
|
|
41
|
+
## Data files written before a push
|
|
41
42
|
|
|
42
43
|
DuckLake writes Parquet as you go, so data files reach the repository before any version names them. Readers never see them: a reader only opens catalogs of versions, and no version names those files yet.
|
|
43
44
|
|
|
44
|
-
A file that stays unnamed for longer than the grace period (7 days by default) may be deleted by maintenance.
|
|
45
|
+
A file that stays unnamed for longer than the grace period (7 days by default) may be deleted by maintenance. Push within that time. If a push is refused because a file it names is missing, rebuild the table in the working catalog, commit and push again. A version committed and never pushed names its files only on your disk, so they are deleted in the same way.
|
|
45
46
|
|
|
46
47
|
## Snapshots in the working catalog
|
|
47
48
|
|
|
@@ -76,13 +76,14 @@ Every version carries a `dataset.json` that says what it holds. Write one next t
|
|
|
76
76
|
|
|
77
77
|
Only `name` and `title` are required. `fdl commit` checks the file against the catalog and fills in each table's row count and each column's type.
|
|
78
78
|
|
|
79
|
-
## Commit
|
|
79
|
+
## Commit and push
|
|
80
80
|
|
|
81
81
|
```bash
|
|
82
82
|
fdl commit work/lake.sqlite -m "First towns" --author alice
|
|
83
|
+
fdl push work/lake.sqlite
|
|
83
84
|
```
|
|
84
85
|
|
|
85
|
-
`commit` freezes the working catalog into a version
|
|
86
|
+
`commit` freezes the working catalog into a version on your disk. `push` uploads it and moves `main` to it, and prints `refs/heads/main -> 019a3c4e-… (version 1)`. The repository now holds:
|
|
86
87
|
|
|
87
88
|
```
|
|
88
89
|
towns/
|
|
@@ -134,8 +135,9 @@ INSERT INTO lake.main.towns SELECT * FROM 'towns-2026.csv';
|
|
|
134
135
|
|
|
135
136
|
```bash
|
|
136
137
|
fdl commit work/lake.sqlite -m "Add 2026" --author alice
|
|
138
|
+
fdl push work/lake.sqlite
|
|
137
139
|
```
|
|
138
140
|
|
|
139
141
|
The new version lists the first as its parent. Both catalogs name the first Parquet file; only the second names the new one.
|
|
140
142
|
|
|
141
|
-
If someone else
|
|
143
|
+
If someone else pushed in between, the push is refused, because the new version would not be built on what `main` holds now. Check out again and redo the change. [Versions and refs](/concepts/versions-and-refs) explains why.
|
|
@@ -30,7 +30,7 @@ FDL is meant for data that is published, read by many and written by few:
|
|
|
30
30
|
- a dataset maintained by a team, where a change has to be reviewed before readers see it
|
|
31
31
|
- copies of the same dataset on several hosts (mirrors)
|
|
32
32
|
|
|
33
|
-
It is not a transactional database.
|
|
33
|
+
It is not a transactional database. Two people who push at once are settled by the store: the first push wins and the second is refused. The second builds again on the new version, or works on a branch of its own and merges it, rows matched by the table's primary key.
|
|
34
34
|
|
|
35
35
|
## FDL and Git
|
|
36
36
|
|
|
@@ -45,10 +45,11 @@ FDL keeps a catalog's versions the way Git keeps a project's commits. If you kno
|
|
|
45
45
|
| Branch, tag, `HEAD` | `refs/heads/`, `refs/tags/`, `HEAD` |
|
|
46
46
|
| Working tree | Working catalog (SQLite on your disk) |
|
|
47
47
|
| `git init --bare` | `fdl init` |
|
|
48
|
-
| `git commit
|
|
48
|
+
| `git commit`, `git push` | `fdl commit`, `fdl push` |
|
|
49
49
|
| `git log`, `git tag` | `fdl log`, `fdl tag` |
|
|
50
|
+
| `git branch`, `git merge` | `fdl branch`, `fdl merge` |
|
|
50
51
|
|
|
51
|
-
|
|
52
|
+
A version has one parent, or two when it merges another branch. [From write to read](/internals/from-write-to-read) follows the files through a commit, step by step.
|
|
52
53
|
|
|
53
54
|
FDL is in beta. [Stability](/stability) says what stays the same across releases.
|
|
54
55
|
|
|
@@ -30,7 +30,7 @@ Three things differ on purpose:
|
|
|
30
30
|
|
|
31
31
|
- A version's ID is a UUIDv7, not a hash of its content. Two DuckDB releases can write the same catalog as different bytes, so a content hash would change with the tool. The sha256 in `version.json` checks the content instead
|
|
32
32
|
- There are no packfiles. Each file is its own object in the store, so a reader fetches only the parts of a Parquet file it needs
|
|
33
|
-
-
|
|
33
|
+
- A merge matches rows by the primary key that `dataset.json` declares, not by lines or files. Two branches that changed the same table without one are a conflict (see [Merging](/spec/writing#merging))
|
|
34
34
|
|
|
35
35
|
## Writing a version
|
|
36
36
|
|
|
@@ -40,7 +40,7 @@ No ref and no version names the file, so no reader can reach it. If the writer g
|
|
|
40
40
|
|
|
41
41
|
## The first commit
|
|
42
42
|
|
|
43
|
-
`fdl commit` does
|
|
43
|
+
`fdl commit` does steps 1 to 4 on the writer's disk, and `fdl push` does the rest, in this order:
|
|
44
44
|
|
|
45
45
|
1. Copy the working catalog from SQLite into a DuckDB file, keeping the snapshots up to the last one
|
|
46
46
|
2. Set the catalog's `data_path` to the repository's data folder, and refuse if any file is recorded with an absolute path elsewhere
|
|
@@ -62,7 +62,7 @@ versions/019a2f10-…/version.json
|
|
|
62
62
|
data/main/towns/ducklake-0199f1….parquet
|
|
63
63
|
```
|
|
64
64
|
|
|
65
|
-
The order is what keeps readers safe. A reader starts from a ref, and the ref is written last. If the
|
|
65
|
+
The order is what keeps readers safe. A reader starts from a ref, and the ref is written last. If the push stops after step 6, 7 or 8, the repository holds a version folder no ref points at. Readers never see it, and it changes nothing.
|
|
66
66
|
|
|
67
67
|
`version.json` is written after the catalog and `dataset.json` for the same reason: a tool that lists `versions/` can treat a folder without `version.json` as unfinished.
|
|
68
68
|
|
|
@@ -56,7 +56,7 @@ HEAD ref: refs/heads/main
|
|
|
56
56
|
|
|
57
57
|
## ブランチを動かす
|
|
58
58
|
|
|
59
|
-
ブランチは前へだけ動きます。新しいバージョンが `main`
|
|
59
|
+
ブランチは前へだけ動きます。新しいバージョンが `main` になれるのは、いま `main` が指すバージョンの子孫であるときです。子孫とは、`parents` をたどるとそのバージョンに着くバージョンです。Git でいう fast-forward です。
|
|
60
60
|
|
|
61
61
|
```
|
|
62
62
|
main → A
|
|
@@ -64,9 +64,20 @@ main → A
|
|
|
64
64
|
Bob も A をチェックアウトしていて、C(親 A)をコミットして push: 断られる
|
|
65
65
|
```
|
|
66
66
|
|
|
67
|
-
C は B の上に積まれていないので、Bob の push は断られます。受け付けると、誰も決めていないのに B が `main` の履歴から消えてしまいます。Bob は B
|
|
67
|
+
C は B の上に積まれていないので、Bob の push は断られます。受け付けると、誰も決めていないのに B が `main` の履歴から消えてしまいます。Bob は B をチェックアウトし、変更をやり直します。新しいバージョンの上でのやり直しは、たいてい同じ SQL を実行し直すだけで済みます。
|
|
68
68
|
|
|
69
|
-
|
|
69
|
+
## マージ
|
|
70
|
+
|
|
71
|
+
時間のかかる作業は自分のブランチで進め、できあがったら `main` にマージします。
|
|
72
|
+
|
|
73
|
+
```
|
|
74
|
+
main → A → B
|
|
75
|
+
\
|
|
76
|
+
feature C
|
|
77
|
+
main で fdl merge refs/heads/feature を実行すると M(親 B、C)ができる: main → M
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
マージは、テーブルごとに B、C、両者の共通の祖先 A の 3 つのバージョンを比較します。片方のブランチだけが変えたテーブルは、そのブランチの内容を取り込みます。両方が同じテーブルを変えたときは、両方が `dataset.json` で宣言した `primary_key` で行を照合し、片方だけが変えた行を取り込みます。両方が違う形に変えた行と、主キーの無いテーブルを両方が変えたときは衝突になり、バージョンは作りません。マージのために付けた行番号は主キーになりません。どの行が同じ行かを示さないためです。[マージ](/ja/spec/writing#マージ)を参照してください。
|
|
70
81
|
|
|
71
82
|
バージョンを取り消すためにブランチを後ろへ戻すのは、明示的に指示したときだけできます。取り消したバージョンも、リポジトリと履歴には残ります。
|
|
72
83
|
|
|
@@ -11,7 +11,8 @@ description: 書き込みをする場所です。SQLite の DuckLake カタロ
|
|
|
11
11
|
| --- | --- | --- |
|
|
12
12
|
| チェックアウト | `fdl checkout` | ブランチのバージョンのカタログを SQLite に写し、そのバージョンを覚える |
|
|
13
13
|
| 書く | DuckDB のクライアント | DuckLake が Parquet をリポジトリへ、管理用の行を SQLite へ書く |
|
|
14
|
-
| コミット | `fdl commit` |
|
|
14
|
+
| コミット | `fdl commit` | 最後のスナップショットを新しいバージョンに固め、作業カタログの隣に置く |
|
|
15
|
+
| push | `fdl push` | バージョンをアップロードし、ブランチをそこへ動かす |
|
|
15
16
|
|
|
16
17
|
チェックアウトでは、DuckLake の管理用の表を、固めた DuckDB ファイルから SQLite へそのまま写します。固めるときはその逆です。どちらも Parquet ファイルは書き換えないので、大きなデータセットでもすぐ終わります。カタログは小さく、データはその場に残ります。
|
|
17
18
|
|
|
@@ -19,7 +20,7 @@ description: 書き込みをする場所です。SQLite の DuckLake カタロ
|
|
|
19
20
|
|
|
20
21
|
作業カタログは、DuckDB から書けて、作業をまたいで残せる必要があります。SQLite はデータベースサーバーなしでその両方ができ、手元のパソコンでもコンテナでも同じように動き、DuckDB の形式との間で欠けなく写せます。
|
|
21
22
|
|
|
22
|
-
作業カタログは 1 種類です。利用者の代わりに書くホスト(定期の取り込みや Web
|
|
23
|
+
作業カタログは 1 種類です。利用者の代わりに書くホスト(定期の取り込みや Web のフォームなど)も、人がパソコンでするのと同じ手順でチェックアウトし、書き、コミットして push します。2 つが同時に push したときは、ref の条件付き書き込みで決まります。一方が通り、もう一方はチェックアウトし直します。
|
|
23
24
|
|
|
24
25
|
## ATTACH の仕方
|
|
25
26
|
|
|
@@ -33,15 +34,15 @@ ATTACH 'ducklake:work/lake.sqlite' AS lake (
|
|
|
33
34
|
);
|
|
34
35
|
```
|
|
35
36
|
|
|
36
|
-
- `DATA_PATH` はリポジトリのデータフォルダです。新しい Parquet ファイルは、読み手が探す場所に書かれます。HTTP 越しのリポジトリでは、かわりに作業カタログの隣のフォルダになり、新しいファイルは `fdl
|
|
37
|
+
- `DATA_PATH` はリポジトリのデータフォルダです。新しい Parquet ファイルは、読み手が探す場所に書かれます。HTTP 越しのリポジトリでは、かわりに作業カタログの隣のフォルダになり、新しいファイルは `fdl push` が上げます([HTTP での push](/ja/spec/http#書き方))
|
|
37
38
|
- `DATA_INLINING_ROW_LIMIT 0` で、行をカタログの中に入れないようにします。バージョンはカタログの中に行を持てないので、行を持つ作業カタログは `fdl commit` が断ります
|
|
38
39
|
- `META_TYPE 'sqlite'` は省略できません。省くと DuckDB がファイルから種類を推測し、SQLite が受け付けないオプションを渡してしまいます
|
|
39
40
|
|
|
40
|
-
##
|
|
41
|
+
## push 前に書かれたデータファイル
|
|
41
42
|
|
|
42
43
|
DuckLake は書くそばから Parquet を書くので、データファイルは、それを参照するバージョンより先にリポジトリに届きます。読み手には見えません。読み手はバージョンのカタログしか開かず、まだどのバージョンもそのファイルを参照していないからです。
|
|
43
44
|
|
|
44
|
-
どこからも参照されないまま猶予期間(既定で 7
|
|
45
|
+
どこからも参照されないまま猶予期間(既定で 7 日)を過ぎたファイルは、保守で消されることがあります。その前に push してください。参照しているファイルが無いと言われて push が断られたら、作業カタログで表を作り直し、コミットと push をやり直してください。コミットしたまま push しなかったバージョンは手元でしかファイルを参照していないので、そのファイルも同じように消されます。
|
|
45
46
|
|
|
46
47
|
## 作業カタログのスナップショット
|
|
47
48
|
|
|
@@ -76,13 +76,14 @@ SELECT * FROM 'towns.csv';
|
|
|
76
76
|
|
|
77
77
|
必須なのは `name` と `title` だけです。`fdl commit` がこのファイルをカタログと照らし合わせ、表ごとの行数と列ごとの型を書き足します。
|
|
78
78
|
|
|
79
|
-
##
|
|
79
|
+
## コミットして push する
|
|
80
80
|
|
|
81
81
|
```bash
|
|
82
82
|
fdl commit work/lake.sqlite -m "First towns" --author alice
|
|
83
|
+
fdl push work/lake.sqlite
|
|
83
84
|
```
|
|
84
85
|
|
|
85
|
-
`commit`
|
|
86
|
+
`commit` は作業カタログを固めて手元でバージョンにします。`push` はそれをアップロードして `main` をそこへ動かし、`refs/heads/main -> 019a3c4e-… (version 1)` と表示します。リポジトリは次のようになります。
|
|
86
87
|
|
|
87
88
|
```
|
|
88
89
|
towns/
|
|
@@ -134,8 +135,9 @@ INSERT INTO lake.main.towns SELECT * FROM 'towns-2026.csv';
|
|
|
134
135
|
|
|
135
136
|
```bash
|
|
136
137
|
fdl commit work/lake.sqlite -m "Add 2026" --author alice
|
|
138
|
+
fdl push work/lake.sqlite
|
|
137
139
|
```
|
|
138
140
|
|
|
139
141
|
新しいバージョンは、最初のバージョンを親として記録します。最初の Parquet ファイルは両方のカタログが参照し、新しいファイルは 2 つめのカタログだけが参照します。
|
|
140
142
|
|
|
141
|
-
|
|
143
|
+
途中でほかの人が push していたら、この push は断られます。新しいバージョンが、いまの `main` の上に積まれていないためです。チェックアウトし直して、変更をやり直してください。理由は[バージョンと ref](/ja/concepts/versions-and-refs) で説明しています。
|
|
@@ -30,7 +30,7 @@ FDL は、公開して多くの人が読み、少ない人が書くデータに
|
|
|
30
30
|
- チームで整備し、読み手に見せる前に変更を確認するデータセット
|
|
31
31
|
- 同じデータセットを複数のホストに置く写し(ミラー)
|
|
32
32
|
|
|
33
|
-
FDL
|
|
33
|
+
FDL はトランザクションのためのデータベースではありません。2 人が同時に push したときは置き場が決めます。先に push したほうが通り、後のほうは断られます。後の書き手は新しいバージョンの上に作り直すか、自分のブランチで作業してマージします。マージではテーブルの主キーで行を照合します。
|
|
34
34
|
|
|
35
35
|
## FDL と Git
|
|
36
36
|
|
|
@@ -45,10 +45,11 @@ FDL は、Git がプロジェクトのコミットを残すのと同じ形で、
|
|
|
45
45
|
| ブランチ・タグ・`HEAD` | `refs/heads/`・`refs/tags/`・`HEAD` |
|
|
46
46
|
| 作業ツリー | 作業カタログ(手元の SQLite) |
|
|
47
47
|
| `git init --bare` | `fdl init` |
|
|
48
|
-
| `git commit
|
|
48
|
+
| `git commit`、`git push` | `fdl commit`、`fdl push` |
|
|
49
49
|
| `git log`・`git tag` | `fdl log`・`fdl tag` |
|
|
50
|
+
| `git branch`・`git merge` | `fdl branch`・`fdl merge` |
|
|
50
51
|
|
|
51
|
-
|
|
52
|
+
バージョンの親は 1 つです。別のブランチをマージしたバージョンは親を 2 つ持ちます。[書いてから読まれるまで](/ja/internals/from-write-to-read)で、コミットのときにファイルがどう動くかを順に追えます。
|
|
52
53
|
|
|
53
54
|
FDL はベータです。リリースをまたいで変わらないものは[安定性](/ja/stability)に書いています。
|
|
54
55
|
|
|
@@ -30,7 +30,7 @@ FDL は Git の役割と名前をそのまま使い、保存の仕方は独自
|
|
|
30
30
|
|
|
31
31
|
- バージョンの ID は UUIDv7 で、中身のハッシュではありません。DuckDB のリリースが違うと、同じカタログでも違うバイト列で書かれることがあり、中身のハッシュは道具によって変わってしまうためです。中身の確認には `version.json` の sha256 を使います
|
|
32
32
|
- packfile はありません。ファイルはそれぞれストアの 1 つのオブジェクトなので、読み手は Parquet ファイルのうち要る部分だけを取りに行けます
|
|
33
|
-
-
|
|
33
|
+
- マージは行やファイルではなく、`dataset.json` が宣言する主キーで行を照合します。主キーの無いテーブルを 2 つのブランチが両方変えたときは衝突になります([マージ](/ja/spec/writing#マージ))
|
|
34
34
|
|
|
35
35
|
## バージョンを書く
|
|
36
36
|
|
|
@@ -40,7 +40,7 @@ data/main/towns/ducklake-0199f1….parquet
|
|
|
40
40
|
|
|
41
41
|
## 最初のコミット
|
|
42
42
|
|
|
43
|
-
`fdl commit`
|
|
43
|
+
1〜4 は `fdl commit` が書き手の手元で行い、残りは `fdl push` が行います。次の順に進みます。
|
|
44
44
|
|
|
45
45
|
1. 作業カタログを SQLite から DuckDB のファイルへ写し、最後のスナップショットまでを残す
|
|
46
46
|
2. カタログの `data_path` をリポジトリのデータフォルダにし、ほかの場所を絶対パスで指すファイルがあれば断る
|
|
@@ -62,7 +62,7 @@ versions/019a2f10-…/version.json
|
|
|
62
62
|
data/main/towns/ducklake-0199f1….parquet
|
|
63
63
|
```
|
|
64
64
|
|
|
65
|
-
読み手の安全はこの順番で守られます。読み手は ref から読み始め、ref
|
|
65
|
+
読み手の安全はこの順番で守られます。読み手は ref から読み始め、ref は最後に書かれます。push が 6、7、8 の段階で止まっても、リポジトリに残るのは、どの ref も指していないバージョンのフォルダです。読み手には見えず、何も変わりません。
|
|
66
66
|
|
|
67
67
|
`version.json` をカタログと `dataset.json` のあとに書くのも同じ理由です。`versions/` の一覧を取るツールは、`version.json` の無いフォルダを書きかけとみなせます。
|
|
68
68
|
|
|
@@ -21,6 +21,8 @@ helper = "example-cli fdl-credential"
|
|
|
21
21
|
|
|
22
22
|
fdl は `<helper> get` を実行し、標準入力に `protocol=`・`host=`・`path=` の行と空行を渡して、出力の `password=` の行を読みます。何も出さないか、エラーで終わったら、トークンは無いものとします。トークンの保存と helper の書き込みは、ホストの側の道具が行います。
|
|
23
23
|
|
|
24
|
+
helper から得たトークンにホストが 401 を返すと、fdl は helper をもう一度実行し、別のトークンが返ればそれでリクエストを送り直します。helper は期限の短いトークンを渡せます。`FDL_TOKEN` のトークンは取り直しません。
|
|
25
|
+
|
|
24
26
|
## fdl init
|
|
25
27
|
|
|
26
28
|
```bash
|
|
@@ -37,9 +39,9 @@ fdl checkout <remote> <working.sqlite> [--ref refs/heads/main] [--storage s3://b
|
|
|
37
39
|
|
|
38
40
|
ブランチが指すバージョンのカタログから作業カタログ(SQLite の DuckLake)を作ります。最初のバージョンの前は空のものを作ります。隣の `<working.sqlite>.fdl.json` に、リポジトリ、ブランチ、元のバージョンを記録します。書くときの `ATTACH` 文を表示します。
|
|
39
41
|
|
|
40
|
-
HTTP のリポジトリでは、新しいデータファイルは `<working.sqlite>.data/`
|
|
42
|
+
HTTP のリポジトリでは、新しいデータファイルは `<working.sqlite>.data/` に書かれ、push でアップロードされます。リポジトリに既にあるファイルは、その場所から HTTP で読みます。push はアップロードを終えると、新しいバージョンから作業カタログを作り直して手元の写しを削除するので、このフォルダにはまだ push していないファイルだけが残ります。
|
|
41
43
|
|
|
42
|
-
`--storage` を付けると、作業カタログはリポジトリのストレージで直接データファイルを読み書きします。`--storage` にはそのストレージでのリポジトリの根を渡します。新しいファイルはその `data_dir`
|
|
44
|
+
`--storage` を付けると、作業カタログはリポジトリのストレージで直接データファイルを読み書きします。`--storage` にはそのストレージでのリポジトリの根を渡します。新しいファイルはその `data_dir` の下に直接書かれるので、push でアップロードするものはありません。鍵は `AWS_*` の環境変数(R2 などの S3 互換ストレージは `AWS_ENDPOINT_URL`)か、自分で作った DuckDB の secret から取ります。作業カタログに書くビルドにも同じ鍵が要ります。
|
|
43
45
|
|
|
44
46
|
バージョンの保持期間が過ぎているとき、カタログの sha256 が `version.json` の記録と違うとき、カタログがデータフォルダの外のデータファイルを指しているときは断られます。
|
|
45
47
|
|
|
@@ -49,27 +51,43 @@ HTTP のリポジトリでは、新しいデータファイルは `<working.sqli
|
|
|
49
51
|
fdl commit <working.sqlite> -m "What changed" --author alice [--dataset dataset.json] [--allow-empty] [--assets files/]
|
|
50
52
|
```
|
|
51
53
|
|
|
52
|
-
|
|
54
|
+
作業カタログを、チェックアウトした(または最後に push した)バージョンを親とする新しいバージョンに固め、`fdl push` で送るまで `<working.sqlite>.pending/` に置きます。リポジトリは何も変わりません。新しいバージョン ID と `seq` を表示します。push する前にもう一度コミットすると、まだ push していないバージョンを置き換えます。
|
|
53
55
|
|
|
54
56
|
バージョンはそれぞれ `dataset.json`([バージョン](/ja/spec/versions#datasetjson)を参照)で説明します。`--dataset` で指定したファイルか、なければいまのディレクトリの `dataset.json` か `dataset.yml` から読みます。そのフォルダより下にある `*.table.yml`(または `*.table.json`)のテーブルの説明も合わせて読みます。隠しフォルダの中は読みません。コマンドはそれをカタログと照らし合わせ、列の型、行数、カタログのコメントを書き足します。
|
|
55
57
|
|
|
56
|
-
コマンドは、説明の隣の `README.md` と、そこにある `docs/` より下のファイル(隠しファイルを除く)をバージョンの tree に入れます。そのフォルダからのパスで `tree.json`
|
|
58
|
+
コマンドは、説明の隣の `README.md` と、そこにある `docs/` より下のファイル(隠しファイルを除く)をバージョンの tree に入れます。そのフォルダからのパスで `tree.json` を書き、push がリポジトリに無いものを書いたままの中身で `assets/<sha256>` にアップロードします([tree.json](/ja/spec/versions#treejson))。
|
|
57
59
|
|
|
58
60
|
あわせてテーブルごとの profile を書きます([profiles/](/ja/spec/versions#profiles))。読むのは、データファイルか列が親から変わったテーブルだけです。読めなかったテーブルには profile を書かず、警告を出してコミットを続けます。
|
|
59
61
|
|
|
60
|
-
`asset: true` の印を付けた列は、ファイルの sha256 を持ちます([アセット](/ja/spec/versions#アセット)
|
|
62
|
+
`asset: true` の印を付けた列は、ファイルの sha256 を持ちます([アセット](/ja/spec/versions#アセット))。コマンドはその列の値を読み、push がリポジトリに無いファイルを `--assets` のフォルダから `assets/<sha256>` にアップロードします。ファイルは中身で照合するので、フォルダの中のファイル名は問いません。
|
|
61
63
|
|
|
62
|
-
親と同じ中身になるとき([変更がないとき](/ja/spec/writing#変更がないとき))は `Nothing to commit`
|
|
64
|
+
親と同じ中身になるとき([変更がないとき](/ja/spec/writing#変更がないとき))は `Nothing to commit` と表示し、何も作らずに終了コード 0 で終わります。同じ行を新しいファイルに書き直しただけの作り直しも、変更なしとみなします。`--allow-empty` を付けると、それでもバージョンを作ります。行を読めず判定できないときは、警告を出してバージョンを作ります。
|
|
63
65
|
|
|
64
66
|
次のときは断られます。
|
|
65
67
|
|
|
66
68
|
- `dataset.json` が無いとき、カタログに無い表や列を説明しているとき。形式が決めていないキーは、警告を出してそのまま残します
|
|
67
|
-
- チェックアウトのあとにブランチが動いたとき。チェックアウトし直して作業をやり直す
|
|
68
69
|
- 作業カタログが行をカタログの中に持っているとき
|
|
69
|
-
-
|
|
70
|
-
- アセットの列が `varchar` でないとき、sha256 でない値を持つとき、リポジトリにも `--assets` にも無いファイルを指すとき
|
|
70
|
+
- アセットの列が `varchar` でないとき、sha256 でない値を持つとき
|
|
71
71
|
- データファイルが、データディレクトリの外を指す絶対パスで記録されているとき
|
|
72
72
|
|
|
73
|
+
## fdl push
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
fdl push <working.sqlite>
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`fdl commit` が作ったバージョンをアップロードし、条件付きでブランチをそこへ動かします([書き込みの順番](/ja/spec/writing#書き込みの順番))。ブランチ、バージョン ID、`seq` を表示します。fast-forward の `fdl merge` のあとは、何もアップロードせず、ブランチをマージしたバージョンへ動かします。コミットしたものが無いときは `Nothing to push` と表示します。
|
|
80
|
+
|
|
81
|
+
作業カタログがリポジトリに書いたデータファイルは push の前からありますが、push するまでどのバージョンも参照しません。push しなかったファイルは猶予期間のあとに削除されます。
|
|
82
|
+
|
|
83
|
+
次のときは断られます。
|
|
84
|
+
|
|
85
|
+
- チェックアウトのあとにブランチが動き、バージョンがいまブランチの指すバージョンの子孫でないとき。チェックアウトし直して作業をやり直す
|
|
86
|
+
- カタログが参照するデータファイルがリポジトリに無いとき
|
|
87
|
+
- アセットの列が、リポジトリにも `--assets` にも無いファイルを指すとき
|
|
88
|
+
|
|
89
|
+
断られても、コミットしたバージョンはそのまま残るので、原因を直してからもう一度送れます。
|
|
90
|
+
|
|
73
91
|
## fdl assets
|
|
74
92
|
|
|
75
93
|
```bash
|
|
@@ -92,7 +110,7 @@ ref が指すバージョンから最初のバージョンまで、最初の親
|
|
|
92
110
|
fdl status <working.sqlite> [--json]
|
|
93
111
|
```
|
|
94
112
|
|
|
95
|
-
作業カタログが checkout してから何を変えたかを、`fdl diff` と同じ区分で表示します。元のバージョンと同じ内容なら `Nothing to commit` と表示します。`dataset.json`
|
|
113
|
+
作業カタログが checkout してから何を変えたかを、`fdl diff` と同じ区分で表示します。元のバージョンと同じ内容なら `Nothing to commit` と表示します。`dataset.json` の文言はコミットまで比べません。コミットしてまだ push していないバージョンがあれば、先にそれを表示し、変更はそのバージョンから数えます。`--json` では `pending` にその ID を入れます。fast-forward の `fdl merge` のあとは、`fdl push` でブランチが動くことを表示します。
|
|
96
114
|
|
|
97
115
|
## fdl diff
|
|
98
116
|
|
|
@@ -140,7 +158,55 @@ fdl tag <remote> <name> [<version>] # バージョンにタグを付ける(
|
|
|
140
158
|
fdl tag <remote> <name> --delete
|
|
141
159
|
```
|
|
142
160
|
|
|
143
|
-
`<version>` にはバージョン ID か、`refs/heads/main` のような ref を渡します。タグは一度作ると動かしません。別のバージョンを指す同じ名前のタグがあるときは断られます。保持期間を過ぎたバージョンにはタグを付けられません。タグを作るか消すと `refs.json` を書き直します。`fdl
|
|
161
|
+
`<version>` にはバージョン ID か、`refs/heads/main` のような ref を渡します。タグは一度作ると動かしません。別のバージョンを指す同じ名前のタグがあるときは断られます。保持期間を過ぎたバージョンにはタグを付けられません。タグを作るか消すと `refs.json` を書き直します。`fdl push` もブランチを動かしたあとに書き直します。
|
|
162
|
+
|
|
163
|
+
## fdl branch
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
fdl branch <remote> # ブランチを並べる
|
|
167
|
+
fdl branch <remote> <name> [<version>] # バージョンからブランチを作る(既定は HEAD が指すバージョン)
|
|
168
|
+
fdl branch <remote> <name> --delete
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
`<version>` にはバージョン ID か、`refs/heads/main` のような ref を渡します。別のバージョンを指す同じ名前のブランチがあるときは断られます。同じバージョンなら何も変えません。保持期間を過ぎたバージョンからはブランチを作れません。`HEAD` が指すブランチは削除できません。ブランチは `fdl checkout --ref refs/heads/<name>` でチェックアウトします。ブランチを作るか削除すると `refs.json` を書き直します。
|
|
172
|
+
|
|
173
|
+
## fdl revert
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
fdl revert <version> <working.sqlite> --author <name> [-m <message>]
|
|
177
|
+
fdl push <working.sqlite>
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
作業カタログを `<version>` が持っていたテーブルとビューに書き戻し、`<version>` の `dataset.json` と `tree.json` で、`fdl commit` と同じく新しいバージョンをコミットします。作業カタログのコミットしていない変更は失われます。そのあと `fdl push` でブランチを前に進めます。間のバージョンは履歴に残り、読み続けられます。`<version>` から変わっていないテーブルはデータファイルをそのまま使い、変わったテーブルは `<version>` の時点の行から書き直します。`<version>` にはバージョン ID か ref を渡し、作業カタログをチェックアウトしたバージョンから最初の親をたどった履歴にあって(マージで取り込んだだけのバージョンは含みません)保持期間内のバージョンを指定します。そのバージョンがすでに `<version>` と同じものを持つときは、何も作りません。
|
|
181
|
+
|
|
182
|
+
公開してはいけないデータを除くときは `fdl withdraw` を使います。revert は間のバージョンとそのデータファイルをそのまま残します。
|
|
183
|
+
|
|
184
|
+
## fdl merge
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
fdl merge <theirs> <working.sqlite> --author <name> [-m <message>]
|
|
188
|
+
fdl push <working.sqlite>
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
別のブランチを、作業カタログをチェックアウトしたブランチにマージします([マージ](/ja/spec/writing#マージ))。`<theirs>` には `refs/heads/feature` のような ref か、バージョン ID を渡します。基点は 2 つのバージョンの共通の祖先です。
|
|
192
|
+
|
|
193
|
+
- `<theirs>` が作業カタログのバージョンの履歴にすでにあるときは `Already up to date` と表示し、何も作りません
|
|
194
|
+
- 作業カタログのバージョンが `<theirs>` の履歴にあるときは、作業カタログを `<theirs>` でチェックアウトし直し、バージョンは作りません。そのあと `fdl push` でブランチをそこへ動かします(fast-forward)
|
|
195
|
+
- それ以外は、マージの結果を作業カタログに書き、マージのバージョンをコミットします。`parents` は作業カタログのバージョンと `<theirs>` です。`fdl push` はコミットと同じくそれをアップロードします。メッセージの既定は `Merge <theirs>` です
|
|
196
|
+
|
|
197
|
+
基点から `<theirs>` だけが変えた・追加した・削除したテーブルは、`<theirs>` の内容を新しいデータファイルに書いて取り込みます。両方が変えたテーブルは、両方が `dataset.json` で宣言した `primary_key` で行をマージします。`<theirs>` だけが追加・変更・削除した行は、その変更を取り込みます。`dataset.json` と `tree.json` はキーごとにマージします。行数・型・NULL の可否は、マージしたカタログから書き直します。コマンドは、取り込んだテーブルと、`<theirs>` が追加・変更・削除した行数を表示します。`fdl commit` は説明を手元のファイルから読むので、`<theirs>` が `dataset.json` か `tree.json` を変えたときは警告を出します。次のコミットの前に、その変更を手元のファイルに反映してください。
|
|
198
|
+
|
|
199
|
+
衝突があるときは、テーブルごとに、行の衝突は主キーの値で一覧を表示し、終了コード 1 で終わり、何も変えません。衝突になるのは次のときです。
|
|
200
|
+
|
|
201
|
+
- 両方が違う形に変えたテーブルに、両方が宣言する主キーが無いとき(ビューはその SQL で、そのようなテーブルと同じく比較します)
|
|
202
|
+
- 片方が削除したテーブルを、もう片方が変えたとき
|
|
203
|
+
- 両方が変えたテーブルの列か型が両者で違うとき、または両方が列を変えたとき
|
|
204
|
+
- 両方が違う形に変えた行があるとき、または主キーに `NULL` や重複があるとき
|
|
205
|
+
- `dataset.json` か `tree.json` の同じ値を、両方が違う形に変えたとき
|
|
206
|
+
|
|
207
|
+
衝突しなくなるようにどちらかのブランチを直してから、もう一度マージします。
|
|
208
|
+
|
|
209
|
+
作業カタログにコミットしていない変更があるとき、コミットして push していないバージョンがあるとき、2 つのバージョンに、ほかの共通の祖先の祖先でない共通の祖先が複数あるとき、基点か `<theirs>` が保持期間を過ぎているときは断られます。
|
|
144
210
|
|
|
145
211
|
## fdl withdraw
|
|
146
212
|
|
|
@@ -160,4 +226,14 @@ fdl withdraw <remote> <version>... [--yes]
|
|
|
160
226
|
fdl expire <remote> [--keep 1] [--since 2026-10-01T00:00:00Z] [--ref refs/heads/main]
|
|
161
227
|
```
|
|
162
228
|
|
|
163
|
-
ブランチの最初の親のつながりで、新しい `--keep` 個より古いバージョンの保持期間を終わらせます。`expired.json` を置き、カタログを消します。`--since` 以降に作ったバージョンと、ref
|
|
229
|
+
ブランチの最初の親のつながりで、新しい `--keep` 個より古いバージョンの保持期間を終わらせます。`expired.json` を置き、カタログを消します。`--since` 以降に作ったバージョンと、ref が指すバージョンは残します。データファイルは消しません。消すのは `fdl gc` です。
|
|
230
|
+
|
|
231
|
+
## fdl gc
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
fdl gc <remote> [--grace 7d] [--yes]
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
どの生きているバージョンからも参照されず、`--grace`(`7d`、`24h`、`30m`)より前に書かれたデータファイルとアセットを削除します([共有オブジェクトを消してよいとき](/ja/spec/data-files#共有オブジェクトを消してよいとき))。保持期間を過ぎたバージョンだけが参照していたファイルと、作業カタログが書いて push しなかったファイルがこれに当たります。`--yes` を付けないときは、一覧を表示するだけです。
|
|
238
|
+
|
|
239
|
+
生きているバージョンそれぞれの `files.json` と、行がアセットを持つバージョンのカタログを読みます。HTTP のリポジトリ(削除はホストが行う)と、`files.json` もカタログも無い生きているバージョンがあるときは断られます。
|