postgresql2 0.5.1+1

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 73

PostgreSQL database driver for Dart

A temporary fork of Greg's PostgreSQL driver using conserved substitution respecting strings and @@ operators, also optimizing the pool implementation aggressivly.

encodeString() supports trimNull to work around the null character issue

Pool.connect() returns as soon as possible when failed to connect to database. Also, it resumes if the connection is back. Caller can detect it as follows:

ex is PostgresqlException
&& const [PE_CONNECTION_TIMEOUT, PE_CONNECTION_CLOSED,
		PE_CONNECTION_FAILED, PE_POOL_STOPPED].contains(ex.exception)

Build Status

Basic usage

Obtaining a connection

var uri = 'postgres://username:password@localhost:5432/database';
connect(uri).then((conn) {
	// ...
});

SSL connections

Set the sslmode to require by appending this to the connection uri. This driver only supports sslmode=require, if sslmode is ommitted the driver will always connect without using SSL.

var uri = 'postgres://username:password@localhost:5432/database?sslmode=require';
connect(uri).then((conn) {
	// ...
});

Querying

conn.query('select color from crayons').toList().then((rows) {
	for (var row in rows) {
		print(row.color); // Refer to columns by name,
		print(row[0]);    // Or by column index.
	}
});

Executing

conn.execute("update crayons set color = 'pink'").then((rowsAffected) {
	print(rowsAffected);
});

Query Parameters

Query parameters can be provided using a map. Strings will be escaped to prevent SQL injection vulnerabilities.

conn.query('select color from crayons where id = @id', {'id': 5})
  .toList()
	.then((result) { print(result); });

conn.execute('insert into crayons values (@id, @color)',
             {'id': 1, 'color': 'pink'})
	.then((_) { print('done.'); });

Closing the connection

You must remember to call Connection.close() when you're done. This won't be done automatically for you.

Conversion of Postgresql datatypes.

Below is the mapping from Postgresql types to Dart types. All types which do not have an explicit mapping will be returned as a String in Postgresql's standard text format. This means that it is still possible to handle all types, as you can parse the string yourself.

     Postgresql type                 Dart type
	boolean                         bool
	int2, int4, int8                int
	float4, float8                  double
	numeric                         String
	timestamp, timestamptz, date    Datetime
	json, jsonb                     Map/List
	All other types                 String

Mapping the results of a query to an object

class Crayon {
	String color;
	int length;
}

conn.query('select color, length from crayons')
	.map((row) => new Crayon()
	                     ..color = row.color
	                     ..length = row.length)
	.toList()
	.then((List<Crayon> crayons) {
		for (var c in crayons) {
			print(c is Crayon);
			print(c.color);
			print(c.length);
		}
	});

Or for an immutable object:

class ImmutableCrayon {
	ImmutableCrayon(this.color, this.length);
	final String color;
	final int length;
}

conn.query('select color, length from crayons')
  .map((row) => new ImmutableCrayon(row.color, row.length))
     .toList()
	.then((List<ImmutableCrayon> crayons) {
		for (var c in crayons) {
			print(c is ImmutableCrayon);
			print(c.color);
			print(c.length);
		}
	});

Query queueing

Queries are queued and executed in the order in which they were queued.

So if you're not concerned about handling errors, you can write code like this:

conn.execute("create table crayons (color text, length int)");
conn.execute("insert into crayons values ('pink', 5)");
conn.query("select color from crayons").single.then((crayon) {
	print(crayon.color); // prints 'pink'
});

Query streaming

Connection.query() returns a Stream of results. You can use each row as soon as it is received, or you can wait till they all arrive by calling Stream.toList().

Connection pooling

In server applications, a connection pool can be used to avoid the overhead of obtaining a connection for each request.

import 'package:postgresql2/pool.dart';

main() {
  var uri = 'postgres://username:password@localhost:5432/database';
  var pool = new Pool(uri, minConnections: 2, maxConnections: 5);
  pool.messages.listen(print);
  pool.start().then((_) {
    print('Min connections established.');
    pool.connect().then((conn) { // Obtain connection from pool
      conn.query("select 'oi';")
        .toList()
        .then(print)
        .then((_) => conn.close()) // Return connection to pool
        .catchError((err) => print('Query error: $err'));
    });
  });
}

Example program

Add postgresql to your pubspec.yaml file, and run pub install.

name: postgresql_example
dependencies:
  postgresql: any
import 'package:postgresql2/postgresql.dart';

void main() {
  var uri = 'postgres://testdb:password@localhost:5432/testdb';
  var sql = "select 'oi'"; 
  connect(uri).then((conn) {
    conn.query(sql).toList()
    	.then((result) {
    		print('result: $result');
    	})
    	.whenComplete(() {
    		conn.close();
    	});
  });
}

Testing

To run the unit tests you will need to create a database, and edit 'test/config.yaml' accordingly.

Creating a database for testing

Change to the postgres user and run the administration commands.

sudo su postgres
createuser --pwprompt testdb
  Enter password for new role: password
  Enter it again: password
  Shall the new role be a superuser? (y/n) n
  Shall the new role be allowed to create databases? (y/n) n
  Shall the new role be allowed to create more new roles? (y/n) n
createdb --owner testdb testdb
exit

Check that it worked by logging in.

psql -h localhost -U testdb -W

Enter "\q" to quit from the psql console.

License

BSD

http://www.postgresql.org/docs/9.2/static/index.html http://www.dartlang.org/

Who Uses

  • Quire - a simple, collaborative, multi-level task management tool.
  • Keikai - a sophisticated spreadsheet for big data

Version 0.3.4

  • Update broken crypto dependency.

Version 0.3.3

  • Fix #73 Properly encode/decode connection uris. Thanks to Martin Manev.
  • Permit connection without a password. Thanks to Jirka Daněk.

Version 0.3.2

  • Improve handing of datetimes. Thanks to Joe Conway.
  • Remove manually cps transformed async code.
  • Fix #58: Establish connections concurrently. Thanks to Tom Yeh.
  • Fix #67: URI encode db name so spaces can be used in db name. Thanks to Chad Schwendiman.
  • Fix #69: Empty connection pool not establishing connections.

Version 0.3.1+1

  • Expose column information via row.getColumns(). Credit to Jesper Håkansson for this change.

Version 0.3.0

  • A new connection pool with more configuration options.
  • Support for json and timestamptz types.
  • Utc time zone support.
  • User customisable type conversions.
  • Improved error handling.
  • Connection.onClosed has been removed.
  • Some api has been renamed, the original names are still functional but marked as deprecated.
    • import 'package:postgresql/postgresql_pool.dart' => import 'package:postgresql/pool.dart'
    • Pool.destroy() => Pool.stop()
    • The constants were upper case and int type. Now typed and lower camel case to match the style guide.
    • Connection.unhandled => Connection.messages
    • Connection.transactionStatus => Connection.transactionState

Thanks to Tom Yeh and Petar Sabev for their helpful feedback.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  postgresql2: ^0.5.1+1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or flutter packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:postgresql2/constants.dart';
import 'package:postgresql2/pool.dart';
import 'package:postgresql2/postgresql.dart';
  
Version Uploaded Documentation Archive
0.5.1+1 Aug 23, 2018 Go to the documentation of postgresql2 0.5.1+1 Download postgresql2 0.5.1+1 archive
0.5.1 Aug 10, 2018 Go to the documentation of postgresql2 0.5.1 Download postgresql2 0.5.1 archive
0.5.0 Aug 9, 2018 Go to the documentation of postgresql2 0.5.0 Download postgresql2 0.5.0 archive
0.3.4+5 May 18, 2018 Go to the documentation of postgresql2 0.3.4+5 Download postgresql2 0.3.4+5 archive
0.3.4+4 Jan 11, 2018 Go to the documentation of postgresql2 0.3.4+4 Download postgresql2 0.3.4+4 archive
0.3.4+3 Jul 11, 2017 Go to the documentation of postgresql2 0.3.4+3 Download postgresql2 0.3.4+3 archive
0.3.4+2 Jul 11, 2017 Go to the documentation of postgresql2 0.3.4+2 Download postgresql2 0.3.4+2 archive
0.3.4+1 Apr 12, 2017 Go to the documentation of postgresql2 0.3.4+1 Download postgresql2 0.3.4+1 archive
0.3.4 Feb 23, 2017 Go to the documentation of postgresql2 0.3.4 Download postgresql2 0.3.4 archive
0.3.3+6 Feb 23, 2017 Go to the documentation of postgresql2 0.3.3+6 Download postgresql2 0.3.3+6 archive

All 24 versions...

Popularity:
Describes how popular the package is relative to other packages. [more]
63
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
60
Overall:
Weighted score of the above. [more]
73
Learn more about scoring.

We analyzed this package on Dec 5, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.1.0
  • pana: 0.12.7

Platforms

Detected platforms: Flutter, other

Platform components identified in package: io.

Health suggestions

Fix lib/src/postgresql_impl/connection.dart. (-0.50 points)

Analysis of lib/src/postgresql_impl/connection.dart reported 1 hint:

line 263 col 9: Equality operator == invocation with references of unrelated types.

Format lib/constants.dart.

Run dartfmt to format lib/constants.dart.

Format lib/pool.dart.

Run dartfmt to format lib/pool.dart.

Fix additional 14 files with analysis or formatting issues.

Additional issues in the following files:

  • lib/postgresql.dart (Run dartfmt to format lib/postgresql.dart.)
  • lib/src/buffer.dart (Run dartfmt to format lib/src/buffer.dart.)
  • lib/src/duration_format.dart (Run dartfmt to format lib/src/duration_format.dart.)
  • lib/src/mock/mock.dart (Run dartfmt to format lib/src/mock/mock.dart.)
  • lib/src/mock/mock_socket_server.dart (Run dartfmt to format lib/src/mock/mock_socket_server.dart.)
  • lib/src/pool_impl.dart (Run dartfmt to format lib/src/pool_impl.dart.)
  • lib/src/pool_settings_impl.dart (Run dartfmt to format lib/src/pool_settings_impl.dart.)
  • lib/src/postgresql_impl/constants.dart (Run dartfmt to format lib/src/postgresql_impl/constants.dart.)
  • lib/src/postgresql_impl/messages.dart (Run dartfmt to format lib/src/postgresql_impl/messages.dart.)
  • lib/src/postgresql_impl/query.dart (Run dartfmt to format lib/src/postgresql_impl/query.dart.)
  • lib/src/postgresql_impl/settings.dart (Run dartfmt to format lib/src/postgresql_impl/settings.dart.)
  • lib/src/postgresql_impl/type_converter.dart (Run dartfmt to format lib/src/postgresql_impl/type_converter.dart.)
  • lib/src/protocol.dart (Run dartfmt to format lib/src/protocol.dart.)
  • lib/src/substitute.dart (Run dartfmt to format lib/src/substitute.dart.)

Maintenance issues and suggestions

Use constrained dependencies. (-20 points)

The pubspec.yaml contains 2 dependencies without version constraints. Specify version ranges for the following dependencies: convert, crypto.

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package. Common file name patterns include: main.dart, example.dart or you could also use postgresql2.dart.

The description is too long. (-10 points)

Search engines will display only the first part of the description. Try to keep it under 180 characters.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev <3.0.0
convert >=1.0.0 2.0.2
crypto >=2.0.0 2.0.6
Transitive dependencies
charcode 1.1.2
collection 1.14.11
typed_data 1.1.6
Dev dependencies
test any
yaml any