diff --git a/.changes/header.tpl.md b/.changes/header.tpl.md new file mode 100644 index 00000000..df8faa7b --- /dev/null +++ b/.changes/header.tpl.md @@ -0,0 +1,6 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html), +and is generated by [Changie](https://github.com/miniscruff/changie). diff --git a/.changes/unreleased/.gitkeep b/.changes/unreleased/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.changie.yaml b/.changie.yaml new file mode 100644 index 00000000..1efbf584 --- /dev/null +++ b/.changie.yaml @@ -0,0 +1,33 @@ +changesDir: .changes +unreleasedDir: unreleased +headerPath: header.tpl.md +changelogPath: CHANGELOG.md +versionExt: md +envPrefix: CHANGIE_ +versionFormat: '## dbt-postgres {{.Version}} - {{.Time.Format "January 02, 2006"}}' +kindFormat: '### {{.Kind}}' +changeFormat: '* {{.Body}}' +kinds: + - label: Breaking Changes + - label: Features + - label: Fixes + - label: Docs + - label: Under the Hood + - label: Dependencies + - label: Security +newlines: + afterChangelogHeader: 1 + afterKind: 1 + afterChangelogVersion: 1 + beforeKind: 1 + endOfVersion: 1 + +custom: +- key: Author + label: GitHub Username(s) (separated by a single space if multiple) + type: string + minLength: 3 +- key: Issue + label: GitHub Issue Number (separated by a single space if multiple) + type: string + minLength: 1 diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 00000000..394de1f2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,81 @@ +name: 🐞 Bug +description: Report a bug or an issue you've found with dbt-postgres +title: "[Bug] " +labels: ["bug", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this bug report! + - type: checkboxes + attributes: + label: Is this a new bug? + description: > + In other words, is this an error, flaw, failure or fault in our software? + + If this is a bug that broke existing functionality that used to work, please open a regression issue. + If this is a bug experienced while using dbt Cloud, please report to [support](mailto:support@getdbt.com). + If this is a request for help or troubleshooting code in your own dbt project, please join our [dbt Community Slack](https://www.getdbt.com/community/join-the-community/) or open a [Discussion question](https://github.com/dbt-labs/docs.getdbt.com/discussions). + + Please search to see if an issue already exists for the bug you encountered. + options: + - label: I believe this is a new bug + required: true + - label: I have searched the existing issues, and I could not find an existing issue for this bug + required: true + - type: textarea + attributes: + label: Current Behavior + description: A concise description of what you're experiencing. + validations: + required: true + - type: textarea + attributes: + label: Expected Behavior + description: A concise description of what you expected to happen. + validations: + required: true + - type: textarea + attributes: + label: Steps To Reproduce + description: Steps to reproduce the behavior. + placeholder: | + 1. In this environment... + 2. With this config... + 3. Run '...' + 4. See error... + validations: + required: true + - type: textarea + id: logs + attributes: + label: Relevant log output + description: | + If applicable, log output to help explain your problem. + render: shell + validations: + required: false + - type: textarea + attributes: + label: Environment + description: | + examples: + - **OS**: Ubuntu 20.04 + - **Python**: 3.11.6 (`python3 --version`) + - **dbt-postgres**: 1.0.0 (`dbt --version`) + value: | + - OS: + - Python: + - dbt-postgres: + render: markdown + validations: + required: false + - type: textarea + attributes: + label: Additional Context + description: | + Links? References? Anything that will give us more context about the issue you are encountering! + + Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..8d0995f4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: Ask the community for help + url: https://github.com/dbt-labs/docs.getdbt.com/discussions + about: Need help troubleshooting? Check out our guide on how to ask + - name: Contact dbt Cloud support + url: mailto:support@getdbt.com + about: Are you using dbt Cloud? Contact our support team for help! + - name: Participate in Discussions + url: https://github.com/dbt-labs/dbt-postgres/discussions + about: Do you have a Big Idea for dbt-postgres? Read open discussions, or start a new one diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml new file mode 100644 index 00000000..edc32c6c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.yml @@ -0,0 +1,59 @@ +name: ✨ Feature +description: Propose a straightforward extension of dbt-postgres functionality +title: "[Feature] <title>" +labels: ["enhancement", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this feature request! + - type: checkboxes + attributes: + label: Is this your first time submitting a feature request? + description: > + We want to make sure that features are distinct and discoverable, + so that other members of the community can find them and offer their thoughts. + + Issues are the right place to request straightforward extensions of existing dbt-postgres functionality. + For "big ideas" about future capabilities of dbt-postgres, we ask that you open a + [discussion](https://github.com/dbt-labs/dbt-postgres/discussions/new?category=ideas) in the "Ideas" category instead. + options: + - label: I have read the [expectations for open source contributors](https://docs.getdbt.com/docs/contributing/oss-expectations) + required: true + - label: I have searched the existing issues, and I could not find an existing issue for this feature + required: true + - label: I am requesting a straightforward extension of existing dbt-postgres functionality, rather than a Big Idea better suited to a discussion + required: true + - type: textarea + attributes: + label: Describe the feature + description: A clear and concise description of what you want to happen. + validations: + required: true + - type: textarea + attributes: + label: Describe alternatives you've considered + description: | + A clear and concise description of any alternative solutions or features you've considered. + validations: + required: false + - type: textarea + attributes: + label: Who will this benefit? + description: | + What kind of use case will this feature be useful for? Please be specific and provide examples, this will help us prioritize properly. + validations: + required: false + - type: input + attributes: + label: Are you interested in contributing this feature? + description: Let us know if you want to write some code, and how we can help. + validations: + required: false + - type: textarea + attributes: + label: Anything else? + description: | + Links? References? Anything that will give us more context about the feature you are suggesting! + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/regression-report.yml b/.github/ISSUE_TEMPLATE/regression-report.yml new file mode 100644 index 00000000..73bfbe75 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/regression-report.yml @@ -0,0 +1,78 @@ +name: ☣️ Regression +description: Report a regression you've observed in a newer version of dbt-postgres +title: "[Regression] <title>" +labels: ["regression", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this regression report! + - type: checkboxes + attributes: + label: Is this a regression? + description: > + A regression is when documented functionality works as expected in an older version of the software + and no longer works after upgrading to a newer version the software + options: + - label: I believe this is a regression in functionality + required: true + - label: I have searched the existing issues, and I could not find an existing issue for this regression + required: true + - type: textarea + attributes: + label: Current Behavior + description: A concise description of what you're experiencing. + validations: + required: true + - type: textarea + attributes: + label: Expected/Previous Behavior + description: A concise description of what you expected to happen. + validations: + required: true + - type: textarea + attributes: + label: Steps To Reproduce + description: Steps to reproduce the behavior. + placeholder: | + 1. In this environment... + 2. With this config... + 3. Run '...' + 4. See error... + validations: + required: true + - type: textarea + id: logs + attributes: + label: Relevant log output + description: | + If applicable, log output to help explain your problem. + render: shell + validations: + required: false + - type: textarea + attributes: + label: Environment + description: | + examples: + - **OS**: Ubuntu 20.04 + - **Python**: 3.11.6 (`python3 --version`) + - **dbt-postgres (working version)**: 1.1.0 (`dbt --version`) + - **dbt-postgres (regression version)**: 1.2.0 (`dbt --version`) + value: | + - OS: + - Python: + - dbt-postgres (working version): + - dbt-postgres (regression version): + render: markdown + validations: + required: true + - type: textarea + attributes: + label: Additional Context + description: | + Links? References? Anything that will give us more context about the issue you are encountering! + + Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in. + validations: + required: false diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000..2a6f3449 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,8 @@ +version: 2 +updates: + # python dependencies + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "daily" + rebase-strategy: "disabled" diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..26e27c4d --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,35 @@ +resolves # +[docs](https://github.com/dbt-labs/docs.getdbt.com/issues/new/choose) dbt-labs/docs.getdbt.com/# + +<!--- + Include the number of the issue addressed by this PR above if applicable. + PRs for code changes without an associated issue *will not be merged*. + See CONTRIBUTING.md for more information. + + Include the number of the docs issue that was opened for this PR. If + this change has no user-facing implications, "N/A" suffices instead. New + docs tickets can be created by clicking the link above or by going to + https://github.com/dbt-labs/docs.getdbt.com/issues/new/choose. +--> + +### Problem + +<!--- + Describe the problem this PR is solving. What is the application state + before this PR is merged? +--> + +### Solution + +<!--- + Describe the way this PR solves the above problem. Add as much detail as you + can to help reviewers understand your changes. Include any alternatives and + tradeoffs you considered. +--> + +### Checklist + +- [ ] I have read [the contributing guide](https://github.com/dbt-labs/dbt-postgres/blob/main/CONTRIBUTING.md) and understand what's expected of me +- [ ] I have run this code in development and it appears to resolve the stated issue +- [ ] This PR includes tests, or tests are not required/relevant for this PR +- [ ] This PR has no interface changes (e.g. macros, cli, logs, json artifacts, config files, adapter interface, etc) or this PR has already received feedback and approval from Product or DX diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..6769e21d --- /dev/null +++ b/.gitignore @@ -0,0 +1,160 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# poetry +# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control +#poetry.lock + +# pdm +# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. +#pdm.lock +# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it +# in version control. +# https://pdm.fming.dev/#use-with-ide +.pdm.toml + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# PyCharm +# JetBrains specific template is maintained in a separate JetBrains.gitignore that can +# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore +# and can be added to the global gitignore or merged into this file. For a more nuclear +# option (not recommended) you can uncomment the following to ignore the entire idea folder. +#.idea/ \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..5ca9d33a --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,9 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html), +and is generated by [Changie](https://github.com/miniscruff/changie). + + +No releases yet, this file will be updated when generating your first release. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..9d2880e8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,182 @@ +# Contributing to `dbt-postgres` + +- [About this document](#about-this-document) +- [Getting the code](#getting-the-code) +- [Developing](#developing) +- [Testing](#testing) +- [Documentation](#documentation) +- [Submitting a pull request](#submitting-a-pull-request) + + +## About this document + +This document is a guide for anyone interested in contributing to `dbt-postgres`. +It outlines how to install `dbt-postgres` for development, +run tests locally, update documentation, and submit pull requests. +This guide assumes users are developing on a Linux or MacOS system. +The following utilities are needed or will be installed in this guide: + +- `pip` +- `virturalenv` +- `git` +- `changie` + +If local functional testing is required, then a database instance +and appropriate credentials are also required. + +In addition to this guide, users are highly encouraged to read the `dbt-core` +[CONTRIBUTING.md](https://github.com/dbt-labs/dbt-core/blob/main/CONTRIBUTING.md). +Almost all information there is applicable here. + + +## Getting the code + +`git` is required to download, modify, and sync the `dbt-postgres` code. +There are several ways to install Git. For MacOS: + +- Install [Xcode](https://developer.apple.com/support/xcode/) +- Install [Xcode Command Line Tools](https://mac.install.guide/commandlinetools/index.html) + +### External contributors + +Contributors external to the `dbt-labs` GitHub organization can contribute to `dbt-postgres` +by forking the `dbt-postgres` repository. For more on forking, check out the +[GitHub docs on forking](https://help.github.com/en/articles/fork-a-repo). To contribute: + +1. Fork the `dbt-labs/dbt-postgres` repository (e.g. `{forked-org}/dbt-postgres`) +2. Clone `{forked-org}/dbt-postgres` locally +3. Check out a new branch locally +4. Make changes in the new branch +5. Push the new branch to `{forked-org}/dbt-postgres` +6. Open a pull request in `dbt-labs/dbt-postgres` to merge `{forked-org}/dbt-postgres/{new-branch}` into `main` + +### dbt Labs contributors + +Contributors in the `dbt Labs` GitHub organization have push access to the `dbt-postgres` repo. +Rather than forking `dbt-labs/dbt-postgres`, use `dbt-labs/dbt-postgres` directly. To contribute: + +1. Clone `dbt-labs/dbt-postgres` locally +2. Check out a new branch locally +3. Make changes in the new branch +4. Push the new branch to `dbt-labs/dbt-postgres` +5. Open a pull request in `dbt-labs/dbt-postgres` to merge `{new-branch}` into `main` + + +## Developing + +### Installation + +1. Ensure the latest version of `pip` is installed: + ```shell + pip install --upgrade pip + ``` +2. Configure and activate a virtual environment using `virtualenv` as described in +[Setting up an environment](https://github.com/dbt-labs/dbt-core/blob/HEAD/CONTRIBUTING.md#setting-up-an-environment) +3. Install `dbt-postgres` and development dependencies in the virtual environment + ```shell + pip install -e .[dev] + ``` + +When `dbt-postgres` is installed this way, any changes made to the `dbt-postgres` source code +will be reflected in the virtual environment immediately. + + +## Testing + +`dbt-postgres` contains [unit](https://github.com/dbt-labs/dbt-postgres/tree/main/tests/unit) +and [functional](https://github.com/dbt-labs/dbt-postgres/tree/main/tests/functional) tests. + +### Unit tests + +Unit tests can be run locally without setting up a database connection: + +```shell +# Note: replace $strings with valid names + +# run all unit tests in a module +python -m pytest tests/unit/$test_file_name.py +# run a specific unit test +python -m pytest tests/unit/$test_file_name.py::$test_class_name::$test_method_name +``` + +### Functional tests + +Functional tests require a database to test against. There are two primary ways to run functional tests: + +- Tests will run automatically against a dbt Labs owned database during PR checks +- Tests can be run locally by configuring a `test.env` file with appropriate `ENV` variables: + ```shell + cp test.env.example test.env + $EDITOR test.env + ``` + +> **_WARNING:_** The parameters in `test.env` must link to a valid database. +> `test.env` is git-ignored, but be _extra_ careful to never check in credentials +> or other sensitive information when developing. + +Functional tests can be run locally with a valid database connection configured in `test.env`: + +```shell +# Note: replace $strings with valid names + +# run all functional tests in a directory +python -m pytest tests/functional/$test_directory +# run all functional tests in a module +python -m pytest tests/functional/$test_dir_and_filename.py +# run all functional tests in a class +python -m pytest tests/functional/$test_dir_and_filename.py::$test_class_name +# run a specific functional test +python -m pytest tests/functional/$test_dir_and_filename.py::$test_class_name::$test__method_name +``` + + +## Documentation + +### User documentation + +Many changes will require an update to `dbt-postgres` user documentation. +All contributors, whether internal or external, are encouraged to open an issue or PR +in the docs repo when submitting user-facing changes. Here are some relevant links: + +- [User docs](https://docs.getdbt.com/) + - [Warehouse Profile](https://docs.getdbt.com/reference/warehouse-profiles/) + - [Resource Configs](https://docs.getdbt.com/reference/resource-configs/) +- [User docs repo](https://github.com/dbt-labs/docs.getdbt.com) + +### CHANGELOG entry + +`dbt-postgres` uses [changie](https://changie.dev) to generate `CHANGELOG` entries. +Follow the steps to [install `changie`](https://changie.dev/guide/installation/). + +Once changie is installed and the PR is created, run: + ```shell + changie new + ``` +`changie` will walk through the process of creating a changelog entry. +Remember to commit and push the file that's created. + +> **_NOTE:_** Do not edit the `CHANGELOG.md` directly. +> Any modifications will be lost by the consolidation process. + + +## Submitting a pull request + +### Signing the CLA + +> **_NOTE:_** All contributors to `dbt-postgres` must sign the +> [Contributor License Agreement](https://docs.getdbt.com/docs/contributor-license-agreements)(CLA). + +Maintainers will be unable to merge contributions until the contributor signs the CLA. +This is a one time requirement, not a per-PR requirement. +Even without a CLA, anyone is welcome to open issues and comment on existing issues or PRs. + +### Opening a pull request + +A `dbt-postgres` maintainer will be assigned to review each PR based on priority and capacity. +They may suggest code revisions for style and clarity or they may request additional tests. +These are good things! dbt Labs believes that contributing high-quality code is a collaborative effort. +The same process is followed whether the contributor is external or another `dbt-postgres` maintainer. +Once all tests are passing and the PR has been approved by the appropriate code owners, +a `dbt-postgres` maintainer will merge the changes into `main`. + +And that's it! Happy developing :tada: diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..10a79fae --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2024 dbt Labs, Inc. + + 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. diff --git a/README.md b/README.md new file mode 100644 index 00000000..1a127c6c --- /dev/null +++ b/README.md @@ -0,0 +1,39 @@ +# dbt Postgres + +This package is responsible for: + +- defining database connection methods +- caching information from databases +- determining how relations are defined + +There are two major adapter types: base and sql + +# Directories + +## `base` + +Defines the base implementation Adapters can use to build out full functionality. + +## `sql` + +Defines a sql implementation for adapters that initially inherits the base implementation +and comes with some pre-made methods and macros that can be overwritten as needed per adapter. +(most common type of adapter.) + +# Files + +## `cache.py` + +Cached information from the database. + +## `factory.py` + +Defines how we generate adapter objects + +## `protocol.py` + +Defines various interfaces for various adapter objects. Helps mypy correctly resolve methods. + +## `reference_keys.py` + +Configures naming scheme for cache elements to be universal. diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 00000000..ad9a25f9 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,128 @@ +[project] +dynamic = ["version"] +name = "dbt-postgres" +description = "The set of adapter protocols and base functionality that supports integration with dbt-core" +readme = "README.md" +keywords = ["dbt", "adapter", "adapters", "database", "elt", "dbt-core", "dbt Core", "dbt Cloud", "dbt Labs", "postgres"] +requires-python = ">=3.8.0" +authors = [ + { name = "dbt Labs", email = "info@dbtlabs.com" }, +] +maintainers = [ + { name = "dbt Labs", email = "info@dbtlabs.com" }, +] +classifiers = [ + "Development Status :: 2 - Pre-Alpha", + "License :: OSI Approved :: Apache Software License", + "Operating System :: MacOS :: MacOS X", + "Operating System :: Microsoft :: Windows", + "Operating System :: POSIX :: Linux", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", +] +dependencies = [ + "dbt-adapters @ git+https://github.com/dbt-labs/dbt-adapters.git", + "dbt-common @ git+https://github.com/dbt-labs/dbt-common.git", +] +[project.optional-dependencies] +lint = [ + "black", + "flake8", + "Flake8-pyproject", + "mypy", + "types-protobuf", + "types-pytz", +] +test = [ + "pytest", + "pytest-dotenv", + "pytest-xdist", +] + +[project.urls] +Homepage = "https://github.com/dbt-labs/dbt-postgres" +Documentation = "https://docs.getdbt.com" +Repository = "https://github.com/dbt-labs/dbt-postgres.git" +Issues = "https://github.com/dbt-labs/dbt-postgres/issues" +Changelog = "https://github.com/dbt-labs/dbt-postgres/blob/main/CHANGELOG.md" + +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + +[tool.hatch.build.targets.sdist] +exclude = [ + "/.github", + "/.changes", + ".changie.yaml", + ".gitignore", + ".pre-commit-config.yaml", + "CONTRIBUTING.md", + "/tests", +] + +[tool.hatch.build.targets.wheel] +packages = ["dbt.postgres"] + +[tool.hatch.metadata] +# needed for installing `dbt-common` directly from github +allow-direct-references = true + +[tool.hatch.version] +path = "dbt/postgres/__about__.py" + +[tool.hatch.envs.default] +features = ["lint", "test"] +[tool.hatch.envs.default.scripts] +unit-tests = "- python -m pytest {args:tests/unit}" +lint-all = [ + "- lint-black", + "- lint-flake8", + "- lint-mypy", +] +lint-black = "python -m black ." +lint-flake8 = "python -m flake8 ." +lint-mypy = "python -m mypy ." + +[tool.black] +extend-exclude = "dbt/postgres/events/adapter_types_pb2.py" +line-length = 99 +target-version = ['py38'] + +[tool.flake8] +select = ["E", "W", "F"] +ignore = ["E203", "E501", "E741", "W503", "W504"] +exclude = [ + "dbt/postgres/events/adapter_types_pb2.py", + "tests", + "venv", +] +per-file-ignores = ["*/__init__.py: F401"] + +[tool.mypy] +namespace_packages = true +show_error_codes = true +explicit_package_bases = true +ignore_missing_imports = true +pretty = true +mypy_path = "third-party-stubs/" +files = [ + "dbt/postgres", + "tests/unit", +] +exclude = [ + "dbt/postgres/events/adapter_types_pb2.py", + "venv", +] +[[tool.mypy.overrides]] +module = ["dbt.postgres.events.adapter_types_pb2"] +follow_imports = "skip" + +[tool.pytest] +env_files = ["test.env"] +testpaths = [ + "tests/functional", + "tests/unit", +]