Skip to content

Commit

Permalink
docs: README for v15
Browse files Browse the repository at this point in the history
  • Loading branch information
@mrdrivingduck
mrdrivingduck committed Sep 4, 2024
1 parent 0c658df commit ade7f2d
Show file tree
Hide file tree
Showing 4 changed files with 376 additions and 0 deletions.
59 changes: 59 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Contributing

PolarDB for PostgreSQL is an open source project based on PostgreSQL and other open source projects. Our main target is to create a larger community of PostgreSQL. Contributors are welcomed to submit their code and ideas. In a long run, we hope this project can be managed by developers from both inside and outside Alibaba Cloud.

## Before Contributing

- Follow the instructions and sign [CLA](https://gist.github.com/alibaba-oss/151a13b0a72e44ba471119c7eb737d74) of PolarDB for PostgreSQL

## Steps

Here is a checklist to prepare and submit your PR (pull request):

- Create your own Github repository copy by forking `ApsaraDB/PolarDB-for-PostgreSQL`.
- Checkout documentations [Advanced Deployment](../deploying/deploy.md) for how to hack PolarDB-PG.
- Run `make stylecheck` to format your code, and push changes to your personal fork.
- Edit detailed commit message, and create a PR to upstream.
- Wait for all CI checks to pass.
- Wait for review and address all feedbacks.
- Wait for merging.

## Coding Style

### Languages

- PostgreSQL kernel, extension and related tools use C, in order to remain compatibility with community version and to upgrade easily.
- Management related tools can use shell or Perl for efficient development.

### Coding Style

- Coding in C follows PostgreSQL's programing style, such as naming, error message format, control statements, length of lines, comment format, length of functions and global variables. In detail, please refer to [PostgreSQL style](https://www.postgresql.org/docs/15/source.html). Here is some highlines:

- Code in PostgreSQL should only rely on language features available in the C99 standard
- Do not use `//` for comments
- Both, macros with arguments and static inline functions, may be used. The latter is preferred only if the former simplifies coding.
- Follow BSD C programming conventions

- Programs in shell can follow [Google code conventions](https://google.github.io/styleguide/shellguide.html)
- Program in Perl can follow official [Perl style](https://perldoc.perl.org/perlstyle)

### Code Design and Review

We share the same thought and rules as [Google Open Source Code Review](https://github.com/google/eng-practices/blob/master/review/index.md).

Before submitting code review, please run unit test and pass all tests under `src/test`, such as regress and isolation. Unit tests or function tests should be submitted with code modification.

In addition to code review, this document offers instructions for the whole cycle of high-quality development, from design, implementation, testing, documentation to preparing for code review. Many good questions are asked for critical steps during development, such as about design, function, complexity, testing, naming, documentation, and code review. The documentation summarizes rules for code review as follows. During a code review, you should make sure that:

- The code is well-designed.
- The functionality is good for the users of the code.
- Any UI changes are sensible and look good.
- Any parallel programming is done safely.
- The code isn't more complex than it needs to be.
- The developer isn't implementing things they might need in the future but don't know they need now.
- Code has appropriate unit tests.
- Tests are well-designed.
- The developer used clear names for everything.
- Comments are clear and useful, and mostly explain why instead of what.
- Code is appropriately documented.
- The code conforms to our style guides.
109 changes: 109 additions & 0 deletions NOTICE
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
=================================================================
For: PolarDB for PostgreSQL
=================================================================

Copyright (c) 2024, Alibaba Group Holding Limited

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

=================================================================
For: PostgreSQL Database Management System
(formerly known as Postgres, then as Postgres95)

---------------------- PostgreSQL License -----------------------
=================================================================

Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group

Portions Copyright (c) 1994, The Regents of the University of California

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose, without fee, and without a written agreement
is hereby granted, provided that the above copyright notice and this
paragraph and the following two paragraphs appear in all copies.

IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING
LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS
DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO
PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

=================================================================
For: pg_jieba
=================================================================

Copyright (c) 2015, Jaimin Pan ([email protected])
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.

* Neither the name of pg_jieba nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

=================================================================
For: pg_repack
=================================================================

Portions Copyright (c) 2008-2011, NIPPON TELEGRAPH AND TELEPHONE CORPORATION
Portions Copyright (c) 2011, Itagaki Takahiro
Portions Copyright (c) 2012-2020, The Reorg Development Team
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of the authors nor the names of its contributors may
be used to endorse or promote products derived from this software
without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
106 changes: 106 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
<div align="center">

[![logo](./polar-doc/docs/.vuepress/public/images/polardb.png)](https://www.polardbpg.com/home)

# PolarDB for PostgreSQL

**A cloud-native database developed by Alibaba Cloud**

#### English | [简体中文](./README_zh.md)

[![official](https://img.shields.io/badge/official%20site-blueviolet?style=flat&logo=alibabacloud)](https://www.polardbpg.com/home)

[![GitHub License](https://img.shields.io/github/license/ApsaraDB/PolarDB-for-PostgreSQL?style=flat&logo=apache)](./LICENSE)
[![github-issues](https://img.shields.io/github/issues/ApsaraDB/PolarDB-for-PostgreSQL?style=flat&logo=github)](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL/issues)
[![github-pullrequest](https://img.shields.io/github/issues-pr/ApsaraDB/PolarDB-for-PostgreSQL?style=flat&logo=github)](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL/pulls)
[![GitHub Discussions](https://img.shields.io/github/discussions/ApsaraDB/PolarDB-for-PostgreSQL?logo=github)](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL/discussions)
[![github-forks](https://img.shields.io/github/forks/ApsaraDB/PolarDB-for-PostgreSQL?style=flat&logo=github)](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL/network/members)
[![github-stars](https://img.shields.io/github/stars/ApsaraDB/PolarDB-for-PostgreSQL?style=flat&logo=github)](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL/stargazers)
[![github-contributors](https://img.shields.io/github/contributors/ApsaraDB/PolarDB-for-PostgreSQL?style=flat&logo=github)](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL/graphs/contributors)
[![GitHub deployments](<https://img.shields.io/github/deployments/ApsaraDB/PolarDB-for-PostgreSQL/github-pages?logo=github&label=github-pages%20(docs)>)](https://apsaradb.github.io/PolarDB-for-PostgreSQL/zh/)
[![GitHub branch check runs](<https://img.shields.io/github/check-runs/ApsaraDB/PolarDB-for-PostgreSQL/POLARDB_15_STABLE?logo=github&label=checks%20(v15)>)](https://github.com/ApsaraDB/PolarDB-for-PostgreSQL/tree/POLARDB_15_STABLE)
[![Leaderboard](https://img.shields.io/badge/PolarDB--for--PostgreSQL-Check%20Your%20Contribution-orange?style=flat&logo=alibabacloud)](https://opensource.alibaba.com/contribution_leaderboard/details?projectValue=polardb-pg)

</div>

## Overview

![arch.png](./polar-doc/docs/imgs/1_polardb_architecture.png)

PolarDB for PostgreSQL (hereafter simplified as PolarDB) is a cloud native database service independently developed by Alibaba Cloud. This service is 100% compatible with PostgreSQL and uses a shared-storage-based architecture in which computing is decoupled from storage. This service features flexible scalability, millisecond-level latency and hybrid transactional/analytical processing (HTAP) capabilities.

1. Flexible scalability: You can use the service to scale out a compute cluster or a storage cluster based on your business requirements.
- If the computing power is insufficient, you can scale out only the compute cluster.
- If the storage capacity or the storage I/O is insufficient, you can scale out a storage cluster without interrupting your service.
2. Millisecond-level latency:
- Write-ahead logging (WAL) logs are stored in the shared storage. Only the metadata of WAL records is replicated from the read-write node to read-only nodes.
- The _LogIndex_ technology provided by PolarDB features two record replay modes: lazy replay and parallel replay. The technology can be used to minimize the record replication latency from the read-write node to read-only nodes.
3. HTAP: HTAP is implemented by using a shared-storage-based massively parallel processing (MPP) architecture. The architecture is used to accelerate online analytical processing (OLAP) queries in online transaction processing (OLTP) scenarios. PolarDB supports a complete suite of data types that are used in OLTP scenarios. PolarDB supports two computing engines that can process these types of data:
- Standalone execution: processes OLTP queries that feature high concurrency.
- Distributed execution: processes large OLAP queries.

PolarDB provides a wide range of innovative multi-model database capabilities to help you process, analyze, and search for different types of data, such as spatio-temporal, geographic information system (GIS), image, vector, and graph data.

## Branch Introduction

The `POLARDB_15_STABLE` is the stable branch based on PostgreSQL 15, which supports compute-storage separation architecture.

## Architecture and Roadmap

PolarDB for PostgreSQL uses a shared-storage-based architecture in which computing is decoupled from storage. The conventional shared-nothing architecture is changed to the shared-storage architecture. N copies of data in the compute cluster and N copies of data in the storage cluster are changed to N copies of data in the compute cluster and one copy of data in the storage cluster. The shared storage stores one copy of data, but the data states in memory are different. The WAL logs must be synchronized from the primary node to read-only nodes to ensure data consistency. In addition, when the primary node flushes dirty pages, it must be controlled to prevent the read-only nodes from reading future pages. Meanwhile, the read-only nodes must be prevented from reading the outdated pages that are not correctly replayed in memory. To resolve this issue, PolarDB provides the index structure _LogIndex_ to maintain the page replay history. LogIndex can be used to synchronize data from the primary node to read-only nodes.

After computing is decoupled from storage, the I/O latency and throughput increase. When a single read-only node is used to process analytical queries, the CPUs, memory, and I/O of other read-only nodes and the large storage I/O bandwidth cannot be fully utilized. To resolve this issue, PolarDB provides the shared-storage-based MPP engine. The engine can use CPUs to accelerate analytical queries at SQL level and support a mix of OLAP workloads and OLTP workloads for HTAP.

For more information, see [Architecture](https://apsaradb.github.io/PolarDB-for-PostgreSQL/theory/arch-overview.html).

## Quick Start with PolarDB

If you have Docker installed already，then you can pull the instance image of PolarDB-PG based on local storage. Create, run and enter the container, and use PolarDB-PG instance directly:

```bash
# pull the instance image and run the container
docker pull polardb/polardb_pg_local_instance:15
docker run -it --rm polardb/polardb_pg_local_instance:15 psql
# check
postgres=# SELECT version();
version
----------------------------------------------------------------------
PostgreSQL 15.x (PolarDB 15.x.x.x build xxxxxxxx) on {your_platform}
(1 row)
```

For more advanced deployment way, please refer to [Advanced Deployment](https://apsaradb.github.io/PolarDB-for-PostgreSQL/deploying/deploy.html). Before your deployment, we recommand to figure out the [Architecture](https://apsaradb.github.io/PolarDB-for-PostgreSQL/deploying/introduction.html) of PolarDB for PostgreSQL.

## Development

Please refer to [Development Guide](https://apsaradb.github.io/PolarDB-for-PostgreSQL/development/dev-on-docker.html) to compile and development PolarDB for PostgreSQL.

## Documentation

Please refer to [Online Documentation Website](https://apsaradb.github.io/PolarDB-for-PostgreSQL/) to see the whole documentations.

If you want to explore or develop documentation locally, see [Document Contribution](https://apsaradb.github.io/PolarDB-for-PostgreSQL/contributing/contributing-polardb-docs.html).

## Contributing

You are welcome to make contributions to PolarDB for PostgreSQL. Here are the contributors:

<a href="https://github.com/ApsaraDB/PolarDB-for-PostgreSQL/graphs/contributors">
<img src="https://contrib.rocks/image?repo=ApsaraDB/PolarDB-for-PostgreSQL" />
</a>

Made with [contrib.rocks](https://contrib.rocks).

## Software License

PolarDB for PostgreSQL is released under Apache License (Version 2.0), developed based on PostgreSQL which is released under PostgreSQL License. See [LICENSE](./LICENSE) for more information.

PolarDB for PostgreSQL contains various third-party components under other open source licenses. See [NOTICE](./NOTICE) for more information.

## Join the Community

Click this [link](https://qr.dingtalk.com/action/joingroup?code=v1,k1,AEOqzSc8Uwzer7yhpNeYp8okNX3KVqpDMk/2oZ3ZRnQ=&_dt_no_comment=1&origin=11) and use DingTalk application to join the DingTalk group.

## Copyright

Copyright © Alibaba Group, Inc.
Loading

0 comments on commit ade7f2d

Please sign in to comment.