Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 597d1d3

Browse files
Merge branch 'dle-4-0' into 'master'
feat(engine): 4.0 alpha – snapshots on demand, Git-like branches, Apache 2.0 license, rename DLE→DBLab See merge request postgres-ai/database-lab!695
2 parents 52a57d2 + 081bd0f commit 597d1d3

File tree

263 files changed

+18542
-3678
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

263 files changed

+18542
-3678
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
.DS_Store
22
.idea/
3+
.env
34

45
engine/bin/
56
/db-lab-run/

‎CLAUDE.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Build/Test/Lint Commands
6+
- Build all components: `cd engine && make build`
7+
- Lint code: `cd engine && make lint`
8+
- Run unit tests: `cd engine && make test`
9+
- Run integration tests: `cd engine && make test-ci-integration`
10+
- Run a specific test: `cd engine && GO111MODULE=on go test -v ./path/to/package -run TestName`
11+
- Run UI: `cd ui && pnpm start:ce` (Community Edition) or `pnpm start:platform`
12+
13+
## Code Style Guidelines
14+
- Go code follows "Effective Go" and "Go Code Review Comments" guidelines
15+
- Use present tense and imperative mood in commit messages
16+
- Limit first commit line to 72 characters
17+
- All Git commits must be signed
18+
- Format Go code with `cd engine && make fmt`
19+
- Use error handling with pkg/errors
20+
- Follow standard Go import ordering
21+
- Group similar functions together
22+
- Error messages should be descriptive and actionable
23+
- UI uses pnpm for package management

‎CONTRIBUTING.md

Lines changed: 151 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,11 @@ These are mostly guidelines, not rules. Use your best judgment, and feel free to
2323
- [Git commit messages](#git-commit-messages)
2424
- [Go styleguide](#go-styleguide)
2525
- [Documentation styleguide](#documentation-styleguide)
26+
- [API design and testing](#api-design-and-testing)
27+
- [UI development](#ui-development)
2628
- [Development setup](#development-setup)
2729
- [Repo overview](#repo-overview)
28-
<!--
2930
- [Building from source](#building-from-source)
30-
-->
3131

3232
---
3333

@@ -121,6 +121,45 @@ We encourage you to follow the principles described in the following documents:
121121
- [Effective Go](https://go.dev/doc/effective_go)
122122
- [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
123123

124+
### Message style guide
125+
Consistent messaging is important throughout the codebase. Follow these guidelines for errors, logs, and user-facing messages:
126+
127+
#### Error messages
128+
- Lowercase for internal errors and logs: `failed to start session` (no ending period)
129+
- Uppercase for user-facing errors: `Requested object does not exist. Specify your request.` (with ending period)
130+
- Omit articles ("a", "an", "the") for brevity: use `failed to update clone` not `failed to update the clone`
131+
- Be specific and actionable whenever possible
132+
- For variable interpolation, use consistent formatting: `failed to find clone: %s`
133+
134+
#### CLI output
135+
- Use concise, action-oriented language
136+
- Present tense with ellipsis for in-progress actions: `Creating clone...`
137+
- Ellipsis (`...`) indicates an ongoing process where the user should wait
138+
- Always follow up with a completion message when the operation finishes
139+
- Past tense with period for results: `Clone created successfully.`
140+
- Include relevant identifiers (IDs, names) in output
141+
142+
#### Progress indication
143+
- Use ellipsis (`...`) to indicate that an operation is in progress and the user should wait
144+
- For longer operations, consider providing percentage or step indicators: `Cloning database... (25%)`
145+
- When an operation with ellipsis completes, always provide a completion message without ellipsis
146+
- Example sequence:
147+
```
148+
Creating clone...
149+
Clone "test-clone" created successfully.
150+
```
151+
152+
#### UI messages
153+
- Be consistent with terminology across UI and documentation
154+
- For confirmations, use format: `{Resource} {action} successfully.`
155+
- For errors, provide clear next steps when possible
156+
- Use sentence case for all messages (capitalize first word only)
157+
158+
#### Commit messages
159+
- Start with lowercase type prefix: `fix:`, `feat:`, `docs:`, etc.
160+
- Use imperative mood: `add feature` not `added feature`
161+
- Provide context in the body if needed
162+
124163
### Documentation styleguide
125164
Documentation for Database Lab Engine and additional components is hosted at https://postgres.ai/docs and is maintained in this GitLab repo: https://gitlab.com/postgres-ai/docs.
126165

@@ -132,6 +171,94 @@ We're building documentation following the principles described at https://docum
132171
133172
Learn more: https://documentation.divio.com/.
134173

174+
### API design and testing
175+
The DBLab API follows RESTful principles with these key guidelines:
176+
- Clear resource-based URL structure
177+
- Consistent usage of HTTP methods (GET, POST, DELETE, etc.)
178+
- Standardized error responses
179+
- Authentication via API tokens
180+
- JSON for request and response bodies
181+
- Comprehensive documentation with examples
182+
183+
#### API Documentation
184+
We use readme.io to host the API docs: https://dblab.readme.io/ and https://api.dblab.dev.
185+
186+
When updating the API specification:
187+
1. Make changes to the OpenAPI spec file in `engine/api/swagger-spec/`
188+
2. Upload it to readme.io as a new documentation version
189+
3. Review and publish the new version
190+
191+
#### Testing with Postman and Newman
192+
Postman collection is generated based on the OpenAPI spec file, using [Portman](https://github.com/apideck-libraries/portman).
193+
194+
##### Setup and Generation
195+
1. Install Portman: `npm install -g @apideck/portman`
196+
2. Generate Postman collection file:
197+
```
198+
portman --cliOptionsFile engine/api/postman/portman-cli.json
199+
```
200+
201+
##### Test Structure Best Practices
202+
- Arrange tests in logical flows (create, read, update, delete)
203+
- Use environment variables to store and pass data between requests
204+
- For object creation tests, capture the ID in the response to use in subsequent requests
205+
- Add validation tests for response status, body structure, and expected values
206+
- Clean up created resources at the end of test flows
207+
208+
##### CI/CD Integration
209+
The Postman collection is automatically run in CI/CD pipelines using Newman. For local testing:
210+
```
211+
newman run engine/api/postman/dblab_api.postman_collection.json -e engine/api/postman/branching.aws.postgres.ai.postman_environment.json
212+
```
213+
214+
### UI development
215+
The Database Lab Engine UI contains two main packages:
216+
- `@postgres.ai/platform` - Platform version of UI
217+
- `@postgres.ai/ce` - Community Edition version of UI
218+
- `@postgres.ai/shared` - Common modules shared between packages
219+
220+
#### Working with UI packages
221+
At the repository root:
222+
- `pnpm install` - Install all dependencies
223+
- `npm run build -ws` - Build all packages
224+
- `npm run start -w @postgres.ai/platform` - Run Platform UI in dev mode
225+
- `npm run start -w @postgres.ai/ce` - Run Community Edition UI in dev mode
226+
227+
_Note: Don't use commands for `@postgres.ai/shared` - it's a dependent package that can't be run or built directly_
228+
229+
#### Platform UI Development
230+
1. Set up environment variables:
231+
```bash
232+
cd ui/packages/platform
233+
cp .env_example_dev .env
234+
```
235+
2. Edit `.env` to set:
236+
- `REACT_APP_API_URL_PREFIX` to point to dev API server
237+
- `REACT_APP_TOKEN_DEBUG` to set your JWT token
238+
3. Start development server: `pnpm run start`
239+
240+
#### CI pipelines for UI code
241+
To deploy UI changes, tag the commit with `ui/` prefix and push it:
242+
```shell
243+
git tag ui/1.0.12
244+
git push origin ui/1.0.12
245+
```
246+
247+
#### Handling Vulnerabilities
248+
When addressing vulnerabilities in UI packages:
249+
1. Update the affected package to a newer version if available
250+
2. For sub-package vulnerabilities, try using [npm-force-resolutions](https://www.npmjs.com/package/npm-force-resolutions)
251+
3. As a last resort, consider forking the package locally
252+
253+
For code-related issues:
254+
1. Consider rewriting JavaScript code in TypeScript
255+
2. Follow recommendations from security analysis tools
256+
3. Only ignore false positives when absolutely necessary
257+
258+
#### TypeScript Migration
259+
- `@postgres.ai/shared` and `@postgres.ai/ce` are written in TypeScript
260+
- `@postgres.ai/platform` is partially written in TypeScript with ongoing migration efforts
261+
135262
### Repo overview
136263
The [postgres-ai/database-lab](https://gitlab.com/postgres-ai/database-lab) repo contains 2 components:
137264
- [Database Lab Engine](https://gitlab.com/postgres-ai/database-lab/-/tree/master/engine)
@@ -190,10 +317,27 @@ Components have a separate version, denoted by either:
190317

191318

192319
### Building from source
193-
Use `Makefile` to build Database Lab components from source.
320+
The Database Lab Engine provides multiple build targets in its `Makefile`:
321+
322+
```bash
323+
cd engine
324+
make help # View all available build targets
325+
make build # Build all components (Server, CLI, CI Checker)
326+
make build-dle # Build Database Lab Engine binary and Docker image
327+
make test # Run unit tests
328+
```
329+
330+
You can also build specific components:
331+
332+
```bash
333+
# Build the CLI for all supported platforms
334+
make build-client
335+
336+
# Build the Server in debug mode
337+
make build-debug
194338
195-
Run `make help` to see all available targets.
339+
# Build and run DLE locally
340+
make run-dle
341+
```
196342

197-
<!--
198-
mention dev images: See our [GitLab Container Registry](https://gitlab.com/postgres-ai/database-lab/container_registry) to find the images built for development branches.
199-
-->
343+
See our [GitLab Container Registry](https://gitlab.com/postgres-ai/database-lab/container_registry) to find pre-built images for development branches.

‎README.md

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -8,18 +8,18 @@
88
<div align="center"><h1 align="center">DBLab Engine</h1></div>
99

1010
<div align="center">
11-
<a href="https://twitter.com/intent/tweet?via=Database_Lab&url=https://github.com/postgres-ai/database-lab-engine/&text=20@PostgreSQL%branching%20–%20DLE%20provides%20blazing-fast%20database%20cloning%20to%20build%20powerful%20development,%20test,%20QA,%20staging%20environments.">
11+
<a href="https://twitter.com/intent/tweet?via=Database_Lab&url=https://github.com/postgres-ai/database-lab-engine/&text=PostgreSQL%20branching%20%E2%80%93%20DLE%20provides%20blazing-fast%20database%20cloning%20to%20build%20powerful%20development,%20test,%20QA,%20and%20staging%20environments.">
1212
<img src="https://img.shields.io/twitter/url/https/github.com/postgres-ai/database-lab-engine.svg?style=for-the-badge" alt="twitter">
1313
</a>
1414
</div>
1515

1616
<div align="center">
17-
<strong>⚡ Blazing-fast Postgres cloning and branching 🐘</strong><br /><br />
17+
<strong>⚡ Blazing-fast PostgreSQL cloning and branching 🐘</strong><br /><br />
1818
🛠️ Build powerful dev/test environments.<br />
1919
🔃 Cover 100% of DB migrations with CI tests.<br>
2020
💡 Quickly verify ChatGPT ideas to get rid of hallucinations.<br /><br />
21-
Available for any PostgreSQL, including self-managed and managed<sup>*</sup> like AWS RDS, GCP CloudSQL, Supabase, Timescale.<br /><br />
22-
Can be installed and used anywhere: all clouds and on-premises.
21+
Available for any PostgreSQL, including self-managed and managed services<sup>*</sup> like AWS RDS, GCP Cloud SQL, Supabase, and Timescale.<br /><br />
22+
It can be installed and used anywhere: across all cloud environments and on-premises.
2323
</div>
2424

2525
<br />
@@ -60,11 +60,11 @@ For example, cloning a 1 TiB PostgreSQL database takes just about 10 seconds. On
6060
<p><img src="./assets/dle-demo-animated.gif" border="0" /></p>
6161

6262
Try it yourself right now:
63-
- Visit [Postgres.ai Console](https://console.postgres.ai/), set up your first organization and provision a DBLab Standard Edition (DBLab SE) to any cloud or on-prem
63+
- Visit [Postgres.ai Console](https://console.postgres.ai/), set up your first organization, and provision a DBLab Standard Edition (DBLab SE) to any cloud or on-premises environment.
6464
- [Pricing](https://postgres.ai/pricing) (starting at 62ドル/month)
65-
- [Doc: How to install DBLab SE](https://postgres.ai/docs/how-to-guides/administration/install-dle-from-postgres-ai)
65+
- [Documentation: How to install DBLab SE](https://postgres.ai/docs/how-to-guides/administration/install-dle-from-postgres-ai)
6666
- Demo: https://demo.dblab.dev (use the token `demo-token` to access)
67-
- Looking for a free version? Install DBLab Community Edition by [following this tutorial](https://postgres.ai/docs/tutorials/database-lab-tutorial)
67+
- Looking for a free version? Install the DBLab Community Edition by [following this tutorial](https://postgres.ai/docs/tutorials/database-lab-tutorial).
6868

6969
## How it works
7070
Thin cloning is fast because it is based on [Copy-on-Write (CoW)](https://en.wikipedia.org/wiki/Copy-on-write#In_computer_storage). DBLab employs two technologies for enabling thin cloning: [ZFS](https://en.wikipedia.org/wiki/ZFS) (default) and [LVM](https://en.wikipedia.org/wiki/Logical_Volume_Manager_(Linux)).
@@ -88,20 +88,20 @@ Read more:
8888

8989
## Features
9090
- Speed & scale
91-
- Blazing-fast cloning of Postgres databases – clone in seconds, irrespective of database size
91+
- Blazing-fast cloning of PostgreSQL databases – clone in seconds, irrespective of database size
9292
- Theoretical max of snapshots/clones: 2<sup>64</sup> ([ZFS](https://en.wikipedia.org/wiki/ZFS), default)
9393
- Maximum size of PostgreSQL data directory: 256 quadrillion zebibytes, or 2<sup>128</sup> bytes ([ZFS](https://en.wikipedia.org/wiki/ZFS), default)
9494
- Support & technologies
9595
- Supported PostgreSQL versions: 9.6–17
9696
- Thin cloning ([CoW](https://en.wikipedia.org/wiki/Copy-on-write)) technologies: [ZFS](https://en.wikipedia.org/wiki/ZFS) and [LVM](https://en.wikipedia.org/wiki/Logical_Volume_Manager_(Linux))
9797
- UI for manual tasks and API & CLI for automation
9898
- Packaged in Docker containers for all components
99-
- Postgres containers
99+
- PostgreSQL containers
100100
- Popular extensions including contrib modules, pgvector, HypoPG and many others ([docs](https://postgres.ai/docs/database-lab/supported-databases#extensions-included-by-default))
101101
- Customization capabilities for containers ([docs](https://postgres.ai/docs/database-lab/supported-databases#how-to-add-more-extensions))
102-
- Docker container and Postgres config parameters in DBLab config
102+
- Docker container and PostgreSQL configuration parameters in the DBLab config
103103
- Source database requirements
104-
- Location flexibility: self-managed Postgres, AWS RDS, GCP CloudSQL, Azure, etc. No source adjustments needed
104+
- Location flexibility: self-managed PostgreSQL, AWS RDS, GCP Cloud SQL, Azure, etc.—no source adjustments needed.
105105
- No ZFS or Docker requirements for source databases
106106
- Data provisioning & retrieval
107107
- Physical (pg_basebackup, WAL-G, pgBackRest) and logical (dump/restore) provisioning
@@ -128,8 +128,8 @@ The simplest way to show your support is by giving us a star on GitHub or GitLab
128128
![Add a star](./assets/star.gif)
129129

130130
### Spread the word
131-
- Shoot out a tweet and mention [@Database_Lab](https://twitter.com/Database_Lab)
132-
- Share this repo's link on your favorite social media platform
131+
- Tweet about DBLab and mention [@Database_Lab](https://twitter.com/Database_Lab).
132+
- Share a link to this repository on your favorite social media platform.
133133

134134
### Share your experience
135135
If DBLab has been a vital tool for you, tell the world about your journey. Use the logo from the `./assets` folder for a visual touch. Whether it's in documents, presentations, applications, or on your website, let everyone know you trust and use DBLab.
@@ -157,10 +157,7 @@ For darker backgrounds:
157157
```
158158

159159
### Propose an idea or report a bug
160-
Check out our [contributing guide](./CONTRIBUTING.md) for more details.
161-
162-
### Participate in development
163-
Check out our [contributing guide](./CONTRIBUTING.md) for more details.
160+
For proposals, bug reports, and participation in development, see our [Contributing Guide](./CONTRIBUTING.md).
164161

165162

166163
### Reference guides
@@ -173,8 +170,11 @@ Check out our [contributing guide](./CONTRIBUTING.md) for more details.
173170
- [How to install and initialize Database Lab CLI](https://postgres.ai/docs/how-to-guides/cli/cli-install-init)
174171
- [How to manage DBLab](https://postgres.ai/docs/how-to-guides/administration)
175172
- [How to work with clones](https://postgres.ai/docs/how-to-guides/cloning)
173+
- [How to work with branches](XXXXXXX) – TBD
174+
- [How to integrate DBLab with GitHub Actions](XXXXXXX) – TBD
175+
- [How to integrate DBLab with GitLab CI/CD](XXXXXXX) – TBD
176176

177-
More you can find in [the "How-to guides" section](https://postgres.ai/docs/how-to-guides) of the docs.
177+
You can find more in the ["How-to guides" section](https://postgres.ai/docs/how-to-guides) of the documentation.
178178

179179
### Miscellaneous
180180
- [DBLab Docker images](https://hub.docker.com/r/postgresai/dblab-server)
@@ -183,15 +183,15 @@ More you can find in [the "How-to guides" section](https://postgres.ai/docs/how-
183183
- [DB Migration Checker](https://postgres.ai/docs/db-migration-checker)
184184

185185
## License
186-
DBLab source code is licensed under the OSI-approved open source license [Apache 2.0](https://opensource.org/license/apache-2-0/).
186+
The DBLab source code is licensed under the OSI-approved open source license [Apache 2.0](https://opensource.org/license/apache-2-0/).
187187

188188
Reach out to the Postgres.ai team if you want a trial or commercial license that does not contain the GPL clauses: [Contact page](https://postgres.ai/contact).
189189

190190
## Community & Support
191-
- ["Database Lab Engine Community Covenant Code of Conduct"](./CODE_OF_CONDUCT.md)
192-
- Where to get help: [Contact page](https://postgres.ai/contact)
191+
- [Database Lab Engine Community Covenant Code of Conduct](./CODE_OF_CONDUCT.md)
192+
- Where to get help: [Contact page](https://postgres.ai/contact).
193193
- [Community Slack](https://slack.postgres.ai)
194-
- If you need to report a security issue, follow instructions in ["Database Lab Engine security guidelines"](./SECURITY.md)
194+
- If you need to report a security issue, follow the instructions in [Database Lab Engine Security Guidelines](./SECURITY.md).
195195

196196
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg?color=blue)](./CODE_OF_CONDUCT.md)
197197

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /