diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 7c30e8c..2b55673 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -27,13 +27,13 @@ jobs: --health-retries 5 strategy: matrix: - smalltalk: [ Pharo64-9.0, Pharo64-8.0, Pharo64-7.0 ] + smalltalk: [ Pharo64-10, Pharo64-9.0, Pharo64-8.0, Pharo64-7.0 ] name: ${{ matrix.smalltalk }} steps: - uses: actions/checkout@v2 - uses: hpi-swa/setup-smalltalkCI@v1 with: - smalltalk-version: ${{ matrix.smalltalk }} + smalltalk-image: ${{ matrix.smalltalk }} - run: smalltalkci -s ${{ matrix.smalltalk }} shell: bash timeout-minutes: 1 diff --git a/P3/P3Client.class.st b/P3/P3Client.class.st index c09c7dc..09a896a 100644 --- a/P3/P3Client.class.st +++ b/P3/P3Client.class.st @@ -45,7 +45,7 @@ Now we can query the contents of the simple table we just created. The result is an instance of P3Result - a P3Result('SELECT 2' 2 records 3 colums) + a P3Result('SELECT 2' 2 records 3 columns) P3Result contains 3 elements, results, descriptions & data: - Results is a string (collection of strings for multiple embedded queries) indicating successful execution. @@ -1158,7 +1158,7 @@ P3Client >> verbose: flag [ { #category : #private } P3Client >> withConnection: block [ - "Execute block, code that will use my conneciton. + "Execute block, code that will use my connection. Handle network errors with a retry/reconnection scheme" ^ [ block value "first try" ] diff --git a/P3/P3Error.class.st b/P3/P3Error.class.st index 34dfca8..d0f0c07 100644 --- a/P3/P3Error.class.st +++ b/P3/P3Error.class.st @@ -139,7 +139,7 @@ P3Error >> info: anObject [ { #category : #testing } P3Error >> isLocal [ "Return true when I represent an error inside P3 itself, - as opposed to an error generted by the PostgreSQL server" + as opposed to an error generated by the PostgreSQL server" ^ self code ifNil: [ true "if there is no code, we might have been initialized directly" ] diff --git a/P3/P3ErrorOccurredEvent.class.st b/P3/P3ErrorOccurredEvent.class.st index cc5a940..5e714c3 100644 --- a/P3/P3ErrorOccurredEvent.class.st +++ b/P3/P3ErrorOccurredEvent.class.st @@ -2,7 +2,7 @@ I am P3ErrorOccurredEvent. I am a P3LogEvent. -I represent the occurence of a P3Error or P3Notification. +I represent the occurrence of a P3Error or P3Notification. " Class { #name : #P3ErrorOccurredEvent, diff --git a/P3/P3GeometricObject.class.st b/P3/P3GeometricObject.class.st index 80df9bd..749bf62 100644 --- a/P3/P3GeometricObject.class.st +++ b/P3/P3GeometricObject.class.st @@ -1,6 +1,6 @@ " -I am P3GeometricObject, the abstract superclass for all PostgreSQL geometric data tyoes, -representing two-dimenional spatial objects. +I am P3GeometricObject, the abstract superclass for all PostgreSQL geometric data types, +representing two-dimensional spatial objects. " Class { #name : #P3GeometricObject, diff --git a/P3/P3ISO8601Parser.class.st b/P3/P3ISO8601Parser.class.st index 9b3701a..4712230 100644 --- a/P3/P3ISO8601Parser.class.st +++ b/P3/P3ISO8601Parser.class.st @@ -19,9 +19,9 @@ Class { } { #category : #'instance creation' } -P3ISO8601Parser class >> on: stringOrReadSstream [ +P3ISO8601Parser class >> on: stringOrReadStream [ ^ self new - on: stringOrReadSstream readStream; + on: stringOrReadStream readStream; yourself ] diff --git a/P3/P3LineSegment.class.st b/P3/P3LineSegment.class.st index 4ef39f4..2b3c7f4 100644 --- a/P3/P3LineSegment.class.st +++ b/P3/P3LineSegment.class.st @@ -5,7 +5,7 @@ I am P3LineSegment I am a P3GeometricObject -My internal reperesentation is a start and stop point +My internal representation is a start and stop point " Class { #name : #P3LineSegment, diff --git a/P3/P3PreparedStatement.class.st b/P3/P3PreparedStatement.class.st index f18a2a4..967d920 100644 --- a/P3/P3PreparedStatement.class.st +++ b/P3/P3PreparedStatement.class.st @@ -23,7 +23,7 @@ Select query: statement := client prepare: 'SELECT name, enabled FROM table1 WHERE id = $1'. result := statement query: #( 123 ). -When I'm no longer needed I should be closed so that the PostgreSQL server side resources for this prepared statemed are freed. +When I'm no longer needed I should be closed so that the PostgreSQL server side resources for this prepared statement are freed. See also https://en.wikipedia.org/wiki/Prepared_statement @@ -114,7 +114,7 @@ P3PreparedStatement >> execute: inputRow [ { #category : #public } P3PreparedStatement >> executeBatch: inputRows [ - "Execute this SQL query mutiple (inputRow size) times in a single network roundtrip. + "Execute this SQL query multiple (inputRow size) times in a single network roundtrip. Assume no rows will be returned." inputRows isEmpty diff --git a/P3/P3SCRAM.class.st b/P3/P3SCRAM.class.st index c90b2c1..9be00c2 100644 --- a/P3/P3SCRAM.class.st +++ b/P3/P3SCRAM.class.st @@ -48,7 +48,7 @@ For this reason, my class side store will be reset before each image save. About PostgreSQL's password storage -If you execute 'SELECT rolname,rolpassword FROM pg_authid' with enough priviledges, +If you execute 'SELECT rolname,rolpassword FROM pg_authid' with enough privileges, you can see how PostgreSQL stores passwords. In the case of SCRAM-SHA-256, rolpassword seems to have the following format (using terms used in this implementation): diff --git a/README.md b/README.md index 2368675..08e6502 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ # P3 - P3 is a modern, lean and mean PostgreSQL client for Pharo. [![CI](https://github.com/svenvc/P3/actions/workflows/CI.yml/badge.svg)](https://github.com/svenvc/P3/actions/workflows/CI.yml) @@ -39,7 +38,6 @@ query with parameters. This will give you a P3PreparedStatement instance than yo execute with specific parameters. Polymorphic to this there is also P3FormattedStatement which you create using the #format: message. These work at the textual, client side level. - ## Basic Usage Here is the simplest test that does an actual query, it should return true. @@ -70,7 +68,7 @@ Now we can query the contents of the simple table we just created. The result is an instance of P3Result ```smalltalk - a P3Result('SELECT 2' 2 records 3 colums) + a P3Result('SELECT 2' 2 records 3 columns) ``` P3Result contains 3 elements, results, descriptions & data: @@ -91,14 +89,12 @@ Finally we can clean up. [ client execute: 'DROP TABLE table1' ] ensure: [ client close ] ]. ``` - ## References - https://postgresql.org - https://en.wikipedia.org/wiki/PostgreSQL - https://www.postgresql.org/docs/9.6/static/protocol.html - ## Using Prepared and Formatted Statements Although you are free to create your SQL statements in any way you see fit, @@ -108,15 +104,15 @@ error prone (because you might violate syntax rules) and dangerous (due to SQL i P3 can help here with two mechanisms: prepared and formatted statements. They are mostly polymorphic and use the same template notation. -They allow you to create a statement once, specifying placeholders with $n, +They allow you to create a statement once, specifying placeholders with $n, and execute it once or multiple times with concrete arguments, with the necessary conversions happening automatically. -The difference between the two is that formatted statements are implemented +The difference between the two is that formatted statements are implemented using simple textual substitution on the client side, while prepared statements are evaluated on the server side with full syntax checking, and are executed with more type checks. -Prepared statements are more efficient since the server can do part of its optimalization +Prepared statements are more efficient since the server can do part of its optimization in the prepare phase, saving time on each execution. Here is a transcript of how to use them. First we set up a client and create a test table. @@ -169,7 +165,6 @@ client execute: 'DROP TABLE table1'. client close. ``` - ## Supported Data Types P3 supports most common PostgreSQL types. Here are some tables with the details. @@ -227,27 +222,26 @@ tsvector | text search document | 3614 txid_snapshot | user-level transaction ID snapshot | 2970 xml | XML data | 142 -Additionally, the following 9 common types are also implemented, +Additionally, the following 9 common types are also implemented, with the Pharo class they map to. -Name | Description | Oid | Class +Name | Description | Oid | Class -----|-------------|-----|------ -oid | object identifier | 26 | Integer +oid | object identifier | 26 | Integer name | name | 19 | String bpchar | text | 1042 | String void | void | 2278 | UndefinedObject _bool | boolean array | 1000 | Array _int4 | integer array | 1007 | Array -_text | string array | 1009 | Array +_text | string array | 1009 | Array _varchar | string array | 1015 | Array -_float8 | float array | 1022 | Array +_float8 | float array | 1022 | Array P3 also supports enums. Each enum definition creates a new type. You can send #loadEnums to P3Client to create mappings for all visible enums. When you do a query that results in data of an unknown type you will get an error, -P3 cannot convert typeOid XXX, where XXX is the oid in the pg_type table. - +P3 cannot convert typeOid XXX, where XXX is the oid in the pg_type table. ## Connection and Authentication @@ -256,7 +250,7 @@ supports plain (#connect) and TLS/SSL encrypted (#connectSSL) connections. It is out of the scope of this README to explain how to install and configure an advanced database like PostgreSQL. There is extensive high quality documentation -available convering all aspect of PostgreSQL, see https://postgresql.org +available covering all aspect of PostgreSQL, see https://postgresql.org Out of the box, most PostgreSQL installations do not allow for network connections from other machines, only for local connections. @@ -276,7 +270,6 @@ trust (no password, no authentication), password, md5 and scram-sha-256 work wit Note that for SCRAM-SHA-256 to work, you need to change the password_encryption directive in postgresql.conf to scam-sha-256, restart and reenter all user passwords. - ## Glorp Included is **P3DatabaseDriver**, an interface between Glorp, an advanced object-relational mapper, and P3Client. @@ -299,7 +292,6 @@ Login new yourself. ``` - ## Code loading The default group loads P3Client and its basic dependencies NeoJSON and ZTimestamp @@ -320,7 +312,6 @@ Metacello new load: 'glorp'. ``` - ## Unit tests **P3ClientTest** holds unit tests for the P3 PSQL client. @@ -337,7 +328,6 @@ The minimal being the following: P3ClientTest url: 'psql://sven@localhost'. ``` - ## Logging P3 uses object logging, an advanced form of code instrumentation. @@ -357,7 +347,7 @@ P3LogEvent logToTranscript. Executing the four expressions of the Basic Usage section yields the following output. -``` +```bash 2020-09-21 16:27:57 001 [P3] 63731 #Connect sven@localhost:5432 Trust 2020-09-21 16:27:57 002 [P3] 63731 #Query SELECT 565 AS N 2020-09-21 16:27:57 003 [P3] 63731 #Result SELECT 1, 1 record, 1 colum, 4 ms @@ -377,7 +367,7 @@ Executing the four expressions of the Basic Usage section yields the following o 2020-09-21 16:28:20 016 [P3] 63737 #Connect sven@localhost:5432 Trust 2020-09-21 16:28:20 017 [P3] 63737 #Query SELECT * FROM table1 -2020-09-21 16:28:20 018 [P3] 63737 #Result SELECT 2, 2 records, 3 colums, 2 ms +2020-09-21 16:28:20 018 [P3] 63737 #Result SELECT 2, 2 records, 3 columns, 2 ms 2020-09-21 16:28:20 019 [P3] 63737 #Close 2020-09-21 16:39:52 020 [P3] 63801 #Connect sven@localhost:5432 Trust @@ -388,7 +378,6 @@ Executing the four expressions of the Basic Usage section yields the following o Remember that the information inside the log events can be used to build other applications. - ## Development, Goals, Contributing The main goal of P3 is to be a modern, lean and mean PostgreSQL client for Pharo. @@ -396,8 +385,8 @@ Right now, P3 is functional and usable. The quality of open source software is determined by it being alive, supported and maintained. -The first way to help is to simply use P3 in your projects and tells us about -your successes and the issues that you encounter. +The first way to help is to simply use P3 in your projects and tells us about +your successes and the issues that you encounter. You can ask questions on the Pharo mailing lists. Development happens on GitHub, where you can create issues.